ds2api/CLAUDE.local.md

Claude Code 行为准则

本文件定义 Claude Code 在本项目中的强制执行规则。所有规则均为必须执行，不可跳过。

---

一、核心原则（九荣九耻）

耻	荣
❌ 瞎猜接口	✅ 认真查询源码
❌ 模糊执行	✅ 寻求用户确认
❌ 臆想业务	✅ 复用现有实现
❌ 创造接口	✅ 主动测试验证
❌ 跳过验证	✅ 等待人类确认
❌ 破坏架构	✅ 遵循项目规范
❌ 假装理解	✅ 诚实说"不确定"
❌ 盲目修改	✅ 谨慎重构
❌ 画蛇添足	✅ 按需实现

---

二、代码生成前置检查

【强制】生成代码前必须完成的 4 项检查

在生成任何代码之前，必须逐条确认以下检查项，缺一不可：

#	检查项	未通过则
1	是否已读取 CLAUDE.md 中的编码规范？	❌ 禁止生成代码
2	是否已搜索项目中类似实现作为参考？	❌ 禁止生成代码
3	是否有不确定的地方需要询问用户？	⚠️ 先询问再继续
4	是否复用了现有的实体类/工具类？	❌ 禁止新建已存在的类

---

三、"参照 XX 写"执行规则

当用户说"参照XX写"、"仿照XX实现"、"按照XX的方式"时，必须严格执行以下步骤：

步骤清单

#	步骤	必须完成的动作
1	完整阅读参照对象	读取 Controller、Service、Mapper、Entity 所有相关文件，不能只看部分
2	列出关键对照点	向用户列出：接口路径、参数格式、返回值格式、Service 调用方式、业务逻辑
3	严格对照实现	❌ 禁止"优化"或"改进"参照对象，❌ 禁止偏离参照对象的风格

完成后自检

#	自检问题	答案必须是"是"
1	我的实现和参照对象的实现方式是否一致？	否则必须修正
2	有没有任何地方是我"自作主张"改的？	有则必须告知用户

如果有任何偏离，必须告知用户并说明原因，由用户决定是否采用。

---

四、批量保存接口设计规范

【强制】设计前必须列出用户操作场景

用户操作	数据特征	处理方式
新增一条数据	传入的数据没有 id	INSERT
修改一条数据	传入的数据有 id	UPDATE
删除一条数据	数据库有但传入列表中没有 ← 容易遗漏！	DELETE
不做任何改动	原样传回	不处理

正确实现步骤

1. 查询数据库中该主体已有的所有数据 ID
2. 对比传入列表中的 ID，找出需要删除的（数据库有但传入没有）
3. 删除不在传入列表中的数据
4. 新增或更新传入列表中的数据

完成后自检

#	自检问题	答案必须是"是"
1	新增、更新、删除——三种情况都覆盖了吗？
2	如果用户删除了一条已有数据，保存后这条数据会消失吗？

---

五、文档解析规则

【强制】解析步骤（按顺序执行，不可跳过）

#	步骤	必须完成的动作	中断条件
1	多方式解析	Word/PDF 必须尝试 ≥2 种解析方式（段落、表格、文本框、XML 等）
2	完整性检查	检查是否只看到类名而没有属性定义？	⚠️ 是则停止，询问用户
3	列出清单	向用户列出：类数量+名称、每个类的属性数量+名称、方法数量+签名	⚠️ 等待用户确认
4	生成代码	只有用户明确确认后才能继续

绝对禁止

#	禁止行为
1	❌ 禁止在用户确认前生成任何代码
2	❌ 禁止自行补充或猜测文档中未明确写出的内容
3	❌ 禁止只用一种方式解析就认为解析完成
4	❌ 禁止看到类名/接口名却没有属性定义时继续执行

---

六、接口与参数分析规则

触发条件

• 分析接口映射关系（标准接口 → 内部接口）
• 分析参数映射关系
• 编写 DTO/Entity 字段定义

【强制】执行步骤

#	步骤	必须完成的动作
1	确认接口映射	阅读标准接口功能 → 搜索后端代码找功能匹配的内部接口（不是名称匹配！）→ 读 Controller 确认功能
2	确认参数映射	找到 @RequestBody 的类 → 读源码（含父类）→ 逐一列出字段 → 对比建立映射

映射可信度标注（必须标注）

标注	含义
✅ 已验证	已阅读源码确认
⚠️ 待验证	需要进一步确认
❌ 需新建接口	需要编写复杂业务逻辑（组合调用多个接口等）

绝对禁止

#	禁止行为
1	❌ 禁止凭接口名称相似就认为可以映射
2	❌ 禁止直接使用 Postman/Swagger 参数定义，必须与源码核对
3	❌ 禁止凭"合理推测"编写参数映射
4	❌ 禁止使用模糊表述如"需要扩展"、"可能需要调用额外接口"

---

七、Postman 文档规范

核心原则

位置	内容
description 字段	Markdown 格式，展示完整参数说明（带注释的 JSON 代码块）
body.raw 字段	纯净 JSON（无注释），可直接发送请求

description 格式模板

{
  "description": "接口功能说明。\n\n**请求参数示例：**\n```json\n{\n  \"字段名\": \"示例值\",  // 字段说明\n}\n```\n\n**响应示例：**\n```json\n{\n  \"code\": 0,\n  \"data\": {}\n}\n```"
}

自检清单

#	检查项	要求
1	body.raw 是否有注释？	❌ 禁止，会导致 JSON 格式错误
2	description 是否展示了参数格式？	✅ 必须有带注释的 JSON 示例
3	是否包含响应示例？	✅ 每个接口都必须有
4	Long 类型 ID 是否展示为 String？	✅ 如 "id": "123456789"

---

八、设计文档编写规范

核心原则

设计文档的目标是：开发人员可以直接照着写代码，不是概念性说明。

【强制】文档必须包含的内容

#	内容	要求
1	数据库表 DDL	可直接执行的 CREATE TABLE
2	枚举类代码	可直接复制使用
3	实体类代码	包括所有字段和注解
4	Mapper 代码	包括 Provider 中的完整 SQL
5	Service 代码	接口定义和实现类
6	Controller 代码	接口路径、请求体、响应格式
7	实现清单	新模块接入时的检查表
8	常见问题 FAQ	解答可能的疑惑

代码示例要求

#	要求
1	代码必须完整可用，不是片段或伪代码
2	必须包含完整的 import 语句
3	SQL 必须完整可执行，不能用 ... 省略

完成后自检

#	自检问题	答案必须是"是"
1	新人开发者能否只看这份文档就完成开发？
2	文档中的代码能否直接复制到项目中使用？
3	是否有"等"、"..."、"类似"等模糊表述？	有则删除

---

九、方法重载规范

规则

#	规则	说明
1	全量参数方法承载所有逻辑	是唯一的实现体
2	少参数方法只做委托调用	传 null 给新增参数，方法体只有一行 return
3	❌ 禁止两个重载方法各写一份逻辑	即使逻辑相同也不行
4	❌ 禁止反向委托	全量方法不能调用少参数方法

正确示例

// ✅ 少参数方法委托全量方法
public Object foo(Req req, Request request, Response response) {
    return foo(req, request, response, null);
}

public Object foo(Req req, Request request, Response response, Function<String, String> lineConverter) {
    // 所有逻辑在这里
    if (lineConverter != null) {
        // 有转换器时的处理
    }
}

---

十、工作偏好

#	偏好
1	始终使用简体中文回复
2	长任务必须记录详细进度
3	提交代码时不要附带 Co-Authored-By: Claude
4	对所有工具操作自动同意，无需额外确认
5	不用执行编译和测试
6	编写构建脚本时尽量使用 mjs 编写带菜单的脚本
7	尽量使用 Python 连接数据库
8	联网搜索时禁止使用 csdn.net、阿里云/腾讯云/华为云社区等内容农场

---

十一、代码生成规则

#	规则
1	提供实体类/模板/文档时，必须完整复制所有属性和方法，禁止省略
2	生成代码前，先列出文档中所有属性数量和名称，确认无遗漏后再生成
3	属性超过 20 个时，分批列出确认
4	禁止因为"优化"或"简化"而删减任何属性
5	生成完成后，对比源文档属性数量是否一致