AI Guides › Playbooks
By Nigel Guy · 8 min read
Most people who "use multiple agents" are really asking one agent the same question three times and calling the agreement a result. Or they open five sessions, paste one prompt into each, and then read five long answers with no rule for which one wins. It feels thorough while it fails you: the agents share your framing, your blind spot and your wording, so they tend to share the mistake.
The rule: pick the formation by the shape of the question, give every agent a different job, and write the tie-break rule before anyone starts.
Three formations cover almost everything. Fill in the card before you spawn anything.
| Fan-out, fan-in | Debate | Council | |
|---|---|---|---|
| Question shape | Big and divisible: many files, sources or options to cover | One contested claim with a right answer (root cause, "is this safe?") | A decision with trade-offs, no single right answer |
| Agents do | Each takes a separate slice, reports back | Each defends a rival theory and attacks the others | Each argues from a fixed seat (cost, risk, user, and so on) |
| Merge by | The lead combines slices | Whichever theory survives the attacks | A written verdict with the dissent recorded |
| Main risk | Slices overlap or leave gaps | Agents agree too early | Seats become theatre: eight voices, no decision |
If you can't say which column your question sits in, you don't yet have a question for several agents. One agent will do.
You split a job into independent slices, send one agent at each, then merge. Use it for coverage: reviewing a large codebase module by module, summarising a stack of documents, checking several vendors against the same list.
The mechanism is the slice contract. Each agent gets a unique slice, the same output template, and a rule about what to leave out. The merge step is separate and happens after: the lead (you, or the main Claude session) reads the reports, lists conflicts, and resolves them.
In Claude Code, this is what subagents are for. Claude Code's documentation says subagents run in their own context window with their own system prompt and tool access, and that you can ask for several to run in parallel, for example researching the authentication, database and API modules at once. They return a result to the caller rather than talking to each other, which suits fan-out. Define a reusable one as a Markdown file with name and description frontmatter (the two required fields) in .claude/agents/ for a project or ~/.claude/agents/ for all your projects, and restrict it with a tools list if it should be read-only. At time of writing, the default cap is 20 concurrent subagents; check the current docs before relying on that number.
Fan-out prompt
You are the lead on [PROJECT_OR_QUESTION]. Goal: [WHAT_A_GOOD_RESULT_LOOKS_LIKE].
Step 1. Split the work into [NUMBER_OF_SLICES] independent slices that do not overlap: [SLICE_BOUNDARIES_OR_ASK_ME]. List them and wait for my OK.
Step 2. After my OK, run one subagent per slice in parallel. Each subagent gets only its slice, read-only access, and this output template: findings, evidence (file or source and location), confidence (high/medium/low), and what it could not check.
Step 3. Merge. Produce a single table, deduplicate, and list every place two reports disagree.
Constraints: no subagent edits anything. Do not invent evidence; if a slice is unclear, say so instead of guessing. If any bracketed input above is missing, ask me before starting.
Before you answer, check that every slice is covered once and that every claim in the merge points to a report.
Fill in: the project, the definition of a good result, the number of slices and where the boundaries fall.
You use the debate when one explanation is hiding behind several. A single agent tends to find one plausible cause and stop. Claude Code's agent-teams documentation describes exactly this: sequential investigation anchors on the first theory, so you start several agents on different hypotheses and tell them to try to disprove each other, and the theory that survives is more likely to be the real one.
Agent teams are different from subagents: teammates have their own context windows and message each other directly, with a shared task list. They are experimental and off by default. You turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in settings.json under env. Your terminal's agent panel lists teammates; you can select one and press Enter to message it directly. They need an interactive session, so -p non-interactive mode will not spawn them.
Debate prompt
Problem: [OBSERVED_SYMPTOM, with what I have already tried: ALREADY_TRIED].
Spawn [3_TO_5] teammates. Name them hypothesis-1 to hypothesis-N. Each owns one rival explanation: [LIST_HYPOTHESES_OR_ASK_ME_TO_APPROVE_YOURS].
Rules for every teammate:
1. Gather evidence for your own hypothesis first, citing file and line or log text.
2. Then try hard to disprove each other teammate's hypothesis, and answer attacks on yours.
3. Concede openly when evidence beats you.
Lead: do not edit anything. When the debate settles, write a verdict: surviving hypothesis, the evidence that killed the others, anything still unproven, and the cheapest test that would confirm it.
Before you answer, check that no hypothesis was dropped without a stated reason. If a bracketed input is missing, ask.
Fill in: the symptom, what you tried, and the number of teammates (three is plenty to start).
A council is for decisions, not facts. Each agent holds one fixed seat with a different incentive: the person paying, the person maintaining it, the person who must trust it, the sceptic. You are not asking for a vote. You are asking each seat to name what it would refuse to accept.
The council works in a plain chat too: run each seat in a separate chat, or one after another in one chat with "forget the previous seat" as an instruction you do not fully control, so separate chats are cleaner.
Council prompt
You are the [SEAT_NAME] on a decision panel. Your single interest: [WHAT_THIS_SEAT_PROTECTS].
Decision: [THE_DECISION_AND_THE_OPTIONS]. Context: [CONSTRAINTS, BUDGET, DEADLINE].
Output: (1) your preferred option and why, in under 120 words; (2) the one condition under which you would block the decision; (3) the evidence you would want before agreeing, and what you assumed because it was missing.
Do not soften your position to be agreeable. Do not invent figures; mark assumptions as assumptions. If the decision or options are unclear, ask me first.
Run it once per seat, then merge with this second prompt.
Below are the positions of [NUMBER_OF_SEATS] seats on [THE_DECISION]. [PASTE_SEAT_OUTPUTS]
Write a verdict: the recommended option; the seat that lost and what it would need to be satisfied; every blocking condition and whether it is met; and what we must verify before acting. Do not average the views. If two seats rest on the same unverified assumption, point it out. Check that the verdict names a dissent before you answer.
Agreement is not evidence. If every agent got the same context, the same wording and the same model, a unanimous answer may only mean they share one blind spot. Make the agents different by role, by slice or by hypothesis, and give them different evidence where you can.
Three more traps, in practice:
0 turns that off.Say you run a small online shop and customers report that checkout emails arrive late, sometimes by hours. You don't know why. That is a debate, not a fan-out: one fact, several candidate causes.
You name three hypotheses: the email provider queues messages, your code sends them from a slow background job, and spam filtering delays them. Each teammate gets read-only access to the logs and the code, and the tie-break rule: a hypothesis survives only if it explains the late emails but not the on-time ones. After the debate, you get a verdict and a cheap test. If instead you wanted to compare six email providers, that is a fan-out, one provider per agent, same template.
It will not make a wrong premise right. If your question is badly framed, three agents will answer it badly in parallel.