handoff

交接

维护 .docs/handoff.md，将其作为项目本地的冷启动指南，供下一位编码 Agent 或人工开发者使用。该文件仅记录临时会话状态：有哪些变更、做出了哪些决定、存在哪些阻碍，以及如何准确地继续工作。

参考文件

文件	内容	何时加载
references/schema.md	逐字呈现的交接模式和行数预算规则	写入前始终加载
references/authority-boundaries.md	交接、记忆、CLAUDE.md、计划和 git 之间的边界	写入前始终加载

何时使用

使用交接	使用其他位置
进行中的工作、未提交的编辑、当前分支、阻碍、恢复步骤	已提交的历史记录使用 git log
会话范围内的决定和失败的尝试	持久的项目事实使用记忆或 ADR
即时验证状态和准确的下一条命令	稳定的设置说明使用 CLAUDE.md
当前路线图进度位置	战略路线图内容使用计划文件

触发条件

• 直接命令：/handoff、/handoff init
• 刷新短语："update handoff"、"session handoff"、"refresh handoff"、"save handoff"
• 恢复短语："cold-start primer"、"resume checklist"、"handoff to next session"
• 停止钩子：若 .docs/handoff.md 已存在，则静默刷新

前置条件

• 项目根目录中可用 git。
• 对 .docs/handoff.md 有项目写入权限。
• 可选的项目本地标记文件：
  • .docs/handoff.last-validation，包含最近一次验证命令及其结果。
  • .docs/handoff.session，包含有关变更、决定、阻碍或参考资料的额外条目。

工作流

1. 确定模式。
   • /handoff init 或从初始化工作流中调用时，若 .docs/handoff.md 不存在，则写入全新项目的占位内容。
   • /handoff、刷新短语和停止钩子调用会重写整个文件。
2. 读取事实来源。
   • 加载 references/schema.md，并准确保留模式中的标题。
   • 加载 references/authority-boundaries.md，并在每份生成的交接中包含权限边界说明行。
3. 检测仓库状态。
   • 运行 git rev-parse --show-toplevel、git branch --show-current、git rev-parse --short HEAD 和 git status --porcelain。
   • 根据 porcelain 状态统计已修改、未跟踪和已暂存的路径数量。
   • 在状态部分列出排名前 3–5 的变更路径。
4. 检测验证状态。
   • 优先使用最近的会话上下文：当前 Agent 会话中实际运行的命令及其结果。
   • 如果可用，读取 .docs/handoff.last-validation。
   • 如果两者都不存在，则明确写明 "not recorded this session"，不要编造通过或失败的结果。
5. 收集会话实质内容。
   • 根据当前对话、未提交路径，以及相关分支基点之后的提交，总结逻辑变更。
   • 用不超过两句话记录决定及其理由。
   • 将阻碍和未决问题记录为可执行的未勾选事项。
   • 记录可能导致下一会话重复浪费时间的失败尝试。
6. 完整重写文件。
   • 以原子方式替换 .docs/handoff.md；不要追加内容。
   • 如果 .docs/ 不存在，则创建该目录。
   • 文件名使用小写：.docs/handoff.md。
7. 确保不超过 200 行。
   • 渲染后统计最终行数。
   • 如果超过 200 行，则从最早的内容开始截短 ## What changed this session。
   • 插入 ``。
   • 如果仍超过 200 行，则压缩决定和阻碍，只保留最新的可执行事项，同时保留所有必需标题。

支持的操作

操作	命令	行为
刷新	/handoff	根据当前仓库和会话状态重写 .docs/handoff.md
搭建框架	/handoff init	当不存在交接文件时，创建空白模式占位文件
停止时刷新	停止钩子	仅当 .docs/handoff.md 已存在时刷新
试运行	uv run skills/handoff/scripts/handoff.py --dry-run	打印生成的内容，不写入文件

实现说明

打包的脚本是命令和钩子使用的确定性基准：

uv run skills/handoff/scripts/handoff.py --project-root "$PWD"
uv run skills/handoff/scripts/handoff.py --project-root "$PWD" --init

Agent 可以根据实时会话上下文改进已填写的项目，但必须保留：

• 架构标题和顺序。
• 权限边界行。
• 完整文件重写语义。
• 200 行硬性上限。
• 明确标注未知信息，不得静默回退。

全新项目脚手架

当以 /handoff init 调用，或在项目初始化流程中调用，且 .docs/handoff.md 不存在时，写入包含空占位符和真实 Git 元数据的架构。这记录了 /init 集成点，但不会修改任何初始化脚本。

输出格式

只写入一个文件：.docs/handoff.md。

必需的首行：

# Handoff — <project name>

**Last touched:** <ISO 8601 timestamp with timezone> · **branch:** `<branch>` · **HEAD:** `<short-sha>` · **session:** <model id>

故障排查

问题	解决方案
不在 Git 仓库中	刷新时明确报错；仅在 /handoff init 期间，脚手架可以使用分支 — 和 HEAD —
缺少 .docs/	写入前创建该目录
验证状态不可用	写入“本会话未记录”；不得声称测试已通过
生成的文件超过 200 行	截断最早的 What changed 项目，并添加警告注释
现有交接文件使用旧大小写或根目录路径	不要自动迁移；仅当在该项目中调用后续刷新时才会逐步统一

验证

• uv run python scripts/validate_evals.py
• uv run scripts/evaluate_package.py skills/handoff
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --dry-run
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --init --output <tmp-file>