datai/docs/skill/phase6-code-generation.md

阶段 6：执行代码生成技能书

A. 元数据 (Metadata)

name: phase6-code-generation

description: 在 Datai 项目中，基于已创建的需求文档、设计文档、决策记录和提示词，生成符合项目规范的代码文件，创建参考代码文档和实施方案文档，并更新索引和会话记录。此技能确保代码生成的准确性和规范性。

---

B. 触发与定位 (Triggers & Scope)

触发关键词

当用户输入包含以下关键词时，必须觉醒此技能：

• "执行代码生成"、"生成代码"、"代码生成"
• "参考代码"、"实施方案"
• "进入阶段 6"、"下一阶段"
• "代码"、"实现"、"开发"

触发场景

• 用户确认阶段 5 完成，要求进入阶段 6
• 用户要求生成代码
• 用户询问如何执行代码生成
• 用户提到"按照项目规则"或"SSOT 流程"进行代码生成

操作路径

此技能涉及以下文件和目录的操作：

• 读取: docs/requirements/YYYY-MM-DD-00X-需求名.md (阶段 1 创建的需求文档)
• 读取: docs/design/YYYY-MM-DD-00X-设计名.md (阶段 2 创建的设计文档)
• 读取: docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md (阶段 3 创建的决策记录)
• 读取: docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md (阶段 5 创建的提示词)
• 创建: 项目目录下的 Java 代码文件（根据提示词要求）
• 创建: docs/reference-code/YYYY-MM-DD-00X-code-功能名.md
• 创建: docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md
• 更新: docs/index.md
• 更新: docs/design/YYYY-MM-DD-00X-设计名.md (添加代码实现引用)
• 更新: docs/sessions/YYYY-MM-DD-00X-session.md
• 读取: .trae/rules/project_rules.md (项目规则)
• 读取: docs/Prompt/0004-单一真源文档驱动架构师.md (SSOT 架构师提示词)

SSOT 依赖

必须参考以下"唯一真源"：

• 需求文档 - 阶段 1 创建的需求文档
• 设计文档 - 阶段 2 创建的设计文档
• 决策记录 - 阶段 3 创建的决策记录
• 提示词 - 阶段 5 创建的提示词
• project_rules.md - 项目规则和阶段定义
• 0004-单一真源文档驱动架构师.md - SSOT 架构师提示词

---

C. 核心指令集 (Instructions)

架构约束

1. 代码生成约束（强制）

• 必须严格按照阶段 5 生成的提示词要求生成代码
• 必须遵循 Spring Boot 最佳实践
• 必须遵循若依框架规范
• 必须使用 MyBatis Plus 进行数据库操作（如果需要）
• 必须使用指定的包结构和文件路径
• 必须包含单元测试

2. 参考代码文档约束（强制）

• 必须在 docs/reference-code/ 目录下创建参考代码文档
• 文档命名：YYYY-MM-DD-00X-code-功能名.md
• 必须包含关键代码片段和说明
• 必须包含代码的使用方法和注意事项

3. 实施方案文档约束（强制）

• 必须在 docs/implementation/ 目录下创建实施方案文档
• 文档命名：YYYY-MM-DD-00X-implementation-功能名.md
• 必须包含实施步骤和注意事项
• 必须包含部署说明和验证方法

4. 索引更新约束（强制）

• 必须在生成代码和文档后立即更新 docs/index.md
• 必须更新设计文档，添加代码实现引用
• 采用增量更新策略，严禁删除现有内容
• 索引链接格式：[文档名](./相对路径/文件名.md)
• 必须在 docs/index.md 中添加到"参考代码"和"实施方案"部分

5. 会话记录约束（强制）

• 必须更新 docs/sessions/YYYY-MM-DD-00X-session.md
• 必须更新当前阶段为"阶段 6：执行代码生成"
• 必须记录生成的代码文件列表
• 必须记录参考代码和实施方案文档链接
• 必须记录 AI 的质疑、替代方案以及最终的复现步骤

业务逻辑 SOP（标准操作流程）

步骤 1：代码生成分析（Let's think step by step）

在生成代码前，必须执行以下分析：

1. 分析需求和设计文档

   • 读取阶段 1 创建的需求文档
   • 读取阶段 2 创建的设计文档
   • 读取阶段 3 创建的决策记录
   • 明确需求的核心功能和非功能需求
   • 明确设计的技术方案和架构

2. 确定需要生成的代码文件

   • 读取阶段 5 创建的提示词
   • 明确需要生成的代码文件类型和路径
   • 明确代码规范和测试要求

3. 遵循 Spring Boot 最佳实践

   • 明确 Spring Boot 的代码结构和规范
   • 明确若依框架的代码结构和规范
   • 明确 MyBatis Plus 的使用规范

步骤 2：首句申明

在生成代码前，必须明确当前"现状"与"目标"：

现状：已完成需求定义、方案设计、方案决策、数据库结构生成和提示词生成
目标：根据提示词生成符合项目规范的代码文件，创建参考代码文档和实施方案文档

步骤 3：加载阶段 5 准备的 Prompt，观察输出

1. 加载提示词

   • 读取阶段 5 创建的提示词
   • 按照提示词的要求生成代码

2. 生成代码

   • 生成 Java 代码文件
   • 保存到对应的项目目录
   • 确保代码符合项目规范
   • 确保代码包含单元测试

3. 观察输出

   • 记录 AI 的质疑
   • 记录替代方案
   • 记录最终的复现步骤

步骤 4：创建参考代码文档

1. 确定文档路径

   • 路径：docs/reference-code/YYYY-MM-DD-00X-code-功能名.md
   • 使用 Write 工具创建文件
   • 确保目录存在（使用 LS 工具检查）

2. 填充文档内容

   • 元数据：包含需求编号、创建时间、创建人、状态等
   • 功能概述：描述功能的核心内容
   • 代码结构：描述生成的代码文件结构
   • 关键代码片段：包含核心功能的代码片段
   • 使用方法：描述代码的使用方法
   • 注意事项：描述代码的注意事项

3. 文档质量检查

   • 使用 Read 工具读取刚创建的文档
   • 检查是否符合参考代码文档约束
   • 检查代码片段是否正确
   • 检查使用方法是否清晰

步骤 5：创建实施方案文档

1. 确定文档路径

   • 路径：docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md
   • 使用 Write 工具创建文件
   • 确保目录存在（使用 LS 工具检查）

2. 填充文档内容

   • 元数据：包含需求编号、创建时间、创建人、状态等
   • 实施概述：描述实施的核心内容
   • 实施步骤：描述实施的详细步骤
   • 注意事项：描述实施的注意事项
   • 部署说明：描述部署的方法和步骤
   • 验证方法：描述验证的方法和步骤

3. 文档质量检查

   • 使用 Read 工具读取刚创建的文档
   • 检查是否符合实施方案文档约束
   • 检查实施步骤是否清晰
   • 检查部署说明是否详细

步骤 6：更新索引和设计文档

1. 读取现有索引

   • 使用 Read 工具读取 docs/index.md
   • 找到"参考代码"和"实施方案"部分
   • 如果不存在，则创建这些部分

2. 添加新文档链接

   • 在"参考代码"部分追加新参考代码

   • 格式：- [参考代码名](./reference-code/YYYY-MM-DD-00X-code-功能名.md) - [描述]

   • 示例：- [用户登录功能参考代码](./reference-code/2026-01-21-001-code-用户登录功能.md) - 用户登录功能的参考代码

   • 在"实施方案"部分追加新实施方案

   • 格式：- [实施方案名](./implementation/YYYY-MM-DD-00X-implementation-功能名.md) - [描述]

   • 示例：- [用户登录功能实施方案](./implementation/2026-01-21-001-implementation-用户登录功能.md) - 用户登录功能的实施方案

3. 更新设计文档

   • 使用 Read 工具读取设计文档
   • 在"相关文档"部分添加代码实现引用
   • 格式：- [参考代码](../reference-code/YYYY-MM-DD-00X-code-功能名.md)
   • 格式：- [实施方案](../implementation/YYYY-MM-DD-00X-implementation-功能名.md)
   • 使用 Write 工具更新设计文档

4. 保存索引

   • 使用 Write 工具更新 docs/index.md
   • 严禁删除现有内容，只追加新内容

步骤 7：更新会话记录

1. 读取现有会话记录

   • 使用 Read 工具读取 docs/sessions/YYYY-MM-DD-00X-session.md

2. 更新阶段 6 信息

   • 更新"当前阶段"为"阶段 6：执行代码生成"
   • 更新"阶段 6：执行代码生成"的状态为"已完成"
   • 添加生成的代码文件列表
   • 添加参考代码和实施方案文档链接
   • 记录 AI 的质疑、替代方案以及最终的复现步骤

3. 保存会话记录

   • 使用 Write 工具更新会话记录

步骤 8：确认与询问

1. 向用户确认

   • 显示生成的代码文件列表
   • 显示参考代码和实施方案文档的链接
   • 询问："代码是否正确？"
   • 询问："是否进入下一阶段（记录当前会话）？"

2. 等待用户反馈

   • 如果用户不满意，询问具体需要修改的地方
   • 如果用户要求回退，执行回退机制（见错误陷阱部分）
   • 如果用户确认，标记阶段 6 为已完成，准备进入阶段 7

工具调用

必须使用的工具

1. Read 工具：读取现有文件

   • 使用场景：读取需求文档、设计文档、决策记录、提示词、索引、会话记录
   • 命令：Read(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md")

2. Write 工具：创建或更新文件

   • 使用场景：生成代码文件、创建参考代码文档、创建实施方案文档、更新索引、更新设计文档、更新会话记录
   • 命令：Write(file_path="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java", content="...")

3. LS 工具：检查目录是否存在

   • 使用场景：创建文档前检查 docs/reference-code/ 和 docs/implementation/ 目录
   • 命令：LS(path="d:\\idea_demo\\datai\\docs")

4. RunCommand 工具：运行代码验证

   • 使用场景：运行单元测试验证代码正确性
   • 命令：RunCommand(command="mvn test", blocking=true, requires_approval=false, target_terminal="new")

可选使用的工具

1. SearchCodebase 工具：搜索现有代码

   • 使用场景：查找现有代码作为参考
   • 命令：SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类")

2. GetDiagnostics 工具：获取代码诊断

   • 使用场景：检查代码的语法错误和类型错误
   • 命令：GetDiagnostics(uri="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java")

3. TodoWrite 工具：管理任务

   • 使用场景：跟踪阶段执行进度
   • 命令：TodoWrite(todos=[...])

---

D. 错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误（Anti-Patterns）

错误 1：不按提示词要求生成代码

错误示例：

AI：读取提示词，要求生成 Controller、Service、Mapper、Entity
AI：只生成了 Controller 和 Service，没有生成 Mapper 和 Entity

问题：

• 没有按照提示词要求生成所有代码文件
• 违反了阶段 5 生成的提示词约束

正确示例：

AI：读取提示词，要求生成 Controller、Service、Mapper、Entity
AI：按照提示词要求，生成了所有代码文件
AI：确保代码符合提示词的代码规范和测试要求

错误 2：不包含单元测试

错误示例：

AI：生成代码，不包含单元测试
AI：违反了提示词的测试要求

正确示例：

AI：生成代码，包含单元测试
AI：确保单元测试覆盖率不低于 80%
AI：确保测试用例包含正常场景和异常场景

错误 3：代码不符合项目规范

错误示例：

// 违反若依框架规范的代码
public class loginController {
    public String login(String username, String password) {
        // 代码逻辑
    }
}

问题：

• 类名不符合规范（首字母小写，驼峰命名错误）
• 方法参数不符合规范（没有使用 DTO 类）
• 没有使用若依框架的注解
• 没有异常处理

正确示例：

// 符合若依框架规范的代码
@RestController
@RequestMapping("/system/auth")
public class SysLoginController {
    @Autowired
    private SysLoginService loginService;

    @PostMapping("/login")
    public AjaxResult login(@RequestBody LoginBody loginBody) {
        // 代码逻辑
        return AjaxResult.success(token);
    }
}

错误 4：不创建参考代码文档和实施方案文档

错误示例：

AI：生成代码
AI：更新索引和会话记录
AI：完成（忘记创建参考代码文档和实施方案文档）

问题：

• 违反了阶段 6 的要求
• 缺少代码的参考文档和实施方案

正确示例：

AI：生成代码
AI：创建参考代码文档
AI：创建实施方案文档
AI：更新索引和会话记录
AI：完成

错误 5：不更新设计文档的代码实现引用

错误示例：

AI：生成代码
AI：创建参考代码文档和实施方案文档
AI：更新 docs/index.md
AI：完成（忘记更新设计文档）

正确示例：

AI：生成代码
AI：创建参考代码文档和实施方案文档
AI：更新 docs/index.md
AI：更新设计文档，添加代码实现引用
AI：完成

错误 6：不询问用户确认就进入下一阶段

错误示例：

AI：生成代码
AI：进入阶段 7：记录当前会话（未询问用户）

正确示例：

AI：生成代码
AI：代码已生成，参考代码和实施方案文档已创建
AI：代码是否正确？
AI：是否进入下一阶段（记录当前会话）？

验收清单（Checklist）

在完成阶段 6 前，必须检查以下项目：

代码生成检查

• 已按照提示词要求生成所有代码文件
• 代码文件保存到了正确的项目目录
• 代码符合 Spring Boot 最佳实践
• 代码符合若依框架规范
• 代码符合 MyBatis Plus 使用规范
• 代码包含单元测试
• 单元测试覆盖率不低于 80%
• 测试用例包含正常场景和异常场景
• 代码没有语法错误和类型错误

参考代码文档检查

• 参考代码文档已创建在 docs/reference-code/ 目录下
• 文档命名符合 YYYY-MM-DD-00X-code-功能名.md 格式
• 文档包含元数据
• 文档包含功能概述
• 文档包含代码结构
• 文档包含关键代码片段
• 文档包含代码的使用方法和注意事项

实施方案文档检查

• 实施方案文档已创建在 docs/implementation/ 目录下
• 文档命名符合 YYYY-MM-DD-00X-implementation-功能名.md 格式
• 文档包含元数据
• 文档包含实施概述
• 文档包含实施步骤
• 文档包含注意事项
• 文档包含部署说明
• 文档包含验证方法

索引更新检查

• docs/index.md 已更新
• 新参考代码链接已添加到"参考代码"部分
• 新实施方案链接已添加到"实施方案"部分
• 索引链接格式正确：[文档名](./相对路径/文件名.md)
• 索引更新采用增量策略，未删除现有内容

设计文档更新检查

• 设计文档已更新
• 设计文档的"相关文档"部分已添加参考代码和实施方案引用
• 引用格式正确：[参考代码](../reference-code/YYYY-MM-DD-00X-code-功能名.md)

会话记录更新检查

• 会话记录已更新
• 会话记录的"当前阶段"已更新为"阶段 6：执行代码生成"
• 会话记录的"阶段 6：执行代码生成"状态已更新为"已完成"
• 会话记录包含生成的代码文件列表
• 会话记录包含参考代码和实施方案文档链接
• 会话记录包含 AI 的质疑、替代方案以及最终的复现步骤

用户确认检查

• 已向用户显示生成的代码文件列表
• 已向用户显示参考代码和实施方案文档的链接
• 已询问用户"代码是否正确？"
• 已询问用户"是否进入下一阶段？"
• 已等待用户反馈

回退机制检查（如果需要）

• 如果用户不满意，已询问具体需要修改的地方
• 如果用户要求回退，已删除相关代码文件
• 如果用户要求回退，已删除参考代码文档和实施方案文档
• 如果用户要求回退，已撤销索引更新
• 如果用户要求回退，已撤销设计文档更新
• 如果用户要求回退，已更新会话记录

Correct vs Incorrect 代码对比

Incorrect（错误示例）

// 违反若依框架规范的代码
public class loginController {
    public String login(String username, String password) {
        // 简单的用户名密码验证
        if ("admin".equals(username) && "123456".equals(password)) {
            return "success";
        } else {
            return "failure";
        }
    }
}

Correct（正确示例）

// 符合若依框架规范的代码
@RestController
@RequestMapping("/system/auth")
public class SysLoginController {
    private static final Logger log = LoggerFactory.getLogger(SysLoginController.class);

    @Autowired
    private SysLoginService loginService;

    /**
     * 登录方法
     * 
     * @param loginBody 登录信息
     * @return 结果
     */
    @PostMapping("/login")
    public AjaxResult login(@RequestBody LoginBody loginBody) {
        AjaxResult ajax = AjaxResult.success();
        // 生成令牌
        String token = loginService.login(loginBody.getUsername(), loginBody.getPassword(), loginBody.getCode(),
                loginBody.getUuid());
        ajax.put(Constants.TOKEN, token);
        return ajax;
    }
}

---

附录：快速参考

文件路径速查

• 需求文档：docs/requirements/YYYY-MM-DD-00X-需求名.md
• 设计文档：docs/design/YYYY-MM-DD-00X-设计名.md
• 决策记录：docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md
• 提示词：docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md
• 参考代码文档：docs/reference-code/YYYY-MM-DD-00X-code-功能名.md
• 实施方案文档：docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md
• 主索引：docs/index.md
• 会话记录：docs/sessions/YYYY-MM-DD-00X-session.md
• 项目规则：.trae/rules/project_rules.md
• SSOT 架构师提示词：docs/Prompt/0004-单一真源文档驱动架构师.md

工具命令速查

# 读取提示词
Read(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md")

# 生成代码文件
Write(file_path="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java", content="...")

# 创建参考代码文档
Write(file_path="d:\\idea_demo\\datai\\docs\\reference-code\\2026-01-21-001-code-用户登录功能.md", content="...")

# 创建实施方案文档
Write(file_path="d:\\idea_demo\\datai\\docs\\implementation\\2026-01-21-001-implementation-用户登录功能.md", content="...")

# 运行单元测试
RunCommand(command="mvn test", blocking=true, requires_approval=false, target_terminal="new")

# 检查代码诊断
GetDiagnostics(uri="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java")

阶段 6 输出清单

• 代码文件：项目目录下的 Java 文件
• 参考代码文档：docs/reference-code/YYYY-MM-DD-00X-code-功能名.md
• 实施方案文档：docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md
• 更新的索引：docs/index.md
• 更新的设计文档：docs/design/YYYY-MM-DD-00X-设计名.md
• 更新的会话记录：docs/sessions/YYYY-MM-DD-00X-session.md

下一阶段提示

如果用户确认进入下一阶段，请参考：

• project_rules.md 的"阶段 7：记录当前会话"
• 准备回顾整个会话过程
• 准备更新会话记录
• 准备更新索引