claude-handoff

Claude 交接

此技能会在明确批准计划后，协调当前会话中的只读调查或实现工作。task-handoff 会为一个全新、独立的会话写入一份决策完备的文件。对于之后或在其他地方继续的工作，请使用 task-handoff。若要立即实施已批准的计划，请使用会话内交接。

如果斜杠命令或美元符号调用已提供这些指令，请直接遵循，不要再通过技能工具调用此技能。

遵循下方的契约，然后使用 Claude Code 的会话内 Agent 工作流，在规划期间开展调查，并实施已批准的计划。

契约

• 仅在用户明确调用后运行。如果用户要求的结果是发现、证据或评估，且未要求更改代码库或制定实施计划，则将任务归类为仅研究。所有交接均可在任何宿主模式下运行。实施交接必须经过规划阶段，并在启动前获得用户明确批准。
• 如果预期结果和重要约束未变，则复用已批准的计划。用户明确指示优先于技能默认设置。仅当存在尚未解决的决策或超出授权范围的操作时，才再次询问。
• Claude 负责决策、最终计划和协调。只有当任务和代码库证据表明规划前进行调查有助益时，才委派给只读研究子 Agent。
• 研究 Agent 收集证据并报告发现。它们不得编辑文件、决定设计或返回计划。
• 实施 Agent 检查、编辑并验证其负责的已批准计划部分。它们不得重新设计或返回另一份计划。
• 使用规模最小且有效的团队。一个 Agent 也可以。仅当拆分能显著改善延迟、正确性或验证时，才增加 Agent。每次交接的实施 Agent 不得超过八个。
• 确定团队前，估算每项工作说明的实际耗时。将预计需要超过约 25–30 分钟的工作拆分为并行且互不重叠的范围，或按依赖关系分波次处理。必要时增加集成 Agent。
• 研究 Agent 最多使用三个，ID 固定为 R1–R3，与八个实施 Agent 分开计数。
• Claude 自身的工作仅限协调、完整性检查、故障处理和有条件的润色。
• 让 Claude Code 自行选择前台或后台交付方式。只有直接的终端结果或错误，或之后收到的完成或失败通知，才能确认 Agent 已结束。启动确认、原生任务行、静默期或显示的权限提示都不表示 Agent 已结束。只有在收到所有必要的最终结果后，才能完成一波任务的核对。
• 将用户明确指定的模型偏好（例如 Sonnet、Opus）视为对所有研究和实施 Agent 的协调约束，除非用户对其范围作了更窄的限定。在该范围内，绝不替换为通常选择的 Sonnet／Opus。如果 Agent 工具无法启动该模型，请报告不兼容情况，并在改用其他模型前征求同意。
• 以已批准的结果作为授权边界，而不是初始清单或其写入范围。如果实施过程中发现相关的代码库内修复或证据变更是实现该结果所必需的，Claude 可以扩展交接范围。Claude 可以在无需再次询问的情况下，为这项必要工作启动后续 Agent。发现问题的子 Agent 仍须遵守其分配范围并返回证据。Claude 负责扩展范围、协调和委派。
• 验证工作应与所请求的结果相称。除非已批准的计划明确要求，否则不得增加验证机制（门禁、清单、检查点、哈希固定、日志、回执）。如果用户明确要求尽快完成或收尾，则可跳过可选的重复检查和必要的润色阶段。在这种情况下，提交已验证的工作，并报告跳过或未经验证的事项。

如果存在 $ARGUMENTS，请将其用作任务；否则，使用当前用户请求。若任务指定了其他技能，请遵循 Companion Skills。

配套技能

如果某项任务在交接说明中提到了另一项技能，例如： run $fresh-eyes-sweep and delegate the implementation，那么这就是一次组合调用。配套技能负责定义工作内容；本交接说明负责管理委派机制。

• 在 Claude 中加载配套技能，并执行其发现、判断和规划阶段。如果能显著提高效率，则通过本技能的研究 Agent 执行只读发现。然后将配套技能的方法、发现结果和约束纳入交接计划。技能列表中缺少的配套技能可能已安装，但被 disable-model-invocation: true 隐藏。确认其不存在前，请直接读取 ~/.claude/skills/<name>/SKILL.md。
• 如果配套技能的发现工作本身就是大部分工作（例如审计或全面检查整个代码仓库或大量文件），Claude 应绘制范围并划分任务，而不是在行内阅读。计划获批后，每个实施 Agent 都应根据配套技能规则审计并修复自己的部分；相关规则须直接写入任务说明。
• 本约定优先于配套技能中与之重叠的计划审批、Agent 数量限制、稳定 ID、单一验证负责人和结果字段要求；也优先于其故障分类、提交负责人和完成情况报告要求。即使配套技能规定了自己的子 Agent、验证或提交机制，这些覆盖规则仍然适用。配套技能中的用户决策关卡仍然有效。本技能的计划审批可满足重合的关卡。仅规划型的配套技能，只有在组合调用要求实施且用户批准计划后，才执行实施。
• Agent 无法加载技能。绝不要在任务说明中仅以技能名称要求 Agent“使用技能 X”。应将其所需的具体配套技能说明、规范或摘录直接写入任务说明。
• 配套技能要求运行 $code-polish 或 $agents-brain maintain，表示该步骤必须纳入规划阶段。每次完成时仍只运行一次。配套技能的提交说明不会额外要求提交。
• 完成时同时满足两份约定：除完成报告外，还须提供配套技能要求的报告产物（台账、表格、判定结果）。

研究阶段

对于纯研究任务，启动 1 到 3 个研究 Agent，并在返回汇总调查结果后停止。 对于这类任务，绝不进入计划阶段或启动实现 Agent。对于实现交接，当范围不明确、任务涉及多个或不熟悉的子系统，或串行收集证据会明显更慢时，启动研究。对于实现交接，默认启动 0 个研究 Agent。由 Claude 根据任务和仓库证据决定数量。绝不询问用户是否选择加入或指定 Agent。

触发研究时，为最多 3 个 Agent 分配稳定 ID R1-R3。立即通过 Agent 工具启动它们，并设置 subagent_type: "Explore" 和明确的模型，除非用户已指定模型偏好。若未指定模型偏好，对范围明确的调查使用 sonnet，对涉及多个或不熟悉子系统的深入调查使用 opus。省略 model 会继承会话的模型。只读的 Explore 工具集使其在任何模式下都可以合法启动。

当宿主的计划模式规定了自己的探索和规划子 Agent 时，本技能的研究 Agent 即为探索部分。Claude 自行编写计划，不启动规划子 Agent。

在一条消息中并行启动所有选定的 Agent。随后发送 🔎 Research started — <n> agents。之后依赖原生子 Agent 进度显示。不要创建仪表板。

为每个 Agent 提供独立完整的提示词，包含待解答的问题、确切的调查范围、所有与任务相关的仓库约束，以及只读边界。注明详尽程度提示（范围明确的调查使用 medium，涉及多个子系统的深入调查使用 very thorough）。Explore 不会加载项目的 CLAUDE.md。绝不要假设这些约束会自动传达。要求提供发现、证据、未决问题和阻碍因素。禁止返回计划或设计。

研究这一轮结束后，阅读每个结果，并将发现和证据纳入实现计划或纯研究答复。仅当未决问题或阻碍因素会改变范围或方案时，才通过 AskUserQuestion 提出。研究 Agent 不得更改任何内容。不要整理工作树。如果结果报告了编辑操作，须标记为违反约定。

Explore Agent 是一次性的，不会返回可复用的 Agent ID。绝不要对其应用实现延续规则。将缺少所需证据视为汇总结果中的未决问题或阻碍因素。

对于纯研究任务，综合证据，并以 ### 🔎 Research handoff — <completed|blocked> 收尾，注明 Agent 数量、发现、证据、未决问题和阻碍因素；以此取代计划阶段和完成报告。如果调查显示需要进行更改，将其作为发现报告并停止。在这种情况下，不要制定计划或开始编辑。

计划阶段

仅在实现交接时进入此阶段。

如果研究结果（无论是委派所得还是 Claude 自行研究）与用户明确陈述的事实（数量、涉及哪些项、涉及哪些账户）相矛盾，须在编写计划前通过 AskUserQuestion 提问。在这种情况下，绝不要扩大计划的默认范围来迁就研究结果。

制定包含以下部分的完整决策计划：

## Claude Handoff

- Research: `<none | R1..Rn — key findings used>`
- Companion skills: `<none | $x — phases Claude runs / what is folded into briefs>`
- Strategy: `<sequential|parallel|hybrid>`
- Agents: `<1-8>` — `<why this is the smallest effective count>`
- Validation owner: `<agent-id|claude>` — `<aggregate checks it runs once>`

| Agent | Wave | Depends on | Scope              | Model            | Implementation brief                                   | Completion evidence                 |
| ----- | ---- | ---------- | ------------------ | ---------------- | ------------------------------------------------------ | ----------------------------------- |
| `A1`  | `1`  | `none`     | `<files/behavior>` | `<sonnet\|opus>` | `<outcome, edits, constraints, and stopping criteria>` | `<commands and observable results>` |

- Code polish: `<required|not required>` — `<reason>`
- Agent-context maintenance: `<required|not required>` — `<reason>`

清单表格的每个单元格都必须保持在一行内。如需更多内容，请将其放在下方对应的 Agent 标题下。 在最终确定计划时，使用 ai-coord draft --name <plan-slug> '<label>' '<path>'... 记录所有清单写入范围的并集；仅当范围是目录时才使用 --recursive。根据计划的简短标识（例如 debarrel-lib）生成 <plan-slug>：将其转换为小写，把 [A-Za-z0-9._-] 以外的字符替换为 -，并截断至 40 个字符。对于两个或更多 Git 根目录，使用 ai-coord bundle draft --name <plan-slug> '<label>' '<absolute-path>'...。在计划的“等待冲突 Agent 结束”部分，写入准确的 promote 命令 ai-coord start --draft <plan-slug>（或 ai-coord bundle start --draft <plan-slug>），并保留针对同一并集的显式 ai-coord start '<label>' '<path>'... 后备命令（或 ai-coord bundle start '<label>' '<absolute-path>'...）。

新的实现会话必须直接从计划中获得这些命令，不得从说明性文字中重新推导范围。仅当 promote 报告 no draft named ... 时才使用后备命令。命名草稿不授予任何权限，并会在七天后过期。

根据仓库证据和已批准的工作选择执行方式：

• 顺序执行：一个 Agent 依赖另一个 Agent、写入范围有重叠，或后续 Agent 负责集成／整体验证。
• 并行执行：仅适用于彼此独立的工作，且必须明确划分互不重叠的写入范围。Agent 可以查看共享上下文，但不得在其范围外写入。
• 混合执行：按依赖关系划分多个波次——在每个波次内并行运行独立 Agent，协调该波次的工作后，再启动依赖该波次的 Agent。

一个波次要等其中最慢的 Agent 完成后才算结束。将可延后的验证交给验证负责人。如果并行工作无法共同证明计划已完成，则预留一个后续顺序执行的 Agent，负责集成和整体验证。

每次交接时，整体验证必须只分配给一位负责人。整包或全仓库检查（完整测试套件、整包类型检查／lint、全目录检查）只运行一次。如果有集成 Agent，就由其运行；否则，由 Claude 在波次后的协调阶段运行。对于其他 Agent，要求以最精简的检查证明其自身修改已完成。检查应限定在所触及的文件，包括文件级 lint／格式／类型检查以及针对性测试。

如果未指定模型偏好，应根据工作内容为每个实现 Agent 选择模型：

工作	模型
范围明确、常规或日常实现	sonnet
语义性、跨领域或最复杂的实现：涉及相互作用的不变量或困难的算法推理	opus

sonnet 和 opus 别名分别对应 Anthropic API 上的 Sonnet 5.5 和 Opus 5.5。Agent 工具不提供按调用设置推理强度的选项。子 Agent 继承会话的推理强度。每个 Agent 都通过 general-purpose 子 Agent 类型运行。模型选择和范围拆分应兼顾波次需求。

对于非局部不变量、并发或状态机、迁移或解析、身份验证或安全、重试或错误语义，以及公共 API 或数据契约变更，必须要求使用 $code-polish。文件数量本身不构成触发条件。

如果已批准的工作会修改其维护工作流支持的目标，则必须要求 $agents-brain maintain：README.md、AGENTS.md 或 CLAUDE.md、持久上下文文档、.agents/skills 下现有的项目已安装技能，或 skills/ 下现有的 Git 跟踪源目录技能（仅限事实性上下文修正且只涉及说明文字）。托管 Agent 配置根目录下已安装的副本不在此列。如果同时符合两条触发规则，则要求执行两项检查；如果两者均不符合，则均不要求。

在用户批准计划之前，不得启动实现子 Agent。只读研究阶段是唯一的批准前例外。

执行阶段

启动

在启动实现子 Agent 之前，使用计划中指定的草案所记录的命令，将其提升为正式声明，以获取一个由父会话拥有、覆盖所有清单写入范围并集的声明。仅当提升操作报告 no draft named ... 时，才使用记录的显式启动回退方案。逐一列出确切文件；对于目录范围，使用 --recursive。启动前必须获得 READY。

如果提升或启动操作进入排队或阻塞状态，绝不要结束当前轮次并暂停。在这种情况下，使用 Bash 设置 run_in_background: true 运行 ai-coord wait，以便其返回时唤醒会话。它也会在其他非就绪唤醒事件（消息、覆盖范围未知、工作释放、默认超时 300 秒）发生时返回。每次唤醒时，通过 ai-coord inbox 处理 MESSAGE 事件。每次唤醒时都重新提交记录的提升或启动命令，并诊断过时的阻塞项。

原生子 Agent 会继承父会话身份，因此该声明授权它们执行分配的写入操作。所有协调生命周期命令均由父会话负责；父会话在协调结果、必要的润色和提交期间持有覆盖范围。子 Agent 绝不能运行生命周期命令。委派防护机制无法强制执行此规则。Claude 子 Agent 会继承父会话身份，无法与父会话区分。因此，它运行的生命周期命令会作用于父会话的声明。

每份任务说明都必须禁止运行生命周期命令。子 Agent 绝不能运行这些命令。

通过 Agent 工具启动每个 Agent：设置 subagent_type: "general-purpose"，使用其清单行中指定的模型，并采用类似 A1 — <scope> 的描述。在同一条消息中并行调用工具，启动每一波中的所有并行 Agent。只有在协调好依赖项后，才启动顺序执行的 Agent。Claude Code 会原生显示子 Agent 的进度。不要创建专门的仪表板、轮询循环或状态表。

启动后，发布一行简短消息：🚀 Handoff started — <agent count> agents · <strategy> · <wave count> waves。然后依赖原生进度显示。记录每个已完成实现结果所返回的 Agent ID，以便进行任何获准的后续操作。

子 Agent 不会收到规划对话的内容。为每个 Agent 编写一份自包含、以结果为先的提示，其中包含：

1. 经批准的整体结果，以及该 Agent 的实施简述、依赖项和完成证据。
2. 其确切的写入范围、相关仓库约束、已知的未提交更改边界（其他 Agent／会话可能共用同一工作树），以及任何前置 Agent 的结果。
3. 根据规划阶段的验证负责人规则分配的验证任务：必须运行的范围内检查。对于除验证负责人以外的每个 Agent，都要说明其不得运行由负责人在整个工作波次结束后运行的汇总检查。不得安排已批准计划未要求的验证机制。
4. 与其清单规模以及用户或适配器施加的硬性运行时限相匹配的时间估算。仅有软性估算不构成停止条件。遇到阻碍时，报告部分证据以及具体阻碍或已耗尽的硬性时限。
5. 以下权限边界：检查、在范围内编辑并在本地验证。绝不提交、推送、部署或执行外部写入，也不得扩大范围，即使仓库或主机指令倾向于要求尽快提交也不例外——协调器在完成核对后负责提交。
6. 一条委派上下文声明，须通过标签／会话 ID 前缀指出负责协调的会话：该会话的声明或存在是对所分配范围的授权，而非冲突。兄弟子 Agent 的互不重叠范围也不构成冲突。只有无关会话声称拥有该 Agent 确切分配文件的修改权，才足以报告 blocked。
7. 以下停止规则：严格按已批准计划实施。如果无法实现或需要重新设计，应提供证据并报告受阻，而不是提出替代计划。只有得出最终结果或遇到真正的阻碍时才结束。绝不得以宣布下一步的进度摘要、继续处理的提议、里程碑报告或不会造成阻碍的决策作为结尾。
8. 最终消息必须以且仅以以下字段结尾：status（completed／blocked）、summary、changed files（仅列出实际修改的文件）、verification（列出每条命令及其结果）、residual risks 和 blockers。

在完整表达所需内容的前提下，尽量精简每条提示词。包含共享的结果摘要，以及该 Agent 自身的任务简述、范围和约束。不要在每条 Agent 提示词中重述完整计划。

收集

Agent 返回结果后，阅读必需的结果字段，并将 changed files 视为其执行后范围的权威记录。确认所报告的文件确实存在或已按计划删除。确认这些文件均在范围内。根据规划阶段的验证负责人规则，确认其验证证据符合任务分配要求。每个工作波次结束后，依据清单和工作树核对所有结果，同时排除无关的并发更改。不得仅因某个工作者进度缓慢或没有回复，就增加 Agent、变更模型、范围或验证负责人。

按下文“完成”部分处理发现的后续工作。Claude 担任验证负责人时，在此核对过程中运行一次已分配的汇总检查。将汇总检查失败归因后，再将其视为阻碍。首先排除交接更改、格式化工具、钩子和生成器的影响，包括对其写入范围之外下游文件造成的失败。只有证据能够证明失败无关，且交接自身的检查仍通过时，才可在失败后继续。

意外的范围外编辑、同一并行工作波次中 Agent 之间的范围重叠，或可归因于交接更改的汇总检查失败，均构成阻碍。遇到这些阻碍时，不得启动依赖任务或进行润色。不得擅自接手实施工作。

技能演进审查

将交接过程中对技能的已验证修复与以下可选审查分开处理。当用户或仓库说明已授权修复时，由主 Agent 负责完成。子 Agent 只报告证据，不得扩大自己的写入范围。只需验证一个实例即可；主任务受阻也不妨碍独立修复。完成交接所需工作或确认其阻塞原因后，根据适用的维护政策，在最终报告前完成独立修复。计划模式仍禁止编辑。

仅当所有必需的 Agent 均成功完成任务且任务已验证后，才由 Claude 单独判断该任务是否揭示了一套稳定、可复用且很可能再次出现的工作流。Agent 不得在本审查中建议技能演进变更。对于受阻、失败或未完成的交接，绝不进行本审查。排除一次性任务、罕见的特殊情况、附带清理和推测性价值。工作规模或难度本身不足以证明任务会再次出现。

新增技能时，说明应放在仓库本地还是全局的 ~/projects/agent-skills。修订技能时，列出所有需要变更的确切技能。提案达到此标准时，在现有完成报告中追加最多一条简短建议（≤2 个短句）。对此提案，保持报告格式不变，并将 $task-handoff 作为下一步操作。绝不在本审查中自动调用 $task-handoff，也不创建或修订技能。如果没有符合条件的内容，就保持沉默——不加占位内容，也不写“未发现符合条件的内容”。

完成

• 当 status: blocked，或已完成的工作表明批准的结果需要相关的仓库内修复或证据变更时，应根据 Contract 的授权边界规则，将其视为后续工作，而非重新寻求授权。对此类工作，让已启动的独立 Agent 完成任务，并阻止依赖任务继续执行。将清单扩展至满足需求的最小范围。完成该范围所需的仓库协调，然后启动一个新的或复用现有的 Agent。重复此过程，直至结果完成或达到真实的授权边界。

  保持 ID 稳定、依赖顺序不变、Agent 数量不超过 8 个，并指定唯一的汇总验证负责人。将后续 Agent 计入最终数量和报告。

• 在完成报告前，按此方式修复批准结果涵盖的同类问题位置。绝不可将这些位置列为可选项或范围外事项。

• 只有在继续执行会改变批准的结果、需要重大重新设计或无关工作，或跨越现有确认边界（破坏性操作、购买、部署、外部写入）时，才询问用户。绝不默默接手实施，也不单因切换到其他模型而重新启动任务。将相关的已完成结果传递给依赖任务的 Agent。

• 将 Agent 工具调用错误或缺少必需字段的最终消息视为基础设施故障。这包括工作尚未完成就停止的进度报告。发生此类故障时，使用 git status/git diff 检查 Agent 写入范围内是否存在部分编辑。然后通过 SendMessage，向返回的 Agent ID 发送消息，让同一个 Agent 继续执行一次。发送简短的验证并继续指令，指出已部分编辑的文件，并保留先前上下文。这是重试，不是一个计入 8 个 Agent 限额的新 Agent。

  如果未返回 ID，或继续执行失败，则该 Agent 受阻。除以下停滞例外情形外，绝不重新启动该 Agent。此例外适用于执行框架停滞（例如：Agent stalled: no progress for 600s），且通过 git status/git diff 检查确认其写入范围未受更改。在此情况下，使用相同的任务说明重新启动该 Agent 一次，并将其排除在 8 个 Agent 限额之外。

• 每个必需 Agent 都完成后，对报告的已更改文件取并集并去重，确认汇总的验证证据能够证明已批准的计划。

• 如果任何必需 Agent 失败，或用户明确要求加快进度或收尾，则跳过所有计划中的润色流程并报告跳过情况。否则，仅针对该并集中的适用路径，各执行一次必需的流程：先运行 $code-polish（默认采用先简化后审查模式），再运行 $agents-brain maintain，并提供符合条件的上下文目标。如果只有一个流程适用，则只运行该流程。不得向任一流程提供并集之外的路径，也不得让其超出声明的工作流权限范围。

• 将各润色流程实际更改的范围内文件纳入最终已更改文件列表和验证结果。若必需的流程阻塞、失败或在支持范围之外写入文件，则阻止后续润色和跨仓库提交。

• 如果已批准的工作更改了交接开始时所在仓库之外的其他 Git 仓库，则在每个附加仓库的工作、验证和必需润色完成后，自动从该仓库调用一次 $commit，并限定为该仓库中已更改的文件。这些提交无需另行确认。切勿提交未完成、受阻、意外或超出范围的更改。仅在请求或长期有效的用户指示授权时推送。

• 如果本次交接推送了提交，且仓库定义了 CI 工作流（例如 .github/workflows），则在完成报告前监控推送的提交所触发的运行（gh run list --commit <sha>，然后运行 gh run watch <run-id>；主机支持时在后台执行）。修复归因于本次交接的失败，并报告 CI 结果。当更改后的代码在不同平台上的行为有所差异，而本地检查只覆盖了其中一个平台时，应将未验证的平台列为风险。

• 以 ### 🏁 Claude handoff — <completed or blocked> 结束，并注明策略和 Agent 数量，再附上简洁的逐 Agent 结果表。接着提供 ### 📦 Changed（文件树）、### 🧪 Verification、执行时的 ### 🧹 Polish、存在时的自动跨仓库提交哈希，以及存在时的 ### Issues and caveats。列出每个润色流程及其结果；其他适用但为空的值填 none。必需工作失败时使用 ⛔ blocked。路径、命令、哈希和子 Agent 返回字段必须保持原样，不得添加修饰。

• 将问题和注意事项分为 Resolved（附有证据的已验证修复）和 Open（仍存在的问题、限制或未经验证的假设，并说明影响和下一步）。省略空分组；如果整个部分为空，则省略该部分。每个事项只报告一次。中性背景信息和已达成的决定放在更改或范围说明中。仅将阻止必需工作的问题称为 blocker；将具体的潜在不良后果称为 risk。如果底层问题仍影响结果，即使采用了变通方案，也应将该事项列为未解决。