handoff

交接文档

生成结构化的 HANDOFF.md 文件，为新的 Claude 会话提供继续这项工作所需的一切，避免当前退化的上下文影响后续工作。

claude-mem 已经会在每个新会话中注入最近的观察记录，因此新的 Agent 一开始就能看到事件时间线。交接文档会补充时间线无法提供的信息：目标、失败的尝试及其失败原因、当前推测、精确的后续步骤，以及便于深入查阅记忆的指引。

适用场景

• 会话很长，Claude 开始感到困惑或重复
• Claude 一直反复尝试同一个失败的方案
• 用户想暂时离开，稍后再继续
• 运行了 /compact，但 Claude 仍然缺少明确方向
• 用户说“交接”“生成交接文档”“我想重新开始”或“写一份交接文档”

需要记录的内容

撰写前，认真梳理整个对话的来龙去脉。交接文档必须能帮助一个从未看过这段对话的 Claude 实例继续工作。

必需章节

1. 目标 — 用一段话说明用户实际想完成什么。描述最终状态，而非当前子任务。具体到足以让新的 Agent 立即了解情况。

2. 当前状态 — 说明目前哪些部分正常、哪些部分出问题，以及问题的确切表现。如有相关错误消息，请原样引用。

3. 涉及的文件 — 列出本次会话中所有已读取、编辑或创建，且与当前任务相关的文件。使用绝对路径或相对于仓库的路径，并用一行说明每个文件的重要性。

4. 已尝试的方案（及失败原因） — 这是最重要的章节。列出每个未奏效的尝试，并解释失败原因（不能只说失败了）。新的 Agent 如果跳过本节，就会重复相同的错误。

5. 当前最佳推测 — 说明目前认为正确的推进方向，即使尚未验证。列出支持这一推测的证据或理由。

6. 后续步骤 — 为新的 Agent 提供具体、按顺序排列的操作。明确列出文件路径、函数名和要运行的命令。新的 Agent 应能立即开始执行第 1 步。

7. 关键约束和背景 — 记录不明显的约束：环境细节、本次会话中表达的用户偏好、用户明确要求不要做的事、外部依赖、性能要求等。

8. 记忆指引 — 如果可以使用 claude-mem 的搜索工具，请使用 Smart search：针对本任务的关键词运行 search，检查相关结果附近的 timeline，然后仅用 get_observations 获取选定记录。列出最重要的几条观察记录 ID（例如决策、根本原因、失败方案），以便新的 Agent 找回这些记录。另列出一到两个值得重新运行的 search 查询。如果无法使用这些工具，则跳过本节。

写作规则

• 面向新的 Claude 撰写交接文档，而不是面向用户。用户知道发生过什么；新的 Claude 不知道。
• 务必具体。含糊的后续步骤毫无用处。“修复身份验证”不够好。“在 src/auth/middleware.ts:47 中，令牌过期检查使用了 Date.now()，但应该使用 req.timestamp——修改第 52 行的比较逻辑”才够好。
• 包含能体现失败情况的准确错误消息、堆栈跟踪或测试输出。
• 不要凑字数。每句话都必须对新的 Agent 有实际帮助。
• 不要以用户的口吻撰写交接文档。应将其写成面向接手 Agent 的简报。

输出

将交接文档写入当前工作目录（项目根目录）下的 HANDOFF.md。

使用以下结构：

# Handoff

> Generated: [timestamp]  
> Project: [project name or directory]  
> Session summary: [one sentence describing what this session was about]

## Goal

[What the user is trying to accomplish — the actual end state]

## Current State

**Working:**
- [list what is confirmed working]

**Broken:**
- [exact symptom, error message, or failure mode]

## Files in Play

| File | Why It Matters |
|------|---------------|
| `path/to/file.ts` | [one line] |

## What Has Been Tried (and Why It Failed)

### Attempt 1: [short name]
- **What:** [what was done]
- **Why it failed:** [root cause, not just "it didn't work"]

### Attempt 2: [short name]
...

## Current Best Theory

[What you currently believe is the correct approach and why]

## Next Steps

1. [Specific, actionable step with file path or command]
2. [Next step]
3. ...

## Key Constraints

- [Non-obvious constraint or preference the user expressed]
- [Things explicitly ruled out]

## Memory Pointers

- Observations: [#ID — one line on why it matters]
- Searches worth re-running: [`search` query]

写完后

告诉用户：

1. 已写入 HANDOFF.md
2. 运行 /clear 或启动新的 Claude Code 会话
3. 打开新会话并说：“Read HANDOFF.md and continue from where we left off.”
4. claude-mem 会自动向新 Agent 提供近期时间线，而 HANDOFF.md 则在此基础上提供精准简报
5. HANDOFF.md 是临时文件：不要提交它（新会话接手后将其删除，或将其添加到 .gitignore）

保持消息简短。用户已经准备好继续了——不要让他们读一大段文字。