技术文档转代码 Skill

核心原则

最重要的工作原则：

1. 严格按文档实现 – 文档和实际代码有冲突时，明确告知用户
2. 分步实现，每步确认 – 不一次性实现全部，分批次编写，每步检查确认
3. 代码禁止 Mock – 只允许在数据库表中 Mock 数据
4. 外部接口标记 TODO – 涉外部接口时，标记为 TODO 但完成其他部分
5. 功能完整实现 – 慎重使用 TODO，完成后告知有哪些 TODO
6. 慎重删除/回滚 – 需要时必须让用户确认

触发条件

当用户提供技术文档并要求根据文档编写代码时激活此 Skill：

• “根据文档生成代码”
• “按技术方案写代码”
• “帮我实现这个功能”
• “根据需求文档写代码”

完整工作流

第一阶段：制定实施计划

Claude必须做的：

1. 研究项目现状

   • 查看后端项目结构（Controller、Service、DAO、Entity 放置位置）
   • 查看前端项目结构（页面、组件、API 封装方式）
   • 识别需要复用的工具类和组件
   • 必须引用项目实际代码作为依据

2. 阅读技术文档

   • 理解整体设计
   • 识别需要实现的模块

3. 制定分步计划

   • 结合项目实际结构，制定切实可行的计划
   • 按以下建议顺序安排：

     步骤1：共用核心模块（数据库表 → 实体类）
     步骤2：功能一涉及的接口
     步骤3：功能一涉及的页面
     步骤4：功能二涉及的接口
     步骤5：功能二涉及的页面
     ...
     

4. 向用户展示计划（包含项目现状调研结果），确认后开始实施

示例：

我已研究项目现状并阅读技术文档，制定实施计划如下：

【项目调研结果】
- 后端：cm-statis，参考 CvActivity.java、StatisMain.java
- 前端：wk_x_h5，参考 views/survey/、api/survey.js

【实施计划（共5步）】
步骤1：共用核心模块（数据库表 + 实体类）
步骤2：功能一接口（Controller + Service + Mapper）
步骤3：功能一页面（首页 + 分析页）
步骤4：功能二接口（Controller + Service + Mapper）
步骤5：功能二页面（列表 + 上传）

是否按此计划执行？(y/n)

第二阶段：分步代码实现

每步实现流程：

1. 编写前明确

   • 说明本步骤要实现的内容
   • 列出需要编写的文件清单
   • 明确使用的技术栈
   • 说明复用的现有模块/组件

2. 编写代码

   • 基于项目现有代码结构实现
   • 遵循项目编码规范
   • 引用现有代码作为参考

3. 编译验证

   • 使用 run-in-container skill 编译代码
   • 确认编译无错误后再进入下一步

4. 展示确认

   • 展示完成的代码和文件清单
   • 询问是否确认进入下一步

编写代码时的原则：

• 复用现有模块 – 优先使用项目已有的 utils、tools、components、entity、mapper 等
• 遵循项目规范 – 代码风格、命名规范与现有代码一致
• 引用实际代码 – 说明参考了哪些现有文件

示例：

步骤1：共用核心模块

【文件】sql + 2个实体类
【技术栈】Java 8 + MyBatis + MySQL 5.6
【复用】参考 CvActivity.java、cv_activity 表结构
[编译中...] ✅ 编译成功

第三阶段：接口验证（CURL命令）

Claude应该做的：

1. 为每个接口生成 CURL 命令
2. 方便用户测试接口

示例：

curl -X POST "http://localhost:8080/api/culture-value/analyze" \
  -H "Authorization: Bearer {token}" \
  -d '{"content": "测试文本", "sourceType": "ARCHIVE"}'

第四阶段：多轮验证

Claude应该做的：

1. 邀请用户提问，验证实现是否符合需求
2. 按功能模块逐一验证
3. 回答是否在代码中体现，并说明位置
4. 需要调整时，先让用户确认再修改

示例：

Q: 保存后是否会触发分词？
A: 已实现，位置：CultureValueServiceImpl.analyzeAndSaveWord()

Q: 外部接口如何处理？
A: 已标记 TODO，需补充真实接口地址

第五阶段：编译运行

Claude应该做的：

1. 如需要编译，使用 run-in-container skill
2. 验证代码能够正常编译

示例：

编译验证...
[调用 run-in-container skill 编译]

✅ 编译成功，未发现错误

可以进入下一步了。

技术约束

除非用户明确要求，否则遵循以下限制：

Java 后端

技术组件要求：
- Java 8
- MySQL 5.6
- 禁止使用：数据库外键、数据库约束
- ORM：MyBatis
- 分页：PageHelper

注意事项：
- 复用现有项目的 request 封装、响应封装、分页处理
- 使用 LOGIN_USER 类获取当前用户信息
- 表必须有逻辑删除字段（deleted）

前端 Vue

技术组件要求：
- Vue 3 + TypeScript
- Element Plus（参考 package.json）
- request.js 封装

注意事项：
- 文件上传：前端直传 OSS，后端只记录 URL
- 复用现有组件

数据源处理

重要提示：

• 如需求文档指定数据源（如 xuehai），查询时使用对应数据源
• SQL 文件放置在 haierren-server/docs/sql/ 目录下
• 数据库连接使用 database-query skill

特殊处理

外部接口

对于外部接口（如第三方 API）：
1. 在代码中标记 // TODO: 待实现
2. 说明需要补充的信息（接口地址、参数等）
3. 提供默认的模拟数据或空实现
4. 列出所有 TODO，供用户后续补充

表结构变更

对于已存在的表，需要变更结构时：
1. 生成 ALTER TABLE SQL
2. 放置在本次生成的 SQL 文件中
3. 说明变更内容和影响

禁止行为

绝对不要：

1. 一次性实现全部 – 必须分步，每步确认
2. 代码中 Mock 数据 – 只允许数据库 Mock
3. 随意使用 TODO – 功能应完整实现
4. 删除/回滚代码 – 需要时必须确认
5. 忽略文档冲突 – 有冲突必须告知用户

文件命名规范

输出清单

每步完成后，向用户说明：

✅ 步骤X完成
📁 新建：3个后端文件 + 1个前端文件
📝 修改：Mapper.xml
🔧 TODO：外部分词服务、OSS上传

与其他 Skill 的配合

成功标准

1. 计划经用户确认后执行
2. 每步代码经用户确认后进入下一步
3. 代码编译通过
4. 所有 TODO 已列出，用户已知晓
5. 实现的功能符合需求文档

核心信念：稳步推进，每步确认。准确实现比快速交付更重要。