复盘

复盘 是做什么的？

复盘是实现一个持续元目标的工具：一个改进我们流程的流程。它审视人与代理的协作方式，并基于证据，将其发现转化为三种输出：对代理的经验教训（指令、技能、工作流、钩子）、对用户的经验教训（如何更好地引导代理）以及对项目设置的变更。它双向坦诚，且从不捏造批评：表现良好的会话将获得简短的报告。

结构和规则改编自两个 MIT 许可的技能，特此致谢：debrief 技能（由 Wavez 开发，包含四个检查组、“每个发现都引用具体时刻”、未经批准不应用任何内容）和 retrospective 技能（由 florianbuetow 开发，将报告保存为历史记录，检查之前的建议，对重复问题升级处理，并为每个发现提供根本原因和建议）。指导部分、五问法习惯以及使用脚本是本技能自创的内容。

输入

1. 会话内容。 主要来源：工具调用、提出的问题及提出时间、用户的更正和确认、子代理报告、错误和重试。如果会话已被压缩，请在报告中说明，并将摘要视为可信度较低的证据；不要为你无法看到的部分编造时刻。

2. 数据统计。 运行会话的内置脚本以获取使用情况：轮次、按名称分类的工具调用、子代理和工作流及其令牌消耗、使用的模型、每个模型的输出令牌数、持续时间跨度、压缩次数。该脚本读取 ~/.claude/projects/<项目标识>/ 下的会话记录以及其旁边的 subagents/ 目录。用户可以询问其他会话；此时需要传递其会话 ID。

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py            # 当前会话（此项目的最新记录）
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py <会话-id>
   

3. 项目记录。 指令文件（CLAUDE.md, AGENTS.md），如果项目维护了待办事项和决策日志则包括这些，以及此项目的代理反馈记忆（~/.claude/projects/<项目标识>/memory/），以便识别重复出现的错误。

4. 之前的复盘报告。 报告目录（见下文）中的最后三份报告。对于其中的每条建议，需说明其是否已被采纳、是否重复出现、或情况未知；重复出现的问题将被升级处理。

工作投入与工作阶段相匹配：简短、清晰的会话只需快速检查；持续数周的会话则进行全面处理，并对较大的模式使用五问法。

检查内容

按以下四个组别进行检查。对于每个发现，请引用具体时刻（发生了什么或说了什么，大致时间点），说明其为何重要，并追问“为什么”，直到找到流程上的原因或原则，或直到答案超出项目的控制范围。将观察结果与解决方案分开：观察结果可能正确，而提出的修复方案可能是错误的。

1. 效率。 冗余或重复的工具调用、本应由脚本或技能完成的手动逻辑、额外的构建或测试周期、可以批量处理的工作、被遗漏或已产生收益的子代理、压缩后返工、因会话结束而丢失的后台工作。
2. 协作。 过早、过晚或未提出的问题；未遵循的常设指令；将示例按字面理解而忽略了规则；啰嗦；代理是否说明了对模糊请求的解读；阻碍性问题是否真的造成了阻碍。
3. 正确性与纪律。 未经证据支持的断言；后期才发现的约束；未经确认的破坏性或不可逆操作；忽略的项目约定；跳过“这个需求适用于哪种场景”和“什么原本可以捕获这个问题”的思考。
4. 传承。 值得保存为记忆或项目文档的偏好和决策；可作为技能、工作流、钩子、常设规则或待办事项的提议；本可以使工作更轻松的工具；下次可以自动化的步骤。两次重复的手工操作表明缺少可复用的资产。

然后是使此技能更具个性化的两个部分：

• 对用户的指导。 编写提示的人如何才能更有效？他们哪些做法最有帮助（明确指出，以便重复使用），哪些做法代价高昂（范围模糊、示例缺少标签、隐瞒了代理需要的决策、跳过了审查）？以类似督导组中同伴的方式，直接对用户说话：具体、基于证据、不奉承、不缓和语气。
• 模型与投入。 根据数据：模型和投入水平是否与工作相称？令牌消耗在何处（主循环、子代理、工作流），是否可以在部分环节使用更便宜的模型或更低的投入？高投入在哪些地方带来了回报？

报告

将报告写入报告目录，并在回复中显示简短摘要。目录是当前仓库中的 docs/debriefs/（如果仓库有 docs/ 目录），否则是 ~/.claude/debriefs/<项目标识>/；用户可以指定其他路径。文件名格式为 YYYY-MM-DD.md，如果已存在则添加 -2 后缀。

简短而密集：读者是亲身经历会话的人，因此报告旨在提醒而非叙述。细微差别体现在证据和原因中，而非围绕它们的文字。使用以下模板：

# 复盘 <日期>: <工作阶段的主题>

覆盖范围: <复盘所能看到的内容；注明压缩情况>。之前的复盘: <日期 或 无>。

## 五句话总结
- <工作阶段的成果>
- <使其成功的原因>
- <代价是什么>
- <用一句话概括的指导>
- <提议的数量，以及其中最重要的那一个>

## 数据
<脚本输出的一段文字：时间跨度、轮次、工具调用（列出主要几个）、各模型输出令牌数、子代理、压缩次数>

## 做得好的地方
- **<两字标签>.** <具体时刻> → <带来的好处>。

## 有代价的地方
- 🔴 / 🟡 / 🟢 **<标签>.** <具体时刻，一行>。
  原因: <追问原因后找到的流程原因>。 <已修复，或存在的问题。>

## 对 <用户> 的指导
继续保持: <有帮助的做法，列在一行内>。
1. **<习惯>.** <证据> 以及 <应如何替代>，一到两句话。

## 模型与投入
<一段文字：是否相称，以及支持该结论的数据>

## 提议
| # | 提议 | 目标位置 | 投入 | 决策 |
|---|---|---|---|---|
目标位置：AGENTS.md 或 CLAUDE.md 规则、记忆、技能、工作流、钩子、待办事项、共享指南、采纳的工具。

## 之前的建议
| 来源 | 建议 | 状态 (已采纳 / 重复出现 / 未知) |

严重程度：🔴 造成实际工作损失或带来损坏风险；🟡 耗费时间或精力；🟢 小习惯。

规则

• 仅限于报告。在用户批准提议之前，不得将任何内容写入指令文件、记忆或待办事项；批准后，仅应用那一项。
• 每个发现都必须引用具体时刻。如果无法指出具体时刻，则放弃该发现。
• 不要夸大：三个真实的发现胜过十个凑数的发现，而“这个阶段进展顺利”本身就是一个有效结果。
• 指导是为了用户的利益，因此必须坦诚；同时默认保密，因此不要将其包含在用户未要求分享的任何内容中。
• 具体、可操作的语言：每个条目都应写得让未参与会话的人或代理能够据此行动。将实践描述为某种行为（某人做了什么以及达到了什么效果：“指定结果，而非解决方案”），切勿使用会话中创造的昵称（如“隐藏的解决方案”、“怀疑论者”、“凭感觉”）；如果简称有助于识别，请将其放在完整形式之后的括号中。检验标准：同事能否将这句话直接复制到他们自己的指南中并遵循？
• 简洁：加粗标签，然后一行证据，接着是原因。如果一个发现需要一段话，那它要么是两个发现，要么是尚未理解透彻。力求每个部分在一屏内显示。
• 经验教训与摩擦：经验教训是你会告诉另一个项目上另一个代理的内容；仅适用于本次会话的内容属于摩擦，应归入发现中，而不应成为常设规则的提议。