write-handoff

将工作交接给下一位 Agent

工作尚未完成，还有任务待处理，而了解原因的会话即将消失。下一位 Agent 将从零开始：没有对话记录，没有推理过程，只有代码树和你留下的内容。 docs/<feature>/HANDOFF.md（位于项目规划目录，除非项目使用其他目录）就是你要留下的内容。

评判标准是：下一位 Agent 的第一个小时能高效推进，而不是考古挖掘——它是否知道工作进展到了哪里、首先要做什么，以及即将发现的哪些情况其实早已弄清楚。

这不是 write-acceptance。 后者是将已完成的工作交给某人测试和验收；这里是把未完成的工作交给 Agent。读者不同，问题也不同——如果一次运行既完成了一个阶段，又留下了待办事项，就要同时编写两份文档。

何时编写

• 请求范围尚未完成：阶段被推迟、因决策受阻，或当天停止。
• 任务进行到一半时，你的上下文即将耗尽。
• 工作转移到另一个分支、检出目录、机器或其他人的会话。

范围已完成时，不要编写交接文档。 已完成的工作由 EXECUTION.md 描述，并通过 close-plan 或 close-roadmap 归档；此时再写交接文档，只会成为同一次运行的第四份摘要，随后过时，却仍会被人相信。

写入内容

先说明代码树的状态，因为它最先出问题。 写明分支和检出目录（或工作树）路径、工作树是否干净，以及哪些内容已推送、哪些尚未推送——如果 Agent 以为工作已在 origin 上，就会在一个并不存在的分支上操作。然后说明第一步：如果主集成分支（例如 main 或 dev）已经前进，就写“先合并 <main>，之后再对代码树进行任何操作”，并把这句话放在页面最前面。

• 明确、醒目地说明从哪里继续。 用一句话点明接下来要做什么。页面上的其他内容都是这句话的背景。
• 说明构建了什么——提供指向文档的链接，而不是复述。 指出哪些文档具有权威性（最终计划、决策记录、生成的参考文档），并明确说明摘要不是规范。只要发生任何变更，文字回顾就会立即变成计划的第二份错误副本。
• 仅在有助于解释时列出提交。 EXECUTION.md 已记录了已合入内容及其哈希——链接到该文档，不要重复表格。这里应说明那些形态特殊的提交：重排决策记录编号的提交、仅包含合并操作的提交，或仍只存在于此分支的提交。
• 说明陷阱。 会反复出现的冲突及上次解决时采用的规则、在分支基点就会失败且与你无关的测试、偶发故障及其特征，以及看起来有问题但其实正常的情况。这部分无法从代码树中还原，因此每行都最有价值——说明一次的陷阱，下一位 Agent 就不用再为它付出代价。
• 说明用户离开期间做出的决策，并提供指向问题日志的链接（指向项目存放未决问题的位置；如果项目没有约定，就在计划旁边添加问题章节或文件）。下一位 Agent 不得悄悄重新作出这些决策，而且必须知道哪些问题仍未解决。
• 说明哪些内容是有意未完成的，这样下一位 Agent 才会在现有工作上继续推进，而不是“修复”有意留下的空缺。

在开头注明日期和本次会话的范围，例如：“在构建里程碑 1 的运行结束时编写”。交接文档只在某个时刻准确；没有日期的文档，即便早已失效，也会长期被信任。

如何撰写

• 假设读者只读过项目的 Agent 入门说明（AGENTS.md、CONTRIBUTING.md 或类似文件），除此之外一无所知。 明确说明这一点，并指向该说明。不要重述仓库的常设规则；要指向与这项工作涉及的代码对应的区域文档。
• 具体说明路径、分支和命令。“工作树”不是一个地址；../myapp-wt/spell-check（位于 spell-check/p4 分支）才是。
• 优先记录难以重新发现的事实。 Agent 通过一次 git log 或一次 grep 就能了解的内容，不必写成一段。花了你一小时才弄清楚的内容，需要写下来。
• 篇幅要足够精简，让人能在开始工作前读完。没人读完的交接，就什么也没交接。

放在哪里

• 将其写入 docs/<feature>/HANDOFF.md，并作为本次工作的最后一次提交，这样它描述的就是下一位 Agent 实际克隆的树。
• 直接更新原文件，不要再附加一份；一份过时的交接文档与一份当前文档并存，比两份都没有还糟糕。
• resume-handoff 是阅读者。它会在信任每项声明前对照树进行核验，因此要以可核验的形式写下可检查的事实——提交哈希、领先／落后数量、检出路径、父级提交上失败的测试名称——绝不要依赖私人记忆或下一次会话可能拿不到的笔记。用户同意方向后，它会删除该页面：交接文档是用完即弃的，而非持续维护的；使用它的会话会根据自己的树撰写下一份交接文档。
• 功能文档关闭后，close-plan 或 close-roadmap 会将其归档。