复盘沉淀¶
复盘是把一次性经验转化为可复用资产的关键步骤。跳过复盘的团队，每次都在重新发明轮子。
复盘的三个层次¶
层次一：任务级复盘（每次任务后，5 分钟）¶
记录三件事：
## 任务复盘 - 2025-05-26
**任务**：为登录页添加 GitHub OAuth 按钮
**有效的**：
- 提供了现有按钮组件作为风格参考，AI 输出风格一致
- 明确约束"不改动 auth/ 目录"，AI 没有越界
**失败的**：
- 第一次没有说明 OAuth callback URL 的格式，AI 生成了错误的路由
- 修复：在规格中补充了 callback URL 约定
**沉淀**：
- OAuth 集成任务需要在规格中包含 callback URL 格式
- 提示词模板更新：添加"OAuth 约定"字段
层次二：项目级复盘（每个里程碑后，30 分钟）¶
- 哪些提示词模式在这个项目中效果最好
- 哪些约定需要写入项目规则文件
- 哪些任务类型 AI 处理得不好，需要人工介入
层次三：团队级复盘（每个季度，1 小时）¶
- 跨项目的通用提示词模式
- 团队成员的最佳实践分享
- 工具链和工作流的改进方向
沉淀的形式¶
提示词库¶
把有效的提示词模式整理成可复用模板：
## 模板：API 接口实现
背景：[项目名] 使用 [框架]，接口统一返回 { data, error } 格式。
目标：实现 [HTTP 方法] [路径] 接口。
范围：只修改 [文件路径]，不改动其他文件。
约束：
- 沿用现有的错误处理中间件
- 参数验证使用 zod schema
- 不引入新依赖
验收：运行 [测试命令]，所有用例通过。
项目规则文件¶
把项目特定约定写入规则文件（.cursor/rules/、CLAUDE.md、.kiro/steering/ 等），让 AI 每次自动遵守。初始配置方式见项目规则文件，团队维护规范见团队协作规范。
失败模式库¶
记录 AI 容易犯的错误，在任务简报中主动规避：
| 失败模式 | 触发条件 | 规避方式 |
|---|---|---|
| 引入不存在的依赖 | 没有提供 package.json | 在约束中列出已有依赖 |
| 改动范围超出预期 | 规格范围不明确 | 明确列出"不改动"的文件 |
| 风格不一致 | 没有提供参考实现 | 附上同类功能的现有实现 |
失败案例：AI 跑偏长什么样¶
理论上知道"要写清楚规格"，但不知道跑偏时实际发生什么。下面是三个真实场景。
场景一：AI 修改了不该改的文件¶
任务：为登录页添加 GitHub OAuth 按钮。
发生了什么：AI 生成了正确的按钮组件，但同时修改了 src/lib/auth.ts，添加了一个它认为"缺少的" session 字段。代码能跑，但破坏了现有的 Google 登录流程。
怎么发现的：任务完成后运行 git diff --stat，看到了规格范围外的文件被修改。
根因：规格里写了"session 中有 user.id"，但没有附上实际的 auth 配置。AI 猜测 session 结构并做了"修复"。
修复：回退 src/lib/auth.ts，重新请求时附上 auth 配置文件，约束中加"不修改 src/lib/auth.ts"。
沉淀：涉及认证的任务，必须附上 auth 配置，并在约束中明确禁止修改。
场景二：AI 引入了项目中不存在的依赖¶
任务：为表单添加日期选择器。
发生了什么：AI 生成了使用 react-datepicker 的代码，但项目实际上用的是 @radix-ui/react-popover 自己封装的日期选择器。代码无法运行，因为依赖不存在。
怎么发现的：运行 pnpm install 时没有报错（因为 AI 没有修改 package.json），但运行时报"找不到模块"。
根因：没有提供 package.json 或现有的日期选择器组件作为参考，AI 使用了它认为"最常见"的方案。
修复：重新请求，附上现有的日期选择器组件代码，约束中加"只使用 package.json 中已有的依赖"。
沉淀：UI 组件任务必须附上同类现有组件，约束中明确禁止引入新依赖。
场景三：AI 修复了症状而不是根因¶
任务：修复用户列表页面偶发的空白问题。
发生了什么：AI 在数据加载函数外层加了 try-catch，捕获错误后返回空数组，页面不再空白了——但实际上是因为 API 请求偶发超时，根本问题没有解决。
怎么发现的：一周后用户反馈"列表有时候加载不出来"，排查时发现错误被静默吞掉了。
根因：Bug 描述只说了"页面空白"，没有提供错误堆栈和复现步骤，AI 选择了最简单的修复方式。
修复：提供完整的错误堆栈和网络请求日志，重新定位根因（API 超时），实现了正确的重试逻辑。
沉淀：Bug 修复任务必须提供完整错误堆栈和复现步骤，约束中加"修复根因，不只是处理症状"。
复盘工具¶
- Git 提交信息：每次提交写清楚"做了什么"和"为什么"
- 任务日志：在任务管理工具中记录 AI 对话的关键决策
- 团队 Wiki：定期把个人复盘整理成团队可读的文档