name: session-handoff description: “创建全面的交接文档，实现AI代理会话的无缝转移。触发时机：(1) 用户请求交接/记忆/上下文保存，(2) 上下文窗口接近容量，(3) 主要任务里程碑完成，(4) 工作会话结束，(5) 用户说‘保存状态’、‘创建交接’、‘我需要暂停’、‘上下文快满了’，(6) 使用‘加载交接’、‘从…恢复’、‘继续之前的工作’恢复工作。在大量工作后（多次文件编辑、复杂调试、架构决策）主动建议交接。通过使新代理无歧义地继续工作，解决长时间运行代理上下文耗尽问题。”

交接

创建全面的交接文档，使新的AI代理能够无缝且无歧义地继续工作。解决长时间运行代理上下文耗尽的问题。

模式选择

确定适用哪种模式：

创建交接？ 用户希望保存当前状态、暂停工作，或上下文快满了。

遵循：下面的创建工作流

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

遵循：下面的恢复工作流

主动建议？ 在大量工作后（5次以上文件编辑、复杂调试、主要决策），建议：

“我们已经取得了显著进展。考虑创建交接文档以保存此上下文供未来会话使用。当准备好时说‘创建交接’。”

创建工作流

步骤1：生成脚手架

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

python scripts/create_handoff.py [任务缩写]

示例：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 <交接文件>

验证器检查：

[ ] 没有剩余[TODO: ...]占位符
[ ] 必需部分存在且已填充
[ ] 未检测到潜在秘密（API密钥、密码、令牌）
[ ] 引用的文件存在
[ ] 质量分数（0-100）

不要最终化检测到秘密或分数低于70的交接。

步骤4：确认交接

向用户报告：

交接文件位置
验证分数和任何警告
捕获上下文的摘要
下次会话的第一个行动项

恢复工作流

步骤1：查找可用交接

列出当前项目中的交接：

python scripts/list_handoffs.py

这显示所有交接的日期、标题和完成状态。

步骤2：检查陈旧性

在加载之前，检查交接的当前程度：

python scripts/check_staleness.py <交接文件>

陈旧性级别：

新鲜：安全恢复 - 自交接以来变化最小
略微陈旧：审查变化后恢复
陈旧：在恢复前仔细验证上下文
非常陈旧：考虑创建新的交接

脚本检查：

自交接创建以来的时间
自交接以来的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-[缩写].md

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

资源

scripts/

脚本	用途
`create_handoff.py [缩写] [--continues-from <文件>]`	生成具有智能脚手架的新交接
`list_handoffs.py [路径]`	列出项目中的可用交接
`validate_handoff.py <文件>`	检查完整性、质量和安全性
`check_staleness.py <文件>`	评估交接上下文是否仍当前

references/

handoff-template.md - 完整的模板结构及指导
resume-checklist.md - 恢复代理的验证检查清单