session-handoff

交接

创建全面的交接文档，让新的 AI Agent 能够毫无歧义地无缝接续工作，解决 Agent 长时间运行导致上下文耗尽的问题。

模式选择

确定适用的模式：

要创建交接文档？ 用户想保存当前状态、暂停工作，或上下文即将满。

• 按照下方的 CREATE 工作流操作

要从交接文档恢复工作？ 用户想继续之前的工作、加载上下文，或提到现有的交接文档。

• 按照下方的 RESUME 工作流操作

主动建议？ 完成大量工作（编辑 5 个或更多文件、复杂调试、重大决策）后，建议：

“我们已经取得了显著进展。可以考虑创建交接文档，为后续会话保留这些上下文。准备好时，请说‘创建交接文档’。”

CREATE 工作流

步骤 1：生成脚手架

运行智能脚手架脚本，创建预填充的交接文档：

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py [task-slug] --model <your model ID>

示例：python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py implementing-user-auth --model claude-opus-5-5

使用你所运行模型的模型 ID 传入 --model：没有 CLI 会将其放入环境变量。若不传入，Model 行会保留为 [TODO]，验证器将阻止操作。

请在目标项目目录中运行：脚手架会从当前工作目录读取项目路径、 Git 分支和近期提交。

对于续接交接文档（链接到之前的工作）：

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

脚本将：

• 根据需要创建 .claude/handoffs/ 目录
• 生成带时间戳的文件名
• 预填充：时间戳、编写者（CLI 和会话 ID）、模型、主机名、项目路径、Git 分支、近期提交、已修改文件
• 若续接之前的工作，则添加交接链链接
• 输出供编辑的文件路径

步骤 2：完成交接文档

打开生成的文件，填写所有 [TODO: ...] 部分。优先填写以下部分：

1. 当前状态摘要 - 当前正在进行的工作
2. 重要上下文 - 下一位 Agent 必须了解的关键信息
3. 紧接着的下一步 - 清晰、可执行的第一步。每一项都要注明来源：用户原话或经用户审阅的工作记录。 用户原话是带日期的用户逐字表述；已填写的 Q-n ans: 也符合要求。 经用户审阅的工作记录是用户审阅过的成果页面或规范。交接文档或 Agent 记录不属于此类。 请将你自己的想法放在“Agent 提案（非用户要求）”下。
4. 已做出的决策 - 包含理由的选择（而不只是结果）
5. 错误与修正 - 有证据支持的错误方向和用户纠正；规则提案应放入 ~/.agents/retro-inbox/pending/，此处只写文件名

请参考 references/handoff-template.md 中的模板结构。

步骤 3：验证交接文档

运行验证脚本，检查完整性和安全性：

python3 ~/.agents/skills/session-handoff/scripts/validate_handoff.py <handoff-file>

验证器会检查：

• 是否仍有 [TODO: ...] 占位符
• 是否包含并填写了必需章节
• 是否检测到潜在机密信息（API 密钥、密码、令牌）
• 所引用的文件是否存在

验证器报告 BLOCKED 时，不要完成交接文档。 若检测到机密信息、仍有 [TODO: ...] 占位符或缺少必需章节，验证器会阻止操作并以非零代码退出。其他情况均为警告。

步骤 4：确认交接

向用户报告：

• 交接文件位置
• 验证结果（READY / BLOCKED）及任何警告
• 所记录上下文的摘要
• 下一次会话的首个行动项

RESUME 工作流

步骤 1：查找近期交接记录

多个会话可以同时在同一个仓库中工作，因此最新文件可能属于另一个会话。列出近期的交接记录，而不只是最新的一份：

ls -lt .claude/handoffs/*.md | head -10              # newest first
grep -H -E '^- (Written by|Session|CLI|Model|Host):' .claude/handoffs/*.md   # writer: manual and compact handoffs

阅读过去两天内与当前任务或文件有交集的每份交接记录。 还要阅读用户指定的交接记录，或任务交接链中链接的交接记录，即使它较早。 根据任务、文件和链路链接，选择与当前任务相关的交接记录。 Written by: 和 compact-<session id>.md 用于标识撰写者，撰写者可能是之前的会话。 不要把撰写者不同视为存在并行工作的证据。 撰写者缺失或为 UNCONFIRMED，表示撰写者未知。

步骤 2：检查是否过时

将交接记录自身的标头（时间戳、分支、提交）与当前仓库进行比较：

git log --oneline -- .            # commits since the handoff was written
git status --short                # uncommitted drift
git branch --show-current         # still the branch the handoff names?

如果交接记录是在另一个分支上编写的，或落后许多次提交，那么它只能作为线索，而非事实：采取行动前，重新核实其中的所有断言。

步骤 3：加载交接记录

采取任何行动前，完整阅读相关交接文档。

如果交接记录属于一条链（含有“Continues from”链接），也要阅读链接的上一份交接记录，以获取完整上下文。

完整阅读交接记录在任意章节中提及的每份用户审核过的工作记录。不要只通过关键词搜索来检查。

步骤 4：核实上下文

在说明范围或依据交接记录采取行动之前：

1. 项目目录和 git 分支与交接记录中的描述一致。
2. 列出的阻塞事项仍然是阻塞事项（它们可能已解决）。 先阅读每个 Q-n 及其 ans:：已填写但尚未执行的 ans: 是本次会话必须原样遵循的指示；空的 ans: 或 Suggested 值不代表获得批准。
3. 所述假设仍然成立——检查后续步骤所依赖的假设。
4. 修改过的文件没有与之冲突的后续工作。
5. 根据其来源检查每项 Immediate Next Step。阅读来源并确认其支持所列行动。 没有来源的条目是提议。无法核实来源的条目为 UNCONFIRMED。 绝不要将提议、UNCONFIRMED 条目或你自己提出的新想法说成用户的范围。用户引用内容优先于用户审核过的工作记录。若有多条用户引用，以较晚的一条为准。 Agent 撰写的条目绝不能凌驾于来源之上。说明冲突，并在说明范围或采取行动前更正交接记录。

步骤 5：开始工作

在处理“Immediate Next Steps”中的第 1 项之前，检查本次运行中最新的人类更正和授权。

工作时参考以下章节：

• “Critical Files”：重要位置
• “Key Patterns Discovered”：应遵循的约定
• “Potential Gotchas”：应避免的已知问题

步骤 6：更新或串联交接记录

工作期间：

• 在“Pending Work”中标记已完成的项目
• 将新发现添加到相关章节
• 对于较长的会话，使用 --continues-from 创建新的交接记录并串联起来

交接记录串联

对于长期项目，可串联交接记录，以保留上下文沿袭：

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

交接链中的每份记录：

• 链接到其前一份记录
• 可以将较早的交接记录标记为已被取代
• 为新的 Agent 提供上下文线索

从交接链中恢复工作时，先阅读最新的交接记录，再根据需要参考前序记录。

存储位置

交接记录存放于：.claude/handoffs/

命名约定：YYYY-MM-DD-HHMMSS-[slug].md

示例：2024-01-15-143022-implementing-auth.md

资源

scripts/

脚本	用途
create_handoff.py [slug] [--continues-from <file>]	使用智能脚手架生成新的交接记录
validate_handoff.py <file>	检查完整性、质量和安全性

列出交接记录和检查是否过时无需脚本——请参阅上方的 RESUME 工作流。

references/

• handoff-template.md - 包含说明的完整模板结构