kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
refactor-20260121
datai/docs/skill/phase10-code-commit.md

14 KiB
Raw Permalink Blame History

阶段 10：代码提交技能书

A. 元数据 (Metadata)

name: phase10-code-commit

description: 在 Datai 项目中，基于已完成的复盘和 API 文档，提交代码到本地仓库，询问用户是否提交到远程仓库，并更新索引和会话记录。此技能确保代码的可管理性和版本控制。

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

触发关键词

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

  • "代码提交"、"提交代码"、"git commit"
  • "进入阶段 10"、"下一阶段"
  • "git"、"commit"、"push"

触发场景

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

操作路径

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

  • 检查: 所有生成的代码文件
  • 检查: 所有生成的文档文件
  • 执行: git 命令（add, commit, push）
  • 更新: docs/index.md（记录代码提交信息）
  • 更新: docs/sessions/YYYY-MM-DD-00X-session.md
  • 读取: .trae/rules/project_rules.md (项目规则)
  • 读取: docs/Prompt/0004-单一真源文档驱动架构师.md (SSOT 架构师提示词)

SSOT 依赖

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

C. 核心指令集 (Instructions)

架构约束

1. 代码检查约束（强制）

  • 必须检查所有生成的代码文件
  • 必须检查所有生成的文档文件
  • 确保代码文件符合项目规范
  • 确保文档文件符合项目规范

2. 提交信息约束（强制）

  • 提交信息格式：feat: [需求编号] 需求描述
  • 示例：feat: [001] 实现用户登录功能
  • 提交信息必须清晰、准确，描述本次提交的主要内容

3. 本地提交约束（强制）

  • 必须使用 git add 添加所有变更
  • 必须使用 git commit 提交到本地仓库
  • 确保所有文件都已添加到提交中

4. 远程提交约束（强制）

  • 必须询问用户是否提交到远程仓库
  • 如果用户确认，使用 git push 推送到远程
  • 如果用户不确认，跳过推送

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

  • 必须在提交代码后更新 docs/index.md
  • 必须记录代码提交信息
  • 采用增量更新策略，严禁删除现有内容

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

  • 必须更新 docs/sessions/YYYY-MM-DD-00X-session.md
  • 必须更新当前阶段为"阶段 10：代码提交"
  • 必须记录代码提交信息
  • 必须标记需求为已完成

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

步骤 1：代码和文档检查（Let's think step by step）

在提交代码前，必须执行以下检查：

  1. 检查所有生成的代码文件

    • 确认代码文件的路径和命名是否符合项目规范
    • 确认代码文件的内容是否符合项目规范
    • 确认代码文件是否包含单元测试
    • 确认代码文件是否通过编译和测试

  2. 检查所有生成的文档文件

    • 确认文档文件的路径和命名是否符合项目规范
    • 确认文档文件的内容是否符合项目规范
    • 确认文档文件之间的引用是否正确
    • 确认文档文件是否完整、准确

  3. 确认提交信息

    • 确定提交信息的格式：feat: [需求编号] 需求描述
    • 确保提交信息清晰、准确
    • 确保提交信息描述了本次提交的主要内容

步骤 2：提交代码到本地

  1. 添加所有变更

    • 使用 git add . 添加所有变更到暂存区
    • 或使用 git add <file> 添加特定文件到暂存区
    • 确保所有生成的代码文件和文档文件都已添加

  2. 提交到本地仓库

    • 使用 git commit -m "feat: [需求编号] 需求描述" 提交到本地仓库
    • 确保提交信息符合项目规范
    • 确保提交成功

步骤 3：询问用户是否提交到远程

  1. 向用户询问

    • 显示本地提交的信息
    • 询问："是否需要提交到远程仓库？"

  2. 根据用户反馈执行

    • 如果用户确认，使用 git push 推送到远程仓库
    • 如果用户不确认，跳过推送
    • 确保推送成功（如果执行）

步骤 4：更新索引

  1. 读取现有索引

    • 使用 Read 工具读取 docs/index.md
    • 找到"代码提交记录"部分
    • 如果不存在，则创建该部分

  2. 添加代码提交信息

    • 在"代码提交记录"部分追加新的提交信息
    • 格式：- YYYY-MM-DD: [提交信息] - [本地/远程]
    • 示例：- 2026-01-21: feat: [001] 实现用户登录功能 - 本地+远程

  3. 保存索引

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

步骤 5：更新会话记录

  1. 读取现有会话记录

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

  2. 更新阶段 10 信息

    • 更新"当前阶段"为"阶段 10：代码提交"
    • 更新"阶段 10：代码提交"的状态为"已完成"
    • 添加代码提交信息
    • 标记需求为已完成

  3. 保存会话记录

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

步骤 6：确认与总结

  1. 向用户确认

    • 显示代码提交的结果
    • 显示更新后的索引链接
    • 显示更新后的会话记录链接
    • 询问："代码是否已提交到本地？"
    • 询问："是否需要提交到远程仓库？"（如果尚未询问）

  2. 总结本次执行

    • 总结本次执行的主要内容
    • 总结生成的文档和代码
    • 总结遇到的问题和解决方案
    • 总结学到的经验和教训

工具调用

必须使用的工具

  1. RunCommand 工具：执行 git 命令

    • 使用场景：添加变更、提交到本地、推送到远程
    • 命令：RunCommand(command="git add .", blocking=true, requires_approval=false, target_terminal="new")
    • 命令：RunCommand(command="git commit -m \"feat: [001] 实现用户登录功能\""), blocking=true, requires_approval=false, target_terminal="new")`
    • 命令：RunCommand(command="git push", blocking=true, requires_approval=false, target_terminal="new")

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

    • 使用场景：读取索引、会话记录
    • 命令：Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

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

    • 使用场景：更新索引、更新会话记录
    • 命令：Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

可选使用的工具

  1. TodoWrite 工具：管理任务

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

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

    • 使用场景：检查代码的语法错误和类型错误
    • 命令：GetDiagnostics()

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

常见错误（Anti-Patterns）

错误 1：不检查代码和文档就提交

错误示例：

AI：直接执行 git add .
AI：直接执行 git commit
AI：完成

问题：

  • 没有检查代码和文档的正确性
  • 可能提交错误的代码或文档
  • 违反了项目规则

正确示例：

AI：检查所有生成的代码文件
AI：检查所有生成的文档文件
AI：确认代码和文档符合项目规范
AI：执行 git add .
AI：执行 git commit
AI：完成

错误 2：提交信息不符合规范

错误示例：

AI：git commit -m "完成功能"

问题：

  • 提交信息过于简单
  • 没有遵循项目规范的提交信息格式
  • 其他开发人员无法快速了解提交的内容

正确示例：

AI：git commit -m "feat: [001] 实现用户登录功能"

错误 3：不询问用户就推送到远程

错误示例：

AI：执行 git add .
AI：执行 git commit
AI：直接执行 git push
AI：完成

问题：

  • 违反了项目规则
  • 没有尊重用户的决策权
  • 可能导致不必要的远程分支污染

正确示例：

AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：如果用户确认，执行 git push
AI：完成

错误 4：不更新索引和会话记录

错误示例：

AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：完成（忘记更新索引和会话记录）

问题：

  • 违反了项目规则
  • 索引中没有记录代码提交信息
  • 会话记录中没有记录代码提交信息
  • 其他开发人员无法快速了解代码提交情况

正确示例：

AI：执行 git add .
AI：执行 git commit
AI：询问用户是否提交到远程仓库
AI：更新索引，记录代码提交信息
AI：更新会话记录，记录代码提交信息
AI：完成

验收清单（Checklist）

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

代码和文档检查

  • 已检查所有生成的代码文件
  • 已检查所有生成的文档文件
  • 代码文件的路径和命名符合项目规范
  • 代码文件的内容符合项目规范
  • 代码文件包含单元测试
  • 代码文件通过编译和测试
  • 文档文件的路径和命名符合项目规范
  • 文档文件的内容符合项目规范
  • 文档文件之间的引用正确
  • 文档文件完整、准确

本地提交检查

  • 已使用 git add 添加所有变更
  • 已使用 git commit 提交到本地仓库
  • 提交信息格式符合要求：feat: [需求编号] 需求描述
  • 提交信息清晰、准确
  • 所有文件都已添加到提交中

远程提交检查

  • 已询问用户是否提交到远程仓库
  • 如果用户确认，已使用 git push 推送到远程
  • 如果执行了推送，推送成功

索引更新检查

  • docs/index.md 已更新
  • 已记录代码提交信息
  • 索引更新采用增量更新策略，未删除现有内容

会话记录更新检查

  • 会话记录已更新
  • 会话记录的"当前阶段"已更新为"阶段 10：代码提交"
  • 会话记录的"阶段 10：代码提交"状态已更新为"已完成"
  • 会话记录包含代码提交信息
  • 会话记录标记需求为已完成

用户确认检查

  • 已向用户显示代码提交的结果
  • 已向用户显示更新后的索引链接
  • 已向用户显示更新后的会话记录链接
  • 已询问用户"代码是否已提交到本地？"
  • 已询问用户"是否需要提交到远程仓库？"（如果尚未询问）

Correct vs Incorrect 代码对比

Incorrect（错误示例）

AI：直接执行 git add .
AI：git commit -m "完成登录功能"
AI：直接执行 git push
AI：完成

Correct（正确示例）

AI：检查所有生成的代码文件和文档文件
AI：确认代码和文档符合项目规范
AI：git add .
AI：git commit -m "feat: [001] 实现用户登录功能"
AI：询问用户是否提交到远程仓库
AI：如果用户确认，git push
AI：更新 docs/index.md，记录代码提交信息
AI：更新会话记录，记录代码提交信息并标记需求为已完成
AI：向用户确认代码提交结果
AI：完成

附录：快速参考

文件路径速查

  • 主索引：docs/index.md
  • 会话记录：docs/sessions/YYYY-MM-DD-00X-session.md
  • 项目规则：.trae/rules/project_rules.md
  • SSOT 架构师提示词：docs/Prompt/0004-单一真源文档驱动架构师.md

工具命令速查

# 添加所有变更
RunCommand(command="git add .", blocking=true, requires_approval=false, target_terminal="new")

# 提交到本地仓库
RunCommand(command="git commit -m \"feat: [001] 实现用户登录功能\"")`, blocking=true, requires_approval=false, target_terminal="new")`

# 推送到远程仓库
RunCommand(command="git push", blocking=true, requires_approval=false, target_terminal="new")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

阶段 10 输出清单

  • 代码提交到本地仓库
  • 代码推送到远程仓库（如果用户确认）
  • 更新的索引：docs/index.md
  • 更新的会话记录：docs/sessions/YYYY-MM-DD-00X-session.md

项目完成总结

当完成阶段 10 后，整个 SSOT 流程即告完成。此时，你已经：

  1. 需求定义与入库：创建了需求文档，建立了需求追踪
  2. 方案设计：创建设计文档，明确了技术方案
  3. 方案决策：创建决策记录，记录了架构决策
  4. 数据库结构生成：生成 SQL 脚本，记录了数据库变更
  5. 提示词生成：生成针对当前需求的提示词
  6. 执行代码生成：根据需求和设计生成了代码
  7. 记录当前会话：完整记录了当前会话的所有信息
  8. 变更记录与归档：创建了变更日志，记录了所有变更
  9. 闭环复盘和接口文档：创建了复盘文档和 API 文档
  10. 代码提交：提交代码到本地仓库，并询问是否提交到远程

通过严格执行 SSOT 流程，确保了所有开发活动都有文档依据，提高了代码的可追溯性、可维护性和质量。同时，通过复盘和 API 文档，确保了项目的持续改进和 API 的可文档化。

最终确认

当完成所有 10 个阶段后，你可以向用户提供最终确认，包括：

  1. 总结本次执行的主要内容
  2. 列出所有生成的文档和代码
  3. 询问用户是否对整个执行过程满意
  4. 询问用户是否需要进行其他操作

通过这种方式，确保用户对整个执行过程有清晰的了解和控制，提高用户的满意度和参与度。