Most multi-agent runs drift because nothing pins the handoff: research agent returns 3 paragraphs, implementer agent invents a different design, reviewer agent argues with both. A good handoff prompt specifies what the previous agent must output, what the next agent must read, and what is explicitly out of scope.
Who this is for
Engineers wiring up Claude Code subagent workflows, founders running solo with AI as the team, anyone using the Agent SDK to chain LLM calls beyond a single turn.
When not to use these prompts
Don’t use multi-agent chains for tasks that one focused prompt could do. The handoff cost is real — both in latency and in drift.
Prompt anatomy / structure formula
Every handoff prompt should carry six elements:
- Role: who AI plays (SRE / release captain / staff engineer / QA lead).
- Context: stack / branch / failing logs / diff / dashboard URL.
- Goal: one concrete deliverable — root cause, checklist, plan, ticket list, runbook.
- Constraints: what AI MUST NOT do (don’t auto-fix, don’t hallucinate file paths).
- Output format: numbered findings, markdown table, JSON, unified diff, runnable code.
- Examples / signal: 1-2 “good” output examples, or counter-examples.
Best for
- Research → plan → code → review pipelines
- Spec → tests → implementation TDD chain
- Parallel agents converging on a shared artifact
- Long-running tasks split across agents to control context
- Subagent runbooks committed to a repo
12 copy-ready prompt templates
1. Handoff contract template
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. Research → Plan
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.3. Plan → Implementation
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. Implementation → Review
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. Review → Ship
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. Spec → Tests → Implementation
Three-agent chain: (a) SPEC agent: write `spec.md` from `{prdLink}`. (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.Variables to swap: prdLink
7. Parallel agents → consolidation
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>.md`. A third CONSOLIDATE agent reads both, recommends one with rationale, lists differences. Don't let A or B see each other's output.8. Context shrinkage handoff
For long sessions approaching context limits.
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. Subagent dispatch from a 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.Variables to swap: task
10. Failure handoff
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. Agent role definitions in 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.12. Handoff debugging
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.Common mistakes
- No handoff contract — every run drifts differently.
- Letting one agent both plan and implement — plan rationalises whatever it just coded.
- Sharing all context with every agent — drowns each in noise.
- No “stop and surface” path — agents fabricate when stuck.
- Re-running the whole chain to fix the last step — wastes tokens and time.
- Agents reading each other’s scratchpads — re-litigates decisions.
- No router — chains become a tangle of conditionals.
How to push results further
- Make handoffs file-based, not message-based. Files survive across sessions.
- Each agent reads ONE input file and writes ONE output file.
- Tests written by a different agent than the implementation catches more bugs.
- Always include a “STOP and surface” instruction — better than confabulation.
- Keep the WRAP agent ready for long sessions; it’s your context safety net.
- Commit role definitions to CLAUDE.md so the chain is the team’s shared mental model.
- Log each handoff (agent / file / SHA) for debugging.
Practical depth notes
Use these prompts as starting points, not final answers. For Multi-Agent Handoff Prompts for Claude Code Subagents, the useful extra work is to replace every generic placeholder with a real constraint: audience, channel, length, brand voice, examples to imitate, and examples to avoid. Run at least two versions with different constraints, then compare the outputs side by side instead of accepting the first polished response.
A good result should pass three checks: it is specific enough that another person could reuse it, it avoids vague praise or filler, and it gives you an editable artifact rather than a broad suggestion. If the output feels generic, add one concrete reference, one forbidden pattern, and one measurable success criterion before rerunning the prompt.
FAQ
- Why not one big prompt?: One big prompt mixes research, decision, and execution — drift is inevitable. Multi-agent forces separation of concerns.
- Doesn’t multi-agent cost more tokens?: Yes — but failed monolith runs cost more in retries. Multi-agent fails fast.
- Can I run agents in parallel?: Yes, when their work is independent (template 7). Otherwise serialise.
- Should the reviewer agent see the plan?: Yes — without the plan it can’t evaluate completeness.
- How do I avoid an “agent God object”?: One responsibility per role, ≤ 200 words of instruction each.
- When is multi-agent overkill?: For tasks under 30 min of work or fewer than 3 files touched.