会话交接

创建交接文档，使新代理能够无缝延续工作。

模式选择

是否要创建交接文档？ 用户希望保存当前状态、暂停工作，或上下文已满。 → 执行 CREATE 流程

是否要从交接文档恢复？ 用户希望继续之前的工作或加载上下文。 → 执行 RESUME 流程

是否需主动建议？ 在完成大量工作后（例如：修改 5+ 个文件、复杂调试、关键决策）：

“建议创建一份交接文档以保留当前上下文。准备就绪时，请说 ‘create handoff’。”

CREATE 流程

第 1 步：生成脚手架

运行智能脚手架脚本：

python scripts/create_handoff.py [task-slug]

如为延续性交接（需关联先前工作）：

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

该脚本将创建 .claude/handoffs/ 目录，并生成一个带时间戳的文件，其中预填充了元数据（时间戳、项目路径、Git 分支、最近提交记录、已修改文件列表）。

第 2 步：完善文档内容

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

1. 当前状态摘要 —— 当前正在发生什么
2. 重要上下文 —— 下一位代理必须了解的关键信息
3. 下一步待办事项 —— 明确、可执行的首个动作
4. 已做决策 —— 包含依据的决策说明（不仅列出结果）

完整结构请参阅 references/handoff-template.md。

第 3 步：验证文档

python scripts/validate_handoff.py 

校验项包括：

• 无残留的 [TODO: ...] 占位符
• 必需章节均已存在且已填写内容
• 未检测到潜在敏感信息（如 API keys、密码、tokens）
• 所引用的文件均真实存在
• 质量评分（0–100 分）

若检测到敏感信息，或质量评分低于 70 分，则不得完成交接文档。

第 4 步：确认并反馈

向用户汇报以下信息：

• 交接文档所在路径
• 验证得分及警告信息
• 已捕获上下文的简要总结
• 下一阶段的首个行动项

RESUME 流程

第 1 步：查找可用交接文档

python scripts/list_handoffs.py

第 2 步：检查时效性

python scripts/check_staleness.py 

时效性等级说明：

• FRESH：可安全恢复
• SLIGHTLY_STALE：恢复前需先审阅变更
• STALE：需谨慎核验上下文一致性
• VERY_STALE：建议新建交接文档

第 3 步：加载并核实

完整阅读交接文档；若属于交接链中的一环，还需一并阅读前序交接文档。

参照 references/resume-checklist.md 执行核验：

1. 确认项目目录与 Git 分支匹配
2. 检查阻塞问题是否已解决
3. 验证原有假设是否仍成立
4. 审查已修改文件是否存在冲突

第 4 步：启动工作

从 “Immediate Next Steps” 中的第一项开始执行。

工作过程中可随时参考以下内容：

• “Critical Files”：关键文件位置
• “Key Patterns Discovered”：已识别的重要约定
• “Potential Gotchas”：需规避的已知风险点

交接链（Handoff Chaining）

针对长期运行的项目，可通过链接多个交接文档来维持上下文的连续性：

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

质量标准

高质量的交接文档具备以下特征：

• 对当前状态的描述零歧义
• 下一步待办事项清晰、编号明确
• 关键决策附有合理依据（不只罗列结果）
• 必要时提供带行号的文件路径
• 不含任何敏感信息或凭据

严禁行为（NEVER）

• 在交接文档中包含 API keys、密码、tokens 或其他凭据
• 在最终版交接文档中遗留 TODO 占位符
• 跳过验证步骤
• 创建不含 “Important Context” 章节的交接文档
• 对质量评分低于 70 分的交接文档执行最终化操作