创建全面的交接文档，实现AI代理会话的无缝转移。触发条件：(1)用户请求交接/记忆/上下文保存，(2)上下文窗口接近容量上限，(3)主要任务里程碑完成，(4)工作会话结束，(5)用户说出'保存状态'、'创建交接'、'我需要暂停'、'上下文快满了'，(6)恢复工作时说'加载交接'、'从...恢复'、'继续之前的工作'。在完成大量工作（多次文件编辑、复杂调试、架构决策）后主动建议创建交接。通过让新代理零歧义地继续工作，解决长时间运行代理的上下文耗尽问题。
交接
创建全面的交接文档，使新AI代理能够零歧义地无缝继续工作。解决长时间运行代理的上下文耗尽问题。
模式选择
确定适用模式：
创建交接？ 用户想要保存当前状态、暂停工作，或上下文快满了。
- 遵循：下面的创建工作流
从交接恢复？ 用户想要继续之前的工作、加载上下文，或提到现有的交接。
- 遵循：下面的恢复工作流
主动建议？ 在完成大量工作（5次以上文件编辑、复杂调试、重大决策）后，建议：
"我们取得了显著进展。考虑创建交接文档以保留此上下文供将来会话使用。准备好后说'创建交接'。"
创建工作流
步骤1：生成框架
运行智能框架脚本以创建预填充的交接文档：
python scripts/create_handoff.py [task-slug]
示例：python scripts/create_handoff.py implementing-user-auth
对于延续交接（链接到之前的工作）：
python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
该脚本将：
- 如有需要，创建
.claude/handoffs/目录 - 生成带时间戳的文件名
- 预填充：时间戳、项目路径、Git分支、最近提交、修改的文件
- 如果从之前的交接继续，添加交接链链接
- 输出文件路径以供编辑
步骤2：完成交接文档
打开生成的文件，填写所有 [TODO: ...] 部分。优先处理以下部分：
- 当前状态摘要 - 当前正在发生的事情
- 重要上下文 - 下一个代理必须知道的关键信息
- 立即下一步 - 清晰、可操作的第一步
- 已做出的决策 - 带有理由的选择（不仅仅是结果）
使用 references/handoff-template.md 中的模板结构作为指导。
步骤3：验证交接
运行验证脚本以检查完整性和安全性：
python scripts/validate_handoff.py <handoff-file>
验证器检查：
- [ ] 没有剩余的
[TODO: ...]占位符 - [ ] 必需部分存在且已填充
- [ ] 未检测到潜在秘密（API密钥、密码、令牌）
- [ ] 引用的文件存在
- [ ] 质量评分（0-100）
如果检测到秘密或评分低于70，不要最终确定交接。
步骤4：确认交接
向用户报告：
- 交接文件位置
- 验证评分及任何警告
- 捕获的上下文摘要
- 下一个会话的第一个操作项
恢复工作流
步骤1：查找可用的交接
列出当前项目中的交接：
python scripts/list_handoffs.py
这将显示所有交接及其日期、标题和完成状态。
步骤2：检查过时程度
在加载之前，检查交接的新鲜程度：
python scripts/check_staleness.py <handoff-file>
过时级别：
- 新鲜：可以安全恢复 - 自交接以来变化很小
- 轻微过时：审查更改，然后恢复
- 过时：在恢复前仔细验证上下文
- 非常过时：考虑创建新的交接
该脚本检查：
- 自交接创建以来的时间
- 自交接以来的Git提交
- 自交接以来更改的文件
- 分支分歧
- 缺失的引用文件
步骤3：加载交接
在采取任何操作之前，完整阅读相关的交接文档。
如果交接是链的一部分（有“继续自”链接），也阅读链接的先前交接以获取完整上下文。
步骤4：验证上下文
遵循 references/resume-checklist.md 中的检查清单：
- 验证项目目录和Git分支匹配
- 检查阻塞项是否已解决
- 验证假设仍然成立
- 审查修改的文件是否存在冲突
- 检查环境状态
步骤5：开始工作
从交接文档中的“立即下一步”第1项开始。
工作时参考以下部分：
- “关键文件”用于重要位置
- “发现的关键模式”用于要遵循的约定
- “潜在陷阱”以避免已知问题
步骤6：更新或链接交接
工作时：
- 在“待办工作”中标记已完成项
- 将新发现添加到相关部分
- 对于长时间会话：使用
--continues-from创建新交接以链接它们
交接链
对于长期项目，将交接链接在一起以维护上下文谱系：
handoff-1.md (初始工作)
↓
handoff-2.md --continues-from handoff-1.md
↓
handoff-3.md --continues-from handoff-2.md
链中的每个交接：
- 链接到其前驱
- 可以将较旧的交接标记为已取代
- 为新代理提供上下文线索
从链恢复时，先读取最新的交接，然后根据需要参考前驱。
存储位置
交接存储在：.claude/handoffs/
命名约定：YYYY-MM-DD-HHMMSS-[slug].md
示例：2024-01-15-143022-implementing-auth.md
资源
scripts/
| 脚本 | 用途 |
|---|---|
create_handoff.py [slug] [--continues-from <file>] |
使用智能框架生成新交接 |
list_handoffs.py [path] |
列出项目中的可用交接 |
validate_handoff.py <file> |
检查完整性、质量和安全性 |
check_staleness.py <file> |
评估交接上下文是否仍然最新 |
references/
- handoff-template.md - 带有指导的完整模板结构
- resume-checklist.md - 恢复代理的验证检查清单
