多数多 Agent 跑出来都会漂移，因为没东西钉住交接：研究 agent 返回三段松散文字，实现 agent 自己造另一套设计，reviewer 跟两边都吵。好的交接 Prompt 就是用契约把这件事钉死——明确上游必须输出什么、下游必须先读什么、什么明确不在范围内。下面 12 个模板都是围绕这个契约设计的，而且和 2026 年 6 月 Claude Code 子代理的真实工作方式一一对应。
一句话总结
- 交接 Prompt 是一份契约：上游的输出格式、下游必读的内容、不在范围内的清单，以及格式不对时的 STOP 路径。
- 在 Claude Code 里，每个子代理跑在独立的 context window 中，所以基于文件的交接（读一个文件、写一个文件）比基于对话的交接更经得起上下文重置。
- 内置子代理（跑在 Haiku 上的 Explore、Plan、general-purpose）已经覆盖大多数链路；只有当你反复派同一种 worker 时，才在
.claude/agents/*.md里自定义。 - 30 分钟内能搞完、或动 3 个以内文件的任务别上多 Agent，交接成本是真实的。
适合哪些人
在配 Claude Code subagent 流水线的工程师、独自把 AI 当整个团队的创业者，以及用 Claude Agent SDK 做跨轮链式调用的开发者。
Claude Code 子代理怎么工作（2026 年 6 月）
这些模板都建立在 Claude Code 当前的子代理模型上，先做个铺垫：
- 独立的 context window。 每个子代理都有自己的上下文、系统提示和工具权限。它在隔离环境里干吵闹的活（搜索、日志、文件 dump），只把摘要返回主对话。这正是交接链能省上下文的根本原因。
- 内置子代理。 Claude Code 自带 Explore（快、只读、跑在 Haiku 上、被禁用 Write/Edit，因此不会误改仓库）、Plan（只读，plan 模式下用）、以及 general-purpose（继承所有工具）。下面很多链路根本不需要自定义 agent。
- 自定义子代理。 用带 YAML frontmatter 的 Markdown 文件定义，放在
.claude/agents/（项目级，提交进 git）或~/.claude/agents/（个人级）。只有name和description是必填；常用的可选字段有tools（白名单）、model（sonnet、opus、haiku、fable、完整 ID 如claude-opus-4-7，或默认的inherit）和effort。运行/agents可交互式创建或编辑。Claude 会拿你的任务去匹配每个 agent 的description来自动挑选，所以这一行要写成触发条件，而不是简介。 - 自动压缩。 会话接近 context window 约 95% 时，Claude Code 会把前面的轮次摘要后继续。链路中途若某次压缩丢了细节，你的交接文件就是安全网。
- Agent teams 和子代理的区别。 子代理在单个会话内工作、结果返回给父级；而 agent teams 是另一项功能，让多个会话彼此通信。这里基于文件的契约两者都适用。
Prompt 结构公式
每个交接 Prompt 都要带这六个要素：
- 角色：agent 扮演谁（SRE / Release Captain / staff 工程师 / QA Lead）。
- 上下文：技术栈 / 分支 / 失败日志 / diff / dashboard URL。
- 目标：一个具体可交付物——根因、checklist、计划、ticket 列表、runbook。
- 限制：agent 不能做什么（别自动修、别瞎造文件路径）。
- 输出格式：编号清单、markdown 表格、JSON、unified diff、可运行代码。
- 示例 / 信号：一两条”好输出”示例，或一个反例。
适合用在哪
- 研究、计划、写代码、审查 流水线
- 需求、测试、实现 TDD 链
- 并行 Agent 收敛到一个产物
- 长任务切给多 Agent 控制上下文
- 提交进仓库的 Agent runbook
12 个可直接复制的 Prompt 模板
1. 交接契约模板
Before agents run, define the handoff: (1) Producer agent: name + one-sentence job, (2) Output schema (markdown / JSON / file path), (3) Out-of-scope items, (4) Consumer agent: name + what it MUST read first, (5) Failure path: if producer output is wrong shape, consumer says STOP. Output as YAML.2. 研究到计划
You are the RESEARCH agent. Output a single markdown doc at `notes/research.md` with: (1) the question, (2) 3 candidate approaches, (3) for each: pros, cons, one risk. Do NOT propose a final plan — that's the plan agent's job. Do NOT write code. Stop after writing the file.提示：在 Claude Code 里这一步可以直接落到内置的 Explore 子代理上——它只读、跑在 Haiku 上，所以先跑一遍很便宜。
3. 计划到实现
You are the PLAN agent. Read `notes/research.md`. Output `notes/plan.md` with: (1) chosen approach + 1-line rationale referencing research, (2) numbered implementation steps (<= 10), (3) files to touch, (4) tests to add, (5) explicit "do not change" list. No code yet.4. 实现到审查
You are the IMPLEMENT agent. Read `notes/plan.md`. Execute exactly the numbered steps. After each step, append a one-line entry to `notes/progress.md`. Do not deviate from the plan; if you find a problem, write it to `notes/blockers.md` and STOP. No autonomous decisions.5. 审查到发布
You are the REVIEW agent. Read `notes/plan.md` + the diff. For each plan item, mark: DONE / PARTIAL / SKIPPED + evidence (file:line). For SKIPPED / PARTIAL: open a follow-up note. Output `notes/review.md`. Do not change code. If anything is unsafe to ship, write `BLOCK` at top.6. 需求到测试到实现
Three-agent chain: (a) SPEC agent: write `spec.md` from `[prd-link]`. (b) TEST agent: write failing tests from spec only, never reading source. (c) IMPL agent: make tests pass without changing tests. Output each agent's instructions separately. No agent does the next agent's job.可替换变量： [prd-link]
7. 并行 Agent 到汇总
Run two agents in parallel on the same task: (a) AGENT-A pursues solution X, (b) AGENT-B pursues solution Y. Both write to `notes/agent-a.md` / `notes/agent-b.md`. A third CONSOLIDATE agent reads both, recommends one with rationale, lists differences. Don't let A or B see each other's output.在 Claude Code 里，用 Task 工具配 run_in_background 同时起 A 和 B 并发跑，等两个文件都生成后再启动 CONSOLIDATE。
8. 上下文收尾交接
用于接近上下文上限的长会话（Claude Code 在约 95% 时自动压缩，但显式收尾更可靠）。
You are the WRAP agent. Read the current session and write `notes/session-summary.md` covering: (1) what was decided, (2) what code was changed (file:line summary), (3) open questions, (4) the exact next prompt to feed a fresh agent. Don't make new decisions.9. Router 派发
You are the ROUTER. Given task: [task], decide which subagent to invoke: RESEARCH (unknowns) / PLAN (knowns, no plan yet) / IMPLEMENT (plan exists) / REVIEW (code exists) / WRAP (long session). Output: agent, reason, prompt-to-pass. Don't do the work — only route.可替换变量： [task]
10. 失败交接
If you (any agent) cannot complete your task, write `notes/blocker.md` with: (1) what you were doing, (2) what stopped you, (3) what info you need, (4) suggested next agent. Do NOT speculate — leave gaps blank. Pass control back to the router.11. CLAUDE.md 里的角色定义
Write a `CLAUDE.md` section that defines our subagent roles: RESEARCH / PLAN / IMPLEMENT / REVIEW / WRAP. For each: (1) responsibility, (2) inputs they read, (3) outputs they write, (4) what they MUST NOT do. <= 200 words per role. Plain text — no marketing prose.更好的做法是把每个角色提升为 .claude/agents/ 里的真实文件：description 写成触发条件、tools 写白名单、model 按需选（只读研究用 haiku、实现用 sonnet、审查用 opus）。
12. 交接调试
A handoff produced wrong output. Diagnose: (1) Was the contract clear (output shape, out-of-scope list)? (2) Did the consumer agent read the producer's output? (3) Did the producer's context include the consumer's requirements? Output one root cause + one prompt change.容易踩的坑
- 没有交接契约——每次跑都漂移得不一样。
- 让一个 Agent 又计划又实现——计划只会为它刚写的代码自圆其说。
- 把所有上下文喂给所有 Agent——每个都被噪音淹。
- 没有”卡住就说”的路径——Agent 在不确定时会硬编。
- 错一步全链路重跑——浪费 token 和时间。
- Agent 互看草稿——把已定的问题再吵一遍。
- 没有 router——链路变成 if-else 噩梦。
- 自定义子代理漏掉
description，或把它写成简介而不是触发条件——这样 Claude 就没法判断何时该委派。
优化技巧
- 交接走文件，不走对话——文件能挺过上下文压缩和会话重启，而子代理的返回摘要挺不过。
- 每个 Agent 读一个文件、写一个文件。面更小、漂移点更少。
- 让写测试的 Agent 和写实现的 Agent 不是同一个——它能抓到实现者看不见的 bug。
- 所有 Agent 都内置”卡住就 STOP”指令——一条 blocker 记录强过一段自信的瞎编。
- 长会话备好 WRAP Agent 当 context 安全网。
- 角色定义提交进
.claude/agents/，让这条链成为全队共享、纳入版本控制的心智模型。 - 记录每次交接（Agent / 文件 / commit SHA），方便精确回放链路在哪一步出错。
- 把廉价的只读活路由给 Explore / Haiku，把 Opus 4.7 留给审查环节——那里推理深度最值。
FAQ
- 为什么不写一个大 prompt？: 一个 prompt 把研究、决策、实现混在一起，漂移不可避免。多 Agent 链强制分离关注点，还让每一步有自己干净的 context window。
- 多 Agent 不更费 token 吗？: 每个子代理确实单独跑，但它在自己的窗口里干活、只返回摘要，所以可能比一个臃肿会话更省；而失败的单体跑会因重试更费。把只读步骤路由给 Haiku 还能再降本。
- 自定义子代理在哪定义？: 带 YAML frontmatter 的 Markdown 文件，放
.claude/agents/（项目）或~/.claude/agents/（个人）。只有name和description必填。运行/agents可交互式创建。 - 能并行跑吗？: 工作独立时能（模板 7）。用 Task 工具配
run_in_background，最后用 CONSOLIDATE agent 收敛；否则串行。 - Reviewer 该读计划吗？: 该读。没有计划，它只能判断代码能不能跑，判断不了它是否做了当初要它做的事。
- 什么时候多 Agent 是过度设计？: 30 分钟内能搞完、或动 3 个以内文件的任务，一条聚焦的 prompt 更快。