交接契约
交接契约
Handover 只承载「下一个 agent 从别处拿不到」的信息。已经写在 roadmap、Blueprint、ADR、commit、diff 里的内容，用路径引用，不复制。
1. 字段
| 字段 | 必填 | 作用 | 判据 |
|---|---|---|---|
| handover_version | 是 | 契约版本 | 当前为 1 |
| created_at | 是 | 判断新鲜度 | ISO-8601 |
| project | 是 | 项目名 | 与 repo 一致 |
| repo_root | 是 | 防止接错目录 | 绝对路径 |
| branch | 是 | 防止接错工作流 | 当前分支 |
| head | 是 | 判断 handover 后是否有新提交 | short SHA |
| dirty | 是 | 判断未提交改动 | true / false |
| predecessor | 是 | 谁写的 | agent / model / session |
| next_session_focus | 是 | 下一次接手的焦点 | 一句话 |
| secrets_redacted | 是 | 脱敏声明 | true |
| objective | 是 | 为什么做 | 完成定义可检查 |
| state | 是 | 现在到哪了 | 一段话 |
| done | 是 | 已完成 | 每条带证据 |
| in_progress | 否 | 半成品 | 停在具体位置 |
| next_action | 是 | 下一步 | 仅一个，可执行 |
| decisions | 是 | 别处没有的决策 | 含 why / rejected |
| open_questions | 否 | 未决问题 | 保留原话，标 owner |
| risks / gotchas | 否 | 坑 | 带触发条件与规避 |
| files | 是 | 读过/改过 | 机械列出 |
| verify | 是 | 怎么验证 | 命令 + 最近结果 |
| references | 是 | 权威文档 | 路径/URL，不复制 |
| do_not_redo | 否 | 不要重做 | 带证据 |
| suggested_skills | 否 | 下次该加载的 skill | 名称 + 理由 |
| handover_chain | 否 | 上一份 | 路径 |
模板见 交接模板。
2. 只写 delta
先问：这条信息是否已经存在于一个 durable doc？
- 是 → 写路径，不写内容。
- 否 → 写进 handover。
- 不确定 → 写进 handover，并标注「未在别处记录」。
复制 durable doc 的后果不是多写几行，而是制造第二真相源：两边迟早不一致，而下一个 agent 不知道该信谁。
3. 证据标准
| 断言 | 合格证据 | 不合格 |
|---|---|---|
| 功能已完成 | commit、测试输出、可运行产物 | 「应该可以了」 |
| bug 已修 | 复现步骤 + 修复后结果 | 「改了代码」 |
| 环境已配置 | 命令 + 输出 | 「装好了」 |
| 计划已变更 | ADR / issue / commit | 「我记得说过」 |
没有证据的项写进 In Progress 或 Open Questions，不写 Done。
4. 一个 next action
next_action 只能有一个。多个候选说明还没决定，写进 open_questions，不要并列成菜单让下一个 agent 自己选。
一个好的 next action：
修复 packages/api/src/auth.ts:88 的 token 刷新竞态；复现命令见 Verify；修完跑 auth 测试。
一个坏的 next action：
继续完善认证模块。
5. 脱敏
写入前检查：
- API key、token、password、cookie、私钥。
- 个人绝对路径、内网地址、客户数据。
- 会话里粘贴的隐私内容。
handover 默认在 .handoff/ 下并被 gitignore；即使如此也按会被别人看到的标准脱敏。
6. 长度预算
- 目标 ≤150 行。
- 超过时先删重复的 durable 内容，再把细节外置成链接。
- 不贴 transcript；需要原始轨迹时，下一个 agent 应该去读工具历史或日志，而不是读一份压缩过的对话复制品。
7. 质量门
写完逐项检查：
- 头部 branch / head / dirty 与当前一致。
-
next_action只有一个，且带文件/命令。 - 每个 Done 都有证据。
- durable docs 只出现路径，没有复制正文。
- open questions 保留了原话与 owner。
- 没有密钥、token、个人路径。
- ≤150 行。
- 与上一份 handover 的 chain 已连上。
8. 跨机器与归档
.handoff/ 默认是本机工作副本的会话 delta，不保证跨机器、跨 clone。
- 需要跨机器：由用户显式决定提交、同步或复制，不自动改版本控制边界。
- 需要历史：归档到 .handoff/archive/，用 handover_chain 串起来。
- 需要长期项目状态：写进项目自己的 status / roadmap / Blueprint，不要指望 handover 承担。