Fan Out

Fan-out

Bounded subagent delegation and evidence-first synthesis for Claude Code. You stay the planner and the single decision-maker; subagents do scoped work and hand back evidence you merge.

When to fan out (and when not to)

Spawn only if at least one is true:

• The user explicitly asked to delegate / parallelize / spawn subagents.
• The task splits into 2-5 genuinely independent subtasks (no shared mutable state).
• Independent work would otherwise pollute the main context (large reads, broad searches).

Otherwise keep it local. Do not rationalize a spawn for work that is sequential, tiny, or shares write surface — coordination overhead and edit collisions cost more than they save.

Mechanism selection

Default to batched Task calls. Reach for Workflow only when stages depend on each other or you need loop/fan-out control flow; reach for background tasks only for true async.

Spawn contract (every subagent prompt)

TASK:    <one concrete outcome>
SCOPE:   <paths / area to look at; what is out of bounds>
MODE:    read-only  |  edit ONLY <named files>
CONTEXT: <self-contained — subagents inherit NO parent transcript>
RETURN:  <exact shape: status, evidence (file:line), commands run, findings + confidence, risks>

Subagents start fresh with no conversation history — never reference "the above" or prior turns.

Roles & model policy

• Pick a custom .claude/agents/<role>.md when one matches; else general-purpose.
• Opus for hard reasoning, review, debugging, planning; inherit (or Sonnet) for read-heavy scans and inventories. Pin model: in the agent file, or omit to inherit the session model.
• Default subagents to read-only (no Edit/Write in their tool scope) unless they own a disjoint, named write surface.

Rendezvous & async discipline

• Synchronous Task batches block until every subagent returns — read all results before the next substantive step; never act on a partial mental model.
• Background tasks: account for every one via TaskGet; TaskStop anything stale or superseded.

Limits & edit safety

• Prefer 2-5 agents; more dilutes synthesis. No nested subagents unless the user asks.
• Parallel edit-workers must own disjoint files. Tell each: "you are not alone in this repo — do not revert or restage another worker's changes." The parent serializes commits.

Escalation

If a subagent underfits, tighten its scope and return contract and re-run only that one on a stronger (Opus) role. Never blanket-escalate the whole batch.

Synthesis & conflict ledger

Merge and dedupe returns; lead with the highest-signal evidence. When subagents disagree, record it and resolve in the parent:

CONFLICT: <claim>
  - agent A: <evidence>
  - agent B: <evidence>
  RESOLUTION: <which wins + why, or the remaining uncertainty>

Verification

Any proposed edit ships with tests/checks actually run, or a concrete command-level verification plan the parent (or a final verify subagent) executes.

Failure modes

See references/agent-templates.md for copyable role stubs and a Workflow skeleton.