handoffkit

handoffkit

将这段对话中学到的所有内容整理成一份交接文档，让一个全新的 Agent 在不了解此处上下文的情况下，也能阅读并继续工作。目标是传递信息，而非存档：记录仅存在于本次会话中的状态和推理，并指明已有的相关产物（规范、PR、提交、差异、问题），而不是复制它们。默认将文档保存为 docs/handoffs/ 下的 Markdown 文件；只有用户明确要求以内联内容或终端输出的形式提供，或没有可写入的文件系统时，才将其作为可复制粘贴的代码块输出。

何时触发

当用户希望跨越上下文边界保持工作连续性时触发，例如：“编写交接文档”“交接这项工作”“为下一次会话总结”“移交给另一个 Agent”“在上下文耗尽前整理内容”。如果用户提供了参数（例如“为完成迁移编写交接文档”），则将其视为下一次会话的重点，并让整份文档围绕这一重点展开。先说明实现该目标所需的信息，并删去无关内容。

应包含和排除的内容

交接文档的价值在于记录新 Agent 无法自行还原的信息：

• 包含：目标及其重要性；已完成和待处理事项；紧接着要采取的行动；已作出的决策及其理由；已排除的失败方案；注意事项、约束条件，以及如何运行和验证。
• 排除（改为引用）：已有文档中记录的内容，包括规范、ADR、计划、问题、提交说明、差异和 PR 描述。通过路径或 URL链接到这些内容；不要粘贴其正文。重复说明差异的交接文档只会造成噪声。
• 脱敏：API 密钥、令牌、密码和个人身份信息。切勿将机密信息写入文档。只提及其名称（例如“.env 中的暂存数据库密码”），不要写出具体值。

文档结构

编写以下各节；确实没有内容的章节应删除，不要为凑数而填充内容。

分两种语体，按章节区分。 当前状态、后续步骤和如何运行／验证面向实际执行工作的人，因此应使用 ASD-STE100 简明技术英语：每句话只包含一条指令；步骤性句子不超过 20 个词；使用主动语态和现在时；明确说明执行者；不使用隐喻或习语；整份文档对同一事物使用同一个术语。如果开头称其为工作者，结尾就不要称其为作业运行器。目标和决策与约束面向尚未动手、正在权衡判断的人，因此保留普通行文和完整推理；将被否决的方案改写成简短步骤会抹去其中的理由，导致下一个 Agent 重复犯错。

# Handoff: <one-line title of the work>

## Goal
What we're trying to achieve and why. If the user gave a focus argument, frame this around it.

## Workspace
Required when the task involves code. The repository root and the worktree path, the branch, the HEAD SHA, the upstream and the count of unpushed commits, the dirty state (each modified, staged, or untracked path, or "clean"), and any stash the session made.

## Current state
What's done and working, what's half-done, what's untouched. Be concrete. Name each check that has not run or is failing, with the command that shows it.

## Next steps
The ordered actions the next agent should take. Start with the very first one.

## Key files & artifacts
Paths and URLs that matter (source files, the spec, the open PR, the failing test). Reference, don't reproduce.

## Decisions & constraints
Choices made and *why*; approaches already ruled out; hard limits and things not to break.

## Open questions / blockers
Unknowns, pending answers, or anything waiting on the user.

## How to run / verify
Commands to build, run, or test, enough to reproduce the current state.

## Suggested skills
Capabilities the next session should reach for, e.g. a commit skill to land the work, a PR skill to open the pull request, a test-plan skill to verify. Name them by function, not by a specific tool that may not be installed. Recommend by relevance to the goal.

流程

1. 重读会话。 浏览对话，梳理目标、当前状态、已做决定和未解决事项。这些就是原始素材。每个部分都有对应内容或确认为空时，此步骤即完成。

2. 任务涉及代码时，读取工作区。 从 git 读取，切勿依赖对会话内容的记忆，因为会话可能早于最近一次提交：

   git rev-parse --show-toplevel; git worktree list
   git branch --show-current; git rev-parse HEAD
   git rev-parse --abbrev-ref @{upstream}; git rev-list --count @{upstream}..HEAD
   git status --short; git stash list
   

   Bash 仅用于这些只读查询。上游查询失败即表示“没有上游”，文档中会说明这一点。每个 工作区 字段都在本次运行中读取并填写后，此步骤即完成。

3. 区分交接内容与参考资料。 对每项值得提及的内容，判断它是仅存在于本次聊天中（交接）还是已有对应产物（链接）。每项内容都标注为其中一种后，此步骤即完成。

4. 按上述结构起草文档，并根据给定的重点论点调整侧重。每句话都包含任何已链接产物未涵盖的信息、所有空章节均已删除，且 后续步骤 以一项后续 Agent 无需继续阅读即可执行的操作开头时，草稿即完成。

5. 脱敏。 输出前删除任何秘密或个人身份信息。确认没有按原值出现的密钥、令牌、密码或个人信息后，此步骤即完成。

6. 按下方输出规则保存或打印，然后按照交接结束。

输出

默认：保存为 Markdown 文件。 将完成的交接文档写入工作区的 docs/handoffs/，如果该目录不存在则创建。文件名使用 NNNN-handoff-<slug>-YYYY-MM-DD.md，其中包含下一个序号、简短的小写 kebab-case 主题 slug，以及交接文档的 ISO 创建日期（例如 0005-handoff-auth-migration-2026-07-13.md）。要获取序号 NNNN，请检查当前工作树、git worktree list 列出的所有其他工作树，以及 origin/HEAD（执行 git fetch origin 后运行 git ls-tree --name-only origin/HEAD docs/handoffs/），找出 docs/handoffs/ 中所有以四位数字开头的最高序号并加一；若不存在，则从 0001 开始。请检查全部三个来源，以免并行工作树使用相同序号。跳过检查失败的来源，例如没有远程仓库；如果没有 git，则只列出目录内容。每个目录的序号独立分配，且永不重复使用。修改同一份交接文档时，文件名保持不变，并在原文件中更新。

告知用户确切路径。

明确要求时：以内联方式打印。 如果用户明确要求在终端、以内联方式、仅在聊天中或以可复制粘贴的形式输出，则将完成的交接文档放在单个 Markdown 代码块中输出，且不要写入文件。

没有可写文件系统时：优雅降级。 如果环境无法写入文件，则将完成的交接文档放在单个 Markdown 代码块中输出，并说明未创建文件。

交接

本节使用程序性语气：每句话只包含一条指令，使用主动语态和现在时，不使用比喻。

变更内容。 项目本身没有变化；交接文档是新增或更新的文件，并说明是哪一种。

保存位置。 给出确切路径（docs/handoffs/NNNN-handoff-<slug>-YYYY-MM-DD.md）；如果以内联方式输出，则写“已以内联方式打印，未写入文件”。

下一步。 只安排一项操作。启动一个新会话，并以本文档为起点，首先执行交接文档中的第一项下一步。请在此处说明该步骤，让用户无需打开文件即可了解。此会话到此结束，不再执行其他操作；交接的目的就是结束当前上下文。