多项目开发规范 CLAUDE.md

1. 多项目开发规范 CLAUDE.md

Claude Code 多项目开发规范配置文件，含数据库操作规范、API 规范、Git 流程

Prompt

# 项目开发规范

> **重要**: 本文档是 Claude Code 的强制规范，必须严格遵守！

## 项目结构

quitsmoking/ └── buffett/ # 巴菲特百科（独立项目） ├── frontend/ # 前端 (Vue 3 + Vite + TypeScript) ├── backend/ # 后端 (Go-Zero) └── database/ # 数据库 SQL 文件

## 项目技术栈

| 项目 | 技术栈 | 数据库 | 说明 |
|------|--------|--------|------|
| **buffett/backend** | Go 1.24 + Go-Zero | db_buffettwiki | 巴菲特百科后端 API |
| **buffett/frontend** | Vue 3 + Vite + TypeScript + Pinia | - | 巴菲特百科前端 |

## API 域名配置

### 线上环境

| 项目 | 线上域名 | 说明 |
|------|---------|------|
| **buffett/backend** | `https://api.notionso.cn` | 巴菲特百科 API |

### 本地开发

| 项目 | 本地地址 | 启动方式 |
|------|---------|---------|
| **buffett/backend** | `http://localhost:9502` | 在 `buffett/backend` 目录运行 `go run .` |
| **buffett/frontend** | `http://localhost:5173` | 在 `buffett/frontend` 目录运行 `npm run dev` |

### API 路径

| 功能 | 完整 URL 示例 |
|------|--------------|
| 巴菲特百科 | `https://api.notionso.cn/api/v1/buffett/xxx` |

---

## 开发前必读

### 0. 同步开发配置（最先执行！）

> **⚠️ 每次开发前必须先同步最新配置！**

在进行任何开发工作之前，**必须先执行以下命令**同步最新的开发配置文件：

```bash
git clone -b main git@codeup.aliyun.com:675456e82d6be1de501d334f/claudemd.git /tmp/claudemd && cp /tmp/claudemd/{CLAUDE.md,.mcp.json} . && rm -rf /tmp/claudemd

命令说明：

• 从远程仓库克隆最新的配置文件到临时目录
• 将 CLAUDE.md 和 .mcp.json 复制到当前项目根目录
• 清理临时目录

为什么必须执行：

• 确保使用最新的开发规范
• 同步最新的 MCP 数据库连接配置
• 避免因配置过期导致的开发问题

Claude Code 必须遵守：

1. 在用户要求开发任何功能时，首先执行此同步命令
2. 如果同步失败，必须告知用户并暂停开发
3. 同步成功后再继续后续步骤

1. 强制创建分支（非常重要！）

⚠️ 绝对禁止在没有创建分支的情况下修改代码！

在修改 buffett 项目代码之前，必须先执行以下步骤：

# 步骤1: 进入对应项目目录
cd 项目目录

# 步骤2: 检查是否是 git 仓库
git status

# 步骤3: 如果不是 git 仓库，也就不存在 .git 文件，则先初始化，否则不需要初始化
git init

# 步骤4: 创建并切换到新分支（分支命名规范见下方）
git checkout -b feat_yymmdd_hh

# 步骤5: 确认当前分支
git branch

分支命名格式：feat_yymmdd_hh

• 示例：feat_260106_14 表示 2026年1月6日 14点创建的分支

违反此规则的后果：

• 直接在 main/master 分支修改代码可能导致无法回滚
• 代码冲突时难以解决
• 无法追溯修改历史

Claude Code 必须遵守：

1. 在用户要求修改任何项目代码时，首先检查 git 状态
2. 如果不在功能分支上，必须先询问用户是否创建新分支，并明确告知用户
3. 只有在用户明确同意后，才能继续修改代码

2. 重要规则

⚠️ buffett/frontend 前端规则

• frontend 目录仅做前端，禁止在该目录中编写后端代码
• 所有数据必须从后端 API 获取，前端禁止硬编码业务数据
• 如果后端 API 不存在，必须先在 buffett/backend 中开发对应接口

⚠️ buffett/backend 后端规则

• API 前缀统一为 /api/v1/buffett/xxx
• 主 API 文件为 buffett_standalone.api，模块 API 文件在 buffett/ 子目录
• 禁止直接修改 types/types.go 文件

3. Git 分支规范

分支命名

feat_yymmdd_hh

• feat - 功能分支前缀
• yymmdd - 年月日（如 260105 表示 2026年1月5日）
• hh - 小时（24小时制）

示例：feat_260105_20 表示 2026年1月5日 20点创建的功能分支

提交规范

git commit -am "具体开发了哪些功能"

合并流程

功能分支直接 push 到远程：

git push -u origin feat_260105_20

数据库操作规范（极其重要）

绝对禁止的操作

1. 禁止执行 DROP 语句

   -- 绝对禁止
   DROP TABLE xxx;
   DROP DATABASE xxx;

2. 禁止执行不带 WHERE 条件的 DELETE 语句

   -- 绝对禁止
   DELETE FROM table_name;
   
   -- 必须带 WHERE 条件
   DELETE FROM table_name WHERE id = 1;

3. 禁止执行不带 WHERE 条件的 UPDATE 语句

   -- 绝对禁止
   UPDATE table_name SET column = value;
   
   -- 必须带 WHERE 条件
   UPDATE table_name SET column = value WHERE id = 1;

4. 禁止 TRUNCATE 语句

   -- 绝对禁止
   TRUNCATE TABLE xxx;

数据库修改流程

1. 查询前：先执行 SELECT 确认数据存在
2. 修改前：先备份相关数据或确认影响范围（SELECT COUNT）
3. 修改时：必须带 WHERE 条件，且先用 LIMIT 1 测试
4. 修改后：验证修改结果

防止数据丢失的强制规则

1. DELETE 操作必须遵循的步骤

-- 步骤1: 先查看要删除的数据（必须执行）
SELECT * FROM table_name WHERE [条件];

-- 步骤2: 确认影响行数（必须执行）
SELECT COUNT(*) FROM table_name WHERE [条件];

-- 步骤3: 如果超过10条，必须先询问用户确认
-- 步骤4: 执行删除时必须加 LIMIT（首次建议 LIMIT 1 测试）
DELETE FROM table_name WHERE [条件] LIMIT 1;

-- 步骤5: 确认无误后再删除剩余数据

2. UPDATE 操作必须遵循的步骤

-- 步骤1: 先查看要更新的数据（必须执行）
SELECT * FROM table_name WHERE [条件];

-- 步骤2: 确认影响行数（必须执行）
SELECT COUNT(*) FROM table_name WHERE [条件];

-- 步骤3: 批量更新超过10条时，必须先询问用户确认
-- 步骤4: 首次更新建议加 LIMIT 1 测试
UPDATE table_name SET column = value WHERE [条件] LIMIT 1;

3. 优先使用软删除

-- ✅ 推荐：软删除（修改状态）
UPDATE table_name SET status = -1 WHERE id = 1;

-- ⚠️ 谨慎：物理删除（真正删除数据）
DELETE FROM table_name WHERE id = 1;

4. 批量操作限制

• 批量 INSERT: 单次不超过 100 条，超过需分批
• 批量 UPDATE: 单次不超过 50 条，超过需分批并确认
• 批量 DELETE: 单次不超过 10 条，超过必须用户确认

5. 关联数据检查

-- 删除父记录前，必须检查是否有子记录
-- 例：删除分类前检查是否有关联的规则
SELECT COUNT(*) FROM bs_rules WHERE category_id = [要删除的分类ID];

-- 如果有子记录，必须先询问用户如何处理

6. 禁止的高危操作

• ❌ 禁止 ALTER TABLE DROP COLUMN（删除列）
• ❌ 禁止 ALTER TABLE MODIFY 缩小字段长度
• ❌ 禁止删除有外键关联的父记录（未处理子记录时）
• ❌ 禁止在生产数据上直接执行未经测试的 SQL

数据库连接

表命名规范

db_buffettwiki 核心表说明

常用字段约定

buffett/backend 后端开发规范（Go-Zero）

核心原则

1. API First: 所有接口变更必须先修改 .api 文件
2. 自动生成: 严格使用 goctl 生成代码，禁止手动修改生成文件
3. 禁止直接修改 types/types.go 文件

目录结构

buffett/backend/
├── buffett_standalone.api          # 主 API 入口文件
├── buffett/                        # 模块 API 定义文件
│   ├── categories.api              # 大师分类
│   ├── rules.api                   # 原则
│   └── chat.api                    # AI 聊天
│
├── handler/                        # HTTP 处理器
│   ├── categories/                 # 大师分类 handler
│   ├── rules/                      # 原则 handler
│   └── chat/                       # 聊天 handler
│
├── logic/                          # 业务逻辑
│   ├── categories/                 # 大师分类 logic
│   ├── rules/                      # 原则 logic
│   └── chat/                       # 聊天 logic
│
├── types/types.go                  # 类型定义（自动生成，禁止手改）
└── etc/
    └── api.local.yaml              # 本地配置

API 路由规范

API 文件示例

规则 API 文件 (buffett/rules.api)

syntax = "v1"

// 结构体命名加 Bs 前缀
type BsRulesListRequest {
    CategoryId int64  `form:"category_id,optional"`
    TagId      int64  `form:"tag_id,optional"`
    Keyword    string `form:"keyword,optional"`
    Page       int64  `form:"page,default=1"`
    PageSize   int64  `form:"page_size,default=20"`
}

type BsRulesListResponse {
    List  []BsRulesItem `json:"list"`
    Total int64         `json:"total"`
}

@server(
    group:  buffett/rules
    prefix: /api/v1/buffett/rules
)
service api {
    @doc "获取规则列表"
    @handler GetRulesList
    get /list (BsRulesListRequest) returns (BsRulesListResponse)
}

代码生成命令

# API 代码生成（在 buffett/backend 目录下执行）
goctl api go -api buffett_standalone.api -dir . -style=go_zero

配置文件

etc/api.local.yaml  # 本地配置

JSON 处理

统一使用 github.com/tidwall/gjson 处理 JSON 数据

buffett/frontend 前端开发规范（Vue 3 + Vite）

目录结构

buffett/frontend/
├── src/
│   ├── api/                    # API 请求层
│   │   ├── categories.ts       # 大师分类 API
│   │   ├── rules.ts            # 原则 API
│   │   └── chat.ts             # 聊天 API
│   │
│   ├── components/             # 复用组件
│   │   └── HelloWorld.vue
│   │
│   ├── views/                  # 页面视图
│   │   ├── Home.vue            # 首页
│   │   ├── Master.vue          # 大师详情
│   │   └── Principle.vue       # 原则详情
│   │
│   ├── stores/                 # Pinia 状态管理
│   │   └── master.ts
│   │
│   ├── router/                 # Vue Router
│   │   └── index.ts
│   │
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts
│   │
│   ├── utils/                  # 工具函数
│   │   └── request.ts          # axios 封装
│   │
│   ├── assets/styles/          # 样式文件
│   │
│   ├── App.vue
│   └── main.ts
│
├── public/                     # 静态资源
├── index.html
├── vite.config.ts
├── tsconfig.app.json
└── package.json

API 调用规范

• 所有数据必须从后端 API 获取，前端禁止硬编码业务数据
• 使用统一的 HTTP 请求封装 (src/utils/request.ts)
• 如果后端 API 不存在，必须先在 buffett/backend 中开发对应接口

后端接口开发流程

1. 确认前端需要的数据
2. 检查 buffett/backend 是否已有对应接口
3. 如无接口，在 buffett/backend/buffett/ 下新增或修改 .api 文件
4. 使用 goctl 生成代码
5. 实现 logic 层业务逻辑
6. 前端调用新接口

API 响应格式规范

统一响应结构

{
    "code": 200,
    "message": "操作成功",
    "data": { ... }
}

响应码说明

响应方法（Go 代码）

// 成功响应
response.Success(w, data)                          // code=200, msg="操作成功"
response.SuccessWithMessage(w, data, "自定义消息")  // 自定义消息

// 错误响应
response.Error(w, 401, "用户未登录")
response.Error(w, 500, "服务器内部错误")

JWT 认证规范

Token 传递方式

通过 HTTP Header 传递，格式为 Bearer Token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token 过期时间

Token Claims 结构

{
    "iat": 1704067200,        // 签发时间（Unix 时间戳）
    "exp": 1735603200,        // 过期时间（Unix 时间戳）
    "uid": "user-uuid-string" // 用户标识
}

在业务逻辑中获取用户信息

// 从 context 获取已认证的用户 ID
uid, ok := l.ctx.Value("uid").(string)
if !ok || uid == "" {
    return nil, errors.New("用户未认证")
}

认证中间件

代码修改原则

1. 最小改动原则：只修改必要的代码，不做不必要的重构
2. 先理解后修改：修改前先阅读理解现有代码逻辑
3. 保持一致性：遵循项目现有的代码风格和规范
4. 测试验证：修改后进行必要的测试验证
5. 数据安全：重构时确保现有功能不变，数据不丢失

检查清单

开发完成前请确认：

• 已执行配置同步命令（同步 CLAUDE.md 和 .mcp.json）
• 已创建功能分支（格式：feat_yymmdd_hh）
• 巴菲特百科后端代码写在 buffett/backend/ 目录下
• 巴菲特百科 API 前缀是 /api/v1/buffett/xxx
• 未在 buffett/frontend 中编写后端代码
• 前端数据通过 API 获取，无硬编码业务数据
• 数据库操作带有 WHERE 条件
• 未执行任何 DROP/TRUNCATE 语句
• 绝对不能直接修改 types/types.go 文件
• API 变更先修改了 .api 文件
• 代码风格与现有代码一致