682 lines
28 KiB
Markdown
682 lines
28 KiB
Markdown
# 阶段 9：闭环复盘和接口文档技能书
|
||
|
||
## A. 元数据 (Metadata)
|
||
|
||
**name**: `phase9-retro-api-docs`
|
||
|
||
**description**: 在 Datai 项目中，基于已完成的变更记录，创建复盘文档和 API 文档，总结整个需求执行过程，包括成功经验、改进点、问题分析等，并记录 API 接口的设计和实现，更新索引和会话记录。此技能确保项目的持续改进和 API 的可文档化。
|
||
|
||
---
|
||
|
||
## B. 触发与定位 (Triggers & Scope)
|
||
|
||
### 触发关键词
|
||
当用户输入包含以下关键词时，必须觉醒此技能：
|
||
- "复盘"、"复盘文档"、"Retrospective"
|
||
- "API 文档"、"接口文档"
|
||
- "进入阶段 9"、"下一阶段"
|
||
- "总结"、"文档"、"回顾"
|
||
|
||
### 触发场景
|
||
- 用户确认阶段 8 完成，要求进入阶段 9
|
||
- 用户要求创建复盘文档和 API 文档
|
||
- 用户询问如何进行复盘
|
||
- 用户提到"按照项目规则"或"SSOT 流程"进行复盘和 API 文档编写
|
||
|
||
### 操作路径
|
||
此技能涉及以下文件和目录的操作：
|
||
- **读取**: `docs/sessions/YYYY-MM-DD-00X-session.md` (阶段 8 更新的会话记录)
|
||
- **创建**: `docs/retros/YYYY-MM-DD-00X-retro.md`
|
||
- **创建**: `docs/api-docs/YYYY-MM-DD-00X-api.md`
|
||
- **更新**: `docs/index.md`
|
||
- **更新**: `docs/requirements/YYYY-MM-DD-00X-需求名.md` (添加复盘和 API 文档引用)
|
||
- **更新**: `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) - 阶段 8 更新的会话记录
|
||
- [项目规则](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. 复盘文档约束（强制）
|
||
- 必须在 `docs/retros/` 目录下创建复盘文档
|
||
- 文档命名：`YYYY-MM-DD-00X-retro.md`
|
||
- 必须使用复盘文档模板
|
||
- 必须包含元数据、复盘概述、成功经验、改进点、问题分析、行动计划、相关文档等章节
|
||
- 必须对比目标与实际产出
|
||
- 必须提取模式：记录 3 条有效的 Prompt 技巧和 3 个避免的坑
|
||
- 必须进行模板迭代：如果发现模板不适用，立即执行一次"模板更新"
|
||
|
||
#### 2. API 文档约束（强制）
|
||
- 必须在 `docs/api-docs/` 目录下创建 API 文档
|
||
- 文档命名：`YYYY-MM-DD-00X-api.md`
|
||
- 必须使用 API 文档模板
|
||
- 必须包含元数据、API 概述、接口列表、错误码、相关文档等章节
|
||
- 必须详细描述每个接口的请求方式、请求路径、请求参数、响应参数、示例等
|
||
|
||
#### 3. 索引更新约束（强制）
|
||
- 必须在创建复盘和 API 文档后立即更新 `docs/index.md`
|
||
- 必须更新需求文档，添加复盘和 API 文档引用
|
||
- 采用增量更新策略，**严禁**删除现有内容
|
||
- 索引链接格式：`[文档名](./相对路径/文件名.md)`
|
||
|
||
#### 4. 会话记录约束（强制）
|
||
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
|
||
- 必须更新当前阶段为"阶段 9：闭环复盘和接口文档"
|
||
- 必须记录复盘和 API 文档链接
|
||
|
||
### 业务逻辑 SOP（标准操作流程）
|
||
|
||
#### 步骤 1：复盘分析（Let's think step by step）
|
||
在创建复盘文档前，必须执行以下分析：
|
||
|
||
1. **回顾整个需求执行过程**
|
||
- 从阶段 1 到阶段 8 的完整过程
|
||
- 识别每个阶段的执行情况
|
||
- 识别成功的经验和失败的教训
|
||
|
||
2. **识别成功经验**
|
||
- 哪些做法是成功的，值得推广
|
||
- 哪些决策是正确的，带来了好的结果
|
||
- 哪些工具和方法是有效的
|
||
|
||
3. **识别改进点**
|
||
- 哪些地方可以改进
|
||
- 哪些决策可以优化
|
||
- 哪些工具和方法可以改进
|
||
|
||
4. **分析问题**
|
||
- 执行过程中遇到了哪些问题
|
||
- 问题的根源是什么
|
||
- 如何避免这些问题再次发生
|
||
|
||
5. **制定行动计划**
|
||
- 针对改进点和问题，制定具体的行动计划
|
||
- 明确责任人和时间节点
|
||
|
||
6. **提取模式**
|
||
- 记录 3 条有效的 Prompt 技巧
|
||
- 记录 3 个避免的坑
|
||
|
||
7. **模板迭代**
|
||
- 检查当前使用的模板是否适用
|
||
- 如果发现模板不适用，立即执行一次"模板更新"
|
||
|
||
#### 步骤 2：创建复盘文档
|
||
1. **确定文档路径**
|
||
- 路径：`docs/retros/YYYY-MM-DD-00X-retro.md`
|
||
- 使用 Write 工具创建文件
|
||
- 确保目录存在（使用 LS 工具检查）
|
||
|
||
2. **填充文档内容**
|
||
- **元数据**：包含需求编号、创建时间、创建人等
|
||
- **复盘概述**：简述本次复盘的目的和范围
|
||
- **成功经验**：记录 3-5 条成功经验
|
||
- **改进点**：记录 3-5 个改进点
|
||
- **问题分析**：记录 2-3 个主要问题及其分析
|
||
- **行动计划**：记录针对改进点和问题的行动计划
|
||
- **相关文档**：添加需求文档链接
|
||
|
||
3. **文档质量检查**
|
||
- 使用 Read 工具读取刚创建的复盘文档
|
||
- 检查是否符合复盘文档模板
|
||
- 检查是否对比了目标与实际产出
|
||
- 检查是否提取了模式
|
||
- 检查是否进行了模板迭代
|
||
|
||
#### 步骤 3：API 文档分析（Let's think step by step）
|
||
在创建 API 文档前，必须执行以下分析：
|
||
|
||
1. **分析 API 接口的设计和实现**
|
||
- 读取阶段 6 生成的代码文件
|
||
- 识别所有 API 接口
|
||
- 确定接口的请求方式、请求路径、请求参数、响应参数等
|
||
- 确定接口的错误码
|
||
|
||
2. **确定 API 文档的结构和内容**
|
||
- API 概述
|
||
- 接口列表
|
||
- 错误码
|
||
- 相关文档
|
||
|
||
#### 步骤 4：创建 API 文档
|
||
1. **确定文档路径**
|
||
- 路径：`docs/api-docs/YYYY-MM-DD-00X-api.md`
|
||
- 使用 Write 工具创建文件
|
||
- 确保目录存在（使用 LS 工具检查）
|
||
|
||
2. **填充文档内容**
|
||
- **元数据**：包含需求编号、创建时间、创建人等
|
||
- **API 概述**：简述 API 的核心功能和用途
|
||
- **接口列表**：详细描述每个 API 接口：
|
||
- 接口名称
|
||
- 请求方式
|
||
- 请求路径
|
||
- 请求参数
|
||
- 响应参数
|
||
- 示例
|
||
- **错误码**：描述 API 可能返回的错误码及其含义
|
||
- **相关文档**：添加需求文档和设计文档链接
|
||
|
||
3. **文档质量检查**
|
||
- 使用 Read 工具读取刚创建的 API 文档
|
||
- 检查是否符合 API 文档模板
|
||
- 检查接口描述是否详细、准确
|
||
- 检查示例是否完整、正确
|
||
- 检查错误码是否清晰、全面
|
||
|
||
#### 步骤 5：更新索引和需求文档
|
||
1. **读取现有索引**
|
||
- 使用 Read 工具读取 `docs/index.md`
|
||
- 找到"复盘文档"和"API 文档"部分
|
||
- 如果不存在，则创建这些部分
|
||
|
||
2. **添加新文档链接**
|
||
- 在"复盘文档"部分追加新复盘文档
|
||
- 格式：`- [复盘文档](./retros/YYYY-MM-DD-00X-retro.md) - [功能名]`
|
||
- 示例：`- [用户登录功能复盘](./retros/2026-01-21-001-retro.md) - 用户登录功能`
|
||
|
||
- 在"API 文档"部分追加新 API 文档
|
||
- 格式：`- [API 文档](./api-docs/YYYY-MM-DD-00X-api.md) - [功能名]`
|
||
- 示例：`- [用户登录功能 API 文档](./api-docs/2026-01-21-001-api.md) - 用户登录功能`
|
||
|
||
3. **更新需求文档**
|
||
- 使用 Read 工具读取需求文档
|
||
- 在"相关文档"部分添加复盘和 API 文档引用
|
||
- 格式：`- [复盘文档](../retros/YYYY-MM-DD-00X-retro.md)`
|
||
- 格式：`- [API 文档](../api-docs/YYYY-MM-DD-00X-api.md)`
|
||
- 使用 Write 工具更新需求文档
|
||
|
||
4. **保存索引**
|
||
- 使用 Write 工具更新 `docs/index.md`
|
||
- **严禁**删除现有内容，只追加新内容
|
||
|
||
#### 步骤 6：更新会话记录
|
||
1. **读取现有会话记录**
|
||
- 使用 Read 工具读取 `docs/sessions/YYYY-MM-DD-00X-session.md`
|
||
|
||
2. **更新阶段 9 信息**
|
||
- 更新"当前阶段"为"阶段 9：闭环复盘和接口文档"
|
||
- 更新"阶段 9：闭环复盘和接口文档"的状态为"已完成"
|
||
- 添加生成的复盘和 API 文档链接
|
||
- 记录复盘的主要结论
|
||
|
||
3. **保存会话记录**
|
||
- 使用 Write 工具更新会话记录
|
||
|
||
#### 步骤 7：确认与询问
|
||
1. **向用户确认**
|
||
- 显示复盘文档的链接
|
||
- 显示 API 文档的链接
|
||
- 询问："复盘和 API 文档是否完整？"
|
||
- 询问："是否进入下一阶段（代码提交）？"
|
||
|
||
2. **等待用户反馈**
|
||
- 如果用户不满意，询问具体需要修改的地方
|
||
- 如果用户要求回退，执行回退机制（见错误陷阱部分）
|
||
- 如果用户确认，标记阶段 9 为已完成，准备进入阶段 10
|
||
|
||
### 工具调用
|
||
|
||
#### 必须使用的工具
|
||
1. **Read 工具**：读取现有文件
|
||
- 使用场景：读取会话记录、索引、需求文档、会话记录
|
||
- 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\sessions\\2026-01-21-001-session.md")`
|
||
|
||
2. **Write 工具**：创建或更新文件
|
||
- 使用场景：创建复盘文档、创建 API 文档、更新索引、更新需求文档、更新会话记录
|
||
- 命令：`Write(file_path="d:\\idea_demo\\datai\\docs\\retros\\2026-01-21-001-retro.md", content="...")`
|
||
|
||
3. **LS 工具**：检查目录是否存在
|
||
- 使用场景：创建文档前检查 `docs/retros/` 和 `docs/api-docs/` 目录
|
||
- 命令：`LS(path="d:\\idea_demo\\datai\\docs")`
|
||
|
||
4. **SearchCodebase 工具**：搜索 API 接口
|
||
- 使用场景：查找生成的 API 接口代码
|
||
- 命令：`SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类和 API 接口")`
|
||
|
||
#### 可选使用的工具
|
||
1. **TodoWrite 工具**：管理任务
|
||
- 使用场景：跟踪阶段执行进度
|
||
- 命令：`TodoWrite(todos=[...])`
|
||
|
||
---
|
||
|
||
## D. 错误陷阱与验证 (Anti-Patterns & Checklist)
|
||
|
||
### 常见错误（Anti-Patterns）
|
||
|
||
#### 错误 1：复盘内容不真实、不深入
|
||
**错误示例**：
|
||
```markdown
|
||
## 成功经验
|
||
1. 团队协作良好
|
||
2. 进度按时完成
|
||
3. 代码质量高
|
||
|
||
## 改进点
|
||
1. 可以更快完成
|
||
2. 可以更仔细
|
||
3. 可以更好
|
||
```
|
||
|
||
**问题**：
|
||
- 复盘内容过于笼统，没有具体的案例和分析
|
||
- 没有对比目标与实际产出
|
||
- 没有提取有效的 Prompt 技巧和避免的坑
|
||
- 没有制定具体的行动计划
|
||
|
||
**正确示例**：
|
||
```markdown
|
||
## 成功经验
|
||
1. **SSOT 流程的严格执行**：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。
|
||
2. **详细的提示词设计**：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。
|
||
3. **完整的会话记录**：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。
|
||
|
||
## 改进点
|
||
1. **阶段间的过渡可以更流畅**：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
|
||
2. **代码生成前的验证可以更严格**：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。
|
||
3. **API 文档的自动生成可以考虑**：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。
|
||
|
||
## 问题分析
|
||
1. **问题 1**：在阶段 6 生成代码时，发现部分代码不符合若依框架规范
|
||
- **根因**：提示词中的代码规范要求不够具体
|
||
- **解决方案**：在后续的提示词设计中，增加更具体的若依框架规范要求
|
||
|
||
2. **问题 2**：在阶段 7 更新会话记录时，发现部分对话记录缺失
|
||
- **根因**：会话记录的更新不及时
|
||
- **解决方案**：在每个阶段完成后立即更新会话记录，确保对话记录的完整性
|
||
|
||
## 行动计划
|
||
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
|
||
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
|
||
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
|
||
4. **针对问题 1**：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
|
||
5. **针对问题 2**：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行
|
||
|
||
## 提取模式
|
||
### 有效的 Prompt 技巧
|
||
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
|
||
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
|
||
### 避免的坑
|
||
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
|
||
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
|
||
|
||
## 模板迭代
|
||
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求。
|
||
```
|
||
|
||
#### 错误 2：API 文档内容不详细、不准确
|
||
**错误示例**：
|
||
```markdown
|
||
## 接口列表
|
||
### 接口 1：登录接口
|
||
- 请求方式：POST
|
||
- 请求路径：/api/system/auth/login
|
||
- 请求参数：
|
||
- username：用户名
|
||
- password：密码
|
||
- 响应参数：
|
||
- token：令牌
|
||
```
|
||
|
||
**问题**：
|
||
- API 文档内容过于简单
|
||
- 请求参数缺少类型、是否必填等信息
|
||
- 响应参数缺少类型、说明等信息
|
||
- 缺少示例
|
||
- 缺少错误码
|
||
|
||
**正确示例**：
|
||
```markdown
|
||
## 接口列表
|
||
### 接口 1：登录接口
|
||
- **功能描述**：用户登录接口，用于验证用户身份并生成令牌
|
||
- **请求方式**：POST
|
||
- **请求路径**：`/api/system/auth/login`
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| username | String | 是 | 用户名，长度 1-30 字符 |
|
||
| password | String | 是 | 密码，长度 6-20 字符 |
|
||
| code | String | 是 | 验证码，长度 4 字符 |
|
||
| uuid | String | 是 | 验证码唯一标识，长度 36 字符 |
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，其他失败） |
|
||
| msg | String | 提示信息 |
|
||
| token | String | JWT 令牌，用于后续请求的身份验证 |
|
||
- **成功示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"token": "eyJhbGciOiJIUzUxMiJ9..."
|
||
}
|
||
```
|
||
- **失败示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "用户名或密码错误"
|
||
}
|
||
```
|
||
- **错误码**：
|
||
- 500：用户名或密码错误
|
||
- 501：验证码错误
|
||
- 502：用户已停用
|
||
- 503：登录失败次数过多
|
||
```
|
||
```
|
||
|
||
#### 错误 3：不提取模式和进行模板迭代
|
||
**错误示例**：
|
||
```markdown
|
||
## 提取模式
|
||
- 无
|
||
|
||
## 模板迭代
|
||
- 无
|
||
```
|
||
|
||
**问题**：
|
||
- 违反了项目规则
|
||
- 没有从本次执行中提取有效的经验和教训
|
||
- 没有对模板进行迭代和改进
|
||
- 无法实现持续改进
|
||
|
||
**正确示例**：
|
||
```markdown
|
||
## 提取模式
|
||
### 有效的 Prompt 技巧
|
||
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
|
||
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
|
||
### 避免的坑
|
||
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
|
||
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
|
||
|
||
## 模板迭代
|
||
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求。
|
||
```
|
||
|
||
#### 错误 4：不更新索引和需求文档
|
||
**错误示例**：
|
||
```
|
||
AI：创建复盘文档和 API 文档
|
||
AI：更新会话记录
|
||
AI：完成（忘记更新索引和需求文档）
|
||
```
|
||
|
||
**问题**：
|
||
- 违反了项目规则
|
||
- 索引中没有新增的复盘和 API 文档链接
|
||
- 需求文档中没有新增的复盘和 API 文档引用
|
||
- 其他开发人员无法快速找到这些文档
|
||
|
||
**正确示例**：
|
||
```
|
||
AI：创建复盘文档和 API 文档
|
||
AI：更新索引
|
||
AI：更新需求文档
|
||
AI：更新会话记录
|
||
AI：完成
|
||
```
|
||
|
||
#### 错误 5：不询问用户确认就进入下一阶段
|
||
**错误示例**：
|
||
```
|
||
AI：创建复盘文档和 API 文档
|
||
AI：进入阶段 10：代码提交（未询问用户）
|
||
```
|
||
|
||
**正确示例**：
|
||
```
|
||
AI：创建复盘文档和 API 文档
|
||
AI：复盘文档已创建：[链接]
|
||
AI：API 文档已创建：[链接]
|
||
AI：复盘和 API 文档是否完整？
|
||
AI：是否进入下一阶段（代码提交）？
|
||
```
|
||
|
||
### 验收清单（Checklist）
|
||
|
||
在完成阶段 9 前，必须检查以下项目：
|
||
|
||
#### 复盘文档检查
|
||
- [ ] 复盘文档已创建在 `docs/retros/` 目录下
|
||
- [ ] 文档命名符合 `YYYY-MM-DD-00X-retro.md` 格式
|
||
- [ ] 文档包含所有必需章节（元数据、复盘概述、成功经验、改进点、问题分析、行动计划、相关文档）
|
||
- [ ] 元数据已正确填写（需求编号、创建时间、创建人）
|
||
- [ ] 复盘概述清晰、准确
|
||
- [ ] 成功经验具体、有案例
|
||
- [ ] 改进点具体、可操作
|
||
- [ ] 问题分析深入、有根因和解决方案
|
||
- [ ] 行动计划具体、有责任人和时间节点
|
||
- [ ] 已对比目标与实际产出
|
||
- [ ] 已提取 3 条有效的 Prompt 技巧
|
||
- [ ] 已提取 3 个避免的坑
|
||
- [ ] 已进行模板迭代
|
||
|
||
#### API 文档检查
|
||
- [ ] API 文档已创建在 `docs/api-docs/` 目录下
|
||
- [ ] 文档命名符合 `YYYY-MM-DD-00X-api.md` 格式
|
||
- [ ] 文档包含所有必需章节（元数据、API 概述、接口列表、错误码、相关文档）
|
||
- [ ] 元数据已正确填写（需求编号、创建时间、创建人）
|
||
- [ ] API 概述清晰、准确
|
||
- [ ] 接口列表完整、详细
|
||
- [ ] 每个接口包含：
|
||
- 功能描述
|
||
- 请求方式
|
||
- 请求路径
|
||
- 请求参数（包括类型、是否必填、说明）
|
||
- 响应参数（包括类型、说明）
|
||
- 成功示例
|
||
- 失败示例（可选）
|
||
- 错误码（可选）
|
||
- [ ] 错误码清晰、全面
|
||
- [ ] 相关文档链接正确
|
||
|
||
#### 索引更新检查
|
||
- [ ] `docs/index.md` 已更新
|
||
- [ ] 新复盘文档链接已添加到"复盘文档"部分
|
||
- [ ] 新 API 文档链接已添加到"API 文档"部分
|
||
- [ ] 索引链接格式正确：`[文档名](./相对路径/文件名.md)`
|
||
- [ ] 索引更新采用增量更新策略，未删除现有内容
|
||
|
||
#### 需求文档更新检查
|
||
- [ ] 需求文档已更新
|
||
- [ ] 需求文档的"相关文档"部分已添加复盘和 API 文档引用
|
||
- [ ] 引用格式正确：`[复盘文档](../retros/YYYY-MM-DD-00X-retro.md)`
|
||
|
||
#### 会话记录更新检查
|
||
- [ ] 会话记录已更新
|
||
- [ ] 会话记录的"当前阶段"已更新为"阶段 9：闭环复盘和接口文档"
|
||
- [ ] 会话记录的"阶段 9：闭环复盘和接口文档"状态已更新为"已完成"
|
||
- [ ] 会话记录包含复盘和 API 文档链接
|
||
- [ ] 会话记录包含复盘的主要结论
|
||
|
||
#### 用户确认检查
|
||
- [ ] 已向用户显示复盘文档链接
|
||
- [ ] 已向用户显示 API 文档链接
|
||
- [ ] 已询问用户"复盘和 API 文档是否完整？"
|
||
- [ ] 已询问用户"是否进入下一阶段？"
|
||
- [ ] 已等待用户反馈
|
||
|
||
#### 回退机制检查（如果需要）
|
||
- [ ] 如果用户不满意，已询问具体需要修改的地方
|
||
- [ ] 如果用户要求回退，已删除相关文档
|
||
- [ ] 如果用户要求回退，已撤销索引更新
|
||
- [ ] 如果用户要求回退，已撤销需求文档更新
|
||
- [ ] 如果用户要求回退，已更新会话记录
|
||
|
||
### Correct vs Incorrect 代码对比
|
||
|
||
#### Incorrect（错误示例）
|
||
```markdown
|
||
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：001
|
||
- 创建时间：2026-01-21
|
||
- 创建人：AI Assistant
|
||
|
||
## 复盘概述
|
||
对用户登录功能的开发过程进行复盘
|
||
|
||
## 成功经验
|
||
1. 开发顺利
|
||
2. 代码质量高
|
||
3. 用户满意
|
||
|
||
## 改进点
|
||
1. 可以更快
|
||
2. 可以更好
|
||
3. 可以更仔细
|
||
|
||
## 问题分析
|
||
1. 无
|
||
|
||
## 行动计划
|
||
1. 无
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
|
||
```
|
||
|
||
#### Correct（正确示例）
|
||
```markdown
|
||
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：001
|
||
- 创建时间：2026-01-21
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对用户登录功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
### 目标
|
||
- 实现用户登录功能，包括用户名和密码验证、记住密码、自动登录等功能
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码
|
||
|
||
### 实际产出
|
||
- 成功实现了用户登录功能，包括用户名和密码验证、记住密码、自动登录等功能
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成的代码符合项目规范，包含单元测试
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
|
||
## 成功经验
|
||
1. **SSOT 流程的严格执行**：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。
|
||
2. **详细的提示词设计**：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。
|
||
3. **完整的会话记录**：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。
|
||
|
||
## 改进点
|
||
1. **阶段间的过渡可以更流畅**：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
|
||
2. **代码生成前的验证可以更严格**：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。
|
||
3. **API 文档的自动生成可以考虑**：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。
|
||
|
||
## 问题分析
|
||
1. **问题 1**：在阶段 6 生成代码时，发现部分代码不符合若依框架规范
|
||
- **根因**：提示词中的代码规范要求不够具体
|
||
- **解决方案**：在后续的提示词设计中，增加更具体的若依框架规范要求
|
||
|
||
2. **问题 2**：在阶段 7 更新会话记录时，发现部分对话记录缺失
|
||
- **根因**：会话记录的更新不及时
|
||
- **解决方案**：在每个阶段完成后立即更新会话记录，确保对话记录的完整性
|
||
|
||
## 行动计划
|
||
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
|
||
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
|
||
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
|
||
4. **针对问题 1**：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
|
||
5. **针对问题 2**：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行
|
||
|
||
## 提取模式
|
||
### 有效的 Prompt 技巧
|
||
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
|
||
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
|
||
### 避免的坑
|
||
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
|
||
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
|
||
|
||
## 模板迭代
|
||
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求，包括：
|
||
- 若依框架的包结构规范
|
||
- 若依框架的注解使用规范
|
||
- 若依框架的异常处理规范
|
||
- 若依框架的权限控制规范
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
|
||
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
|
||
- [决策记录](../decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md)
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：快速参考
|
||
|
||
### 文件路径速查
|
||
- 复盘文档：`docs/retros/YYYY-MM-DD-00X-retro.md`
|
||
- API 文档：`docs/api-docs/YYYY-MM-DD-00X-api.md`
|
||
- 主索引：`docs/index.md`
|
||
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
|
||
- 项目规则：`.trae/rules/project_rules.md`
|
||
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`
|
||
|
||
### 工具命令速查
|
||
```powershell
|
||
# 读取会话记录
|
||
Read(file_path="d:\\idea_demo\\datai\\docs\\sessions\\2026-01-21-001-session.md")
|
||
|
||
# 创建复盘文档
|
||
Write(file_path="d:\\idea_demo\\datai\\docs\\retros\\2026-01-21-001-retro.md", content="...")
|
||
|
||
# 创建 API 文档
|
||
Write(file_path="d:\\idea_demo\\datai\\docs\\api-docs\\2026-01-21-001-api.md", content="...")
|
||
|
||
# 读取索引
|
||
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")
|
||
|
||
# 更新索引
|
||
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")
|
||
|
||
# 搜索 API 接口
|
||
SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类和 API 接口")
|
||
```
|
||
|
||
### 阶段 9 输出清单
|
||
- [ ] 复盘文档：`docs/retros/YYYY-MM-DD-00X-retro.md`
|
||
- [ ] API 文档：`docs/api-docs/YYYY-MM-DD-00X-api.md`
|
||
- [ ] 更新的索引：`docs/index.md`
|
||
- [ ] 更新的需求文档：`docs/requirements/YYYY-MM-DD-00X-需求名.md`
|
||
- [ ] 更新的会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
|
||
|
||
### 下一阶段提示
|
||
如果用户确认进入下一阶段，请参考：
|
||
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) 的"阶段 10：代码提交"
|
||
- 准备检查所有生成的代码文件和文档文件
|
||
- 准备提交代码到本地仓库
|
||
- 准备询问用户是否提交到远程仓库
|