handoff

工作交接（Handoff）

同一个项目轮流让不同 agent（Claude Code / Codex / Kimi CLI…）来做，切换时会丢上下文、 留下半成品工作区，下一棒接手容易出错。这个 skill 把"人类同事交接班"那套协议固化下来： 交出方负责把现场交代清楚、留干净工作区；接手方负责对账后再动手。

核心分工：机械、确定性的事（采集 git 状态、探测测试命令、检查工作区是否干净）交给脚本， 保证不同 agent 行为一致；需要判断的事（总结进度、规划下一步）交给你（LLM）。

---

何时做哪个动作

• 用户在交出（要离开 / 要换 agent / "整理进度交接"）→ 走 A. 交接出去。
• 用户在接手（刚切过来 / "继续上一个 agent 的活" / "读一下进度"）→ 走 B. 接手。

判断不了就直接问一句："你是要把当前进度交接出去，还是接手上一棒的活？"

---

A. 交接出去（handoff）

目标产物：一份写实的 HANDOFF.md + 一个干净的工作区 + 一段可直接粘贴给下一棒的交接话术。

1. 采集客观事实（先跑脚本，别凭记忆）

bash <skill-dir>/scripts/handoff.sh

脚本会给出：当前分支、工作区是否干净、改动统计、最近 commit、疑似敏感文件、探测到的测试命令。 先读它的输出，再写总结。 你对"做了什么"的记忆可能漏或错，git 才是真相——拿脚本输出对账。

2. 写 HANDOFF.md

用 references/HANDOFF_TEMPLATE.md 的结构，写到项目根目录的 HANDOFF.md。 关键是"进行中"和"下一步"要具体到文件:行 + 思路 + 卡在哪 + 验证标准—— 让接手方不用猜就能继续，而不是"继续做认证功能"这种空话。

测试状态据脚本探测如实填：跑过且通过就写命令和结果；没跑或探测不到就写"未知/需人工"， 不要假装测试通过。

3. 提议 commit，等用户确认（不要自动提交）

把改动按逻辑分组，给出原子 commit 方案（每个 commit 一件事，conventional 风格的 message）， 列给用户看，等确认后再执行。这一步绝不自动跑——闷头 commit 可能把半成品或凭证提进去。

铁律：脚本"疑似敏感文件"里命中的（*.local.*、.env*、密钥证书等）绝不进交接 commit。 在 HANDOFF.md 里标注它们存在但不提交。

确认后按方案提交。该忽略的提醒用户加进 .gitignore。

4. 自检并报告

再跑一次 git status，确认工作区真的干净（除了刻意保留、且已在 HANDOFF.md 标注的本地文件）。 向用户报告：交接单写好了、提交了哪几个 commit、工作区状态、测试状态。 有没做完或不确定的，明说，别粉饰。

5. 产出可粘贴的「交接话术」给用户（默认主动给，别等用户开口）

报告完，主动附一段可直接整段复制、粘贴给下一棒 agent（Codex / Kimi…）的简短话术。 用户通常是手动把任务转交出去的：HANDOFF.md 是交接载体，这段话术是"点醒下一棒去读它、 并知道第一步干什么"的钥匙——没有它，用户就得自己再写一遍。漏给这段=交接没做完。

话术要素（精炼几句，用代码块包住方便整段复制）：

• 项目路径 + 分支；第一句就让它读 HANDOFF.md 全文（+ 必要时 DESIGN.md/CLAUDE.md）再动手，并跑 pickup.sh 对账。
• 一句话交代当前状态（已完成 / 待推进）。
• 点明接手后第一步做什么；若有悬而未决、需先和用户确认的，写明"先别埋头改，先给方案等拍板"。
• 关键约束（交流语言、设计系统、测试 / 部署方式…）一句带过，细节让它去 HANDOFF.md 看。
• 末尾要求它先复述理解 + 说清第一步，再开干（呼应 B 的接手纪律）。

---

B. 接手（pickup）

目标：在动手前确认"交接单说的"和"仓库真实状态"一致，把上下文真正装进来。

1. 读交接单 + 对账

bash <skill-dir>/scripts/pickup.sh

脚本会打印 HANDOFF.md 全文，并把当前工作区状态、最近 commit 摆出来供核对。

2. 核对一致性

• 交接单说"工作区干净"，脚本却显示 DIRTY？→ 上一棒没交接干净，先向用户指出，别假装没看见。
• 交接单提到的 commit hash 在 git log 里找得到吗？找不到说明分支/状态对不上，先澄清。
• 标注"不提交"的敏感文件还在且未被误提交吗？