handoff

交接

概述

创建或使用一份持久交接文档，让其他 Agent（或后续会话）能够在保留目标、决策、仓库状态、风险和后续步骤的情况下继续同一项工作。

模式

确定适用的模式：

• 生成：将当前对话和工作区状态整理成交接文档。
• 接续：将现有交接文档视为事实来源，并据此继续工作。

如果无法确定，只询问一次是要撰写交接文档，还是根据现有文档继续工作。

核心规则

• 优先考虑接手工作的 Agent，而不是离开的 Agent 的工作日记。
• 优先提供具体路径、命令、决策和有序的后续步骤，而非叙述性回顾。
• 区分事实、假设和待解问题。
• 切勿包含机密、令牌、密码、私钥或完整的机密值。只写环境变量名称。
• 不要捏造已完成的工作。尽可能根据工作区核实相关说法。
• 保持与具体工具无关。默认在聊天中输出；只有用户提出要求或指定路径时才写入文件。
• 如果存在可选待办列表、计划模式或审批流程，只将它们作为辅助工具；交接文档仍须是可移植的交接材料。

生成流程

1. 确认下一位 Agent 应继续执行的任务。
2. 检查足够的实时状态，以便交接内容有据可依：
   • 当前分支、未提交文件、近期提交，以及可用时的相关运行进程。
   • 已修改或即将修改的关键文件。
   • 用户已确认的决策。
3. 填写 references/template.md 中的模板。省略空白章节，不要为了填满内容而补写。
4. 如需缩短内容，优先保留以下章节：
   • 目标和状态
   • 紧接着要做的步骤
   • 必须了解的背景
   • 不要做的事
5. 除非用户要求提供文件路径，否则在聊天中输出交接文档。
6. 以一行可供用户粘贴到下一会话的恢复指令结尾，例如：从这份交接文档继续工作，并执行第 1 步。

生成质量标准

优秀的交接文档应让另一位 Agent 阅读一次后就能开始有效工作。

请包含：

• 状态：ready、needs-review 或 blocked，并注明阻塞原因。
• 已完成和未完成的工作。
• 如实说明未提交或尚未完成的工作。
• 有序且可验证的后续步骤。
• 简短的“先阅读这些文件”列表（通常为 3 至 7 个路径），并说明每个文件的用途。
• 可能需要重新确认的假设、注意事项和已否决的方案。
• 已知的重要命令或检查的准确内容。

避免：

• 倾倒完整聊天记录。
• 使用“继续实现”或“完成此功能”等含糊步骤。
• 列出仓库中所有相关文件。
• 隐瞒不确定性；明确标注未知事项。

接续流程

1. 进行任何更改前，先完整阅读交接文档。
2. 适用时，用简短确认向用户重述目标、状态和第一项后续步骤。
3. 在信任交接文档前，根据实时状态进行核实：
   • 分支、工作区是否干净，以及文档中声称的文件变更。
   • 所引用的提交、路径和命令是否仍然存在。
   • 阻塞因素是否仍然存在。
4. 如果工作区状态与交接文档不一致，先停止并报告差异，再继续。
5. 除非用户另有要求，否则遵循“不要做的事”和有序的后续步骤。
6. 先阅读列出的文件，只有需要时再查看其他内容。
7. 交接工作完成，或本次会话需要再次中止时，生成更新后的交接文档，不要只依赖聊天记忆。

默认输出设置

• 默认输出位置：聊天中，作为一份完整的 Markdown 文档。
• 如果用户指定路径，则写入该路径。常见路径包括：HANDOFF.md、docs/handoff.md 或用户指定的日期路径。
• 不要在无关项目中擅自创建交接文件。
• 交接正文中不要包含特定产品的 UI 元数据。

最简恢复提示词

生成交接文档时，也提供以下简短提示，供下一位 Agent 开始工作：

Use $handoff in consume mode.
Handoff is below / at <path>.
Verify it against the repo, then continue from Immediate Next Steps without re-litigating settled decisions unless they conflict with the workspace or user direction.