412 lines
14 KiB
Markdown
412 lines
14 KiB
Markdown
# 阶段 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 依赖
|
||
必须参考以下"唯一真源"：
|
||
- [会话记录](file:///d:\idea_demo\datai\docs\sessions\YYYY-MM-DD-00X-session.md) - 阶段 9 更新的会话记录
|
||
- [项目规则](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
|
||
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - 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`
|
||
|
||
### 工具命令速查
|
||
```powershell
|
||
# 添加所有变更
|
||
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. 询问用户是否需要进行其他操作
|
||
|
||
通过这种方式，确保用户对整个执行过程有清晰的了解和控制，提高用户的满意度和参与度。 |