Claude Code Parallel Agents: Fan-Out Without Conflict

Why an unmanaged fan-out collides

Claude Code can run several subagents at once. You hand out a set of tasks, each agent works in its own context, and the results come back to be combined. The appeal is speed and breadth. Three research questions answered in the time of one, a codebase explored from five angles simultaneously, a refactor split across independent modules. The risk is that parallelism is only free when the tasks are genuinely independent, and the moment two agents touch the same thing, the fan-out that was supposed to save time produces a mess that costs more to untangle than doing the work in sequence would have.

An unmanaged fan-out collides in predictable ways. Two agents asked to "improve the codebase" both edit the same file, and the second overwrites the first, so one agent's work vanishes. Three agents each add an import to the same module, and the merge is a tangle of conflicting changes. Five research agents return overlapping findings that contradict each other, and the parent has no way to decide which is right. The work happened in parallel, but the results do not compose, because nobody decided in advance how the pieces fit together. Parallelism without coordination is not faster; it is the same work plus a reconciliation problem.

This guide covers the parallel-agent setup that keeps a fan-out coherent: deciding what is actually parallelizable, isolating writes so agents do not clobber each other, structuring results so they merge cleanly, the synthesis step that combines them into one outcome, and the cost math that says when parallelism is worth it. For the single-agent contract each parallel worker still needs, Claude Code subagents covers the agent file anatomy. For the context budget a fan-out spends, Claude Code context window management covers how parallel runs draw down the window.

What is actually parallelizable

The first decision in any fan-out is which tasks can run at once without interfering, and the test is whether they share state. Tasks that only read are almost always parallelizable, because reading the same file from five agents causes no conflict. Tasks that write are parallelizable only if they write to disjoint targets, because two agents writing the same file is a race the merge cannot resolve cleanly.

Read-heavy work is the natural fit. Researching five independent questions, analysing a codebase from several angles, gathering signals from multiple sources, none of these write anything, so they fan out perfectly: each agent reads what it needs, returns its findings, and never touches what another agent is doing. This is where parallelism pays off most reliably, and it is the pattern a research swarm is built on.

Write-heavy work needs partitioning first. A refactor across the codebase parallelizes only if you split it along boundaries that do not overlap, one agent owns src/auth/, another owns src/billing/, and they never reach into each other's territory. If the work cannot be partitioned that cleanly, if every change touches a shared module, then it is not parallelizable and forcing it into a fan-out just creates collisions. The judgement is to parallelize the independent work and sequence the rest, not to parallelize everything because the capability exists. This is the same scoping discipline that Claude Code subagents apply to a single delegation, extended to deciding which delegations can coexist.

Isolating writes so agents do not clobber each other

When parallel agents must write, the rule that prevents collisions is that each agent owns a disjoint set of files and never writes outside it. Ownership is declared up front, in the brief and enforced through tool scope, so an agent physically cannot edit a file another agent owns.

The cleanest pattern is a partition by directory or module. Give each agent a clear territory, state it explicitly in the brief, and the writes never overlap because the territories do not. An agent told "you own src/auth/ and only src/auth/" has an unambiguous boundary, and as long as the partition is genuinely disjoint, the agents run in parallel with zero write conflicts.

# Parallel refactor brief

Agent A: owns src/auth/ ONLY. Migrate it to the new error type.
Agent B: owns src/billing/ ONLY. Migrate it to the new error type.
Agent C: owns src/notifications/ ONLY. Migrate it to the new error type.

Shared files (src/errors/, src/types/): NONE of you edit these. If a shared
change is needed, report it and the parent will make it after the fan-out.

The brief names each agent's territory and, critically, names the shared files nobody touches. The shared-files rule is what prevents the subtle collision where three agents each "helpfully" tweak the common error definition and produce three conflicting versions. By reserving shared changes for the parent to make after the parallel work finishes, the fan-out stays conflict-free and the shared file changes exactly once, by one actor. This is the coordination layer that turns parallel writes from a race into a clean partition, and it pairs with the Claude Code permissions model that can scope each agent's edit access to its own territory.

The parallel-agents CLAUDE.md template

The project CLAUDE.md governs how the main session fans out work: what to parallelize, how to partition writes, and how results come back.

# Parallel agent rules

## What to parallelize
- Read-only tasks (research, analysis) fan out freely
- Write tasks ONLY if they touch disjoint files
- NEVER parallelize work that writes the same file from two agents

## Write isolation (MANDATORY)
- Each parallel agent owns a disjoint set of files, stated in its brief
- Shared files are edited by the PARENT after the fan-out, never by an agent
- An agent that needs a shared change reports it, does not make it

## Result contracts (MANDATORY)
- Every parallel agent returns a result in the SAME defined shape
- Results must be mergeable: structured, comparable, non-overlapping
- The parent synthesises; agents do not coordinate with each other

## Synthesis
- The parent reconciles contradictions between agent results explicitly
- A contradiction is surfaced, not silently resolved by picking one

## Hard rules
- NEVER fan out write tasks without a disjoint file partition
- NEVER let two agents own the same file
- NEVER let a parallel agent edit a shared file
- NEVER merge results that contradict without reconciling them
- ALWAYS give parallel agents the same output shape for clean merging
- ALWAYS reserve shared-file changes for the parent

Three rules carry most of the value.

The write-isolation rule is what makes parallel writes safe. Two agents owning the same file is the core failure of an unmanaged fan-out, and the rule eliminates it by requiring a disjoint partition before any write task fans out. No overlap, no race.

The shared-file rule closes the subtle gap the partition leaves. Even with disjoint territories, agents tend to reach for a common file they all depend on, and three agents editing one shared module is a collision the partition did not cover. The rule reserves shared changes for the parent, so the shared file is touched once by one actor after the parallel work is done.

The result-contract rule makes the merge possible. Parallel results only compose if they arrive in the same shape, so the parent can line them up, compare them, and combine them. Agents returning different shapes force the parent to reconcile formats before it can even reconcile content, which defeats the parallelism. This is the same output-contract discipline that Claude Code subagents require, applied across many agents at once so their results merge cleanly.

Merging results without contradiction

The hardest part of a fan-out is not running the agents; it is combining what they return. When five agents report on the same codebase, their findings overlap, sometimes agree, and sometimes contradict, and the parent has to produce one coherent result from all of them. The synthesis step is where a fan-out either pays off or unravels.

The foundation of a clean merge is that every agent returns the same shape, set by the result contract. When findings arrive as structured items with consistent fields, the parent can deduplicate the overlaps, group the agreements, and isolate the contradictions mechanically. A finding that two agents report identically is one finding, not two. A finding only one agent reports stands on its own. The structure does the first pass of the merge automatically.

The contradictions are what need judgement, and the rule is to surface them, not bury them. When two agents reach opposite conclusions, the wrong move is for the parent to silently pick one and present a confident answer that hides the disagreement. The right move is to name the contradiction, weigh the evidence each agent gave, and either resolve it with a stated reason or flag it as unresolved for a human. A fan-out's value is breadth, and breadth includes disagreement; pretending the agents all agreed throws away the signal that they did not. This is the synthesis discipline a research swarm depends on, and it is why the Claude Code subagents output contract matters so much, since the merge is only as clean as the shapes coming into it.

When parallelism is worth the cost

Parallelism is not free, and the cost is context. Each parallel agent runs in its own window, but the parent that coordinates them pays to brief each one and to read each result back. A fan-out of ten agents means ten briefs out and ten results in, all flowing through the parent's context, which is a real draw on the window the parent has to keep for synthesis.

The trade-off favours parallelism when the tasks are substantial and independent. Five research questions that each take real work are worth fanning out, because the time saved dwarfs the coordination overhead and the results merge cleanly. Ten trivial lookups are not, because the overhead of briefing and merging ten agents exceeds the cost of just doing the lookups inline. The judgement is the same one that governs any concurrency: parallelize when the per-task work is large relative to the coordination cost, and stay sequential when it is not.

The context cost also caps how wide a fan-out should go. A parent coordinating too many agents at once spends so much of its window on briefs and results that it has little left for the synthesis that makes the fan-out worthwhile, and synthesis quality is where the value lives. A moderate fan-out the parent can fully reason over beats a massive one that overwhelms its context. This is the budget side of the same equation Claude Code context window management covers for any heavy operation: the window is finite, and a fan-out spends it fast.

Common Claude Code mistakes with parallel agents

Six patterns Claude or a team gets wrong without CLAUDE.md constraints.

1. Two agents writing the same file

The pattern: a fan-out where agents have overlapping territory and clobber each other.

Correct pattern: a disjoint file partition so each agent owns its files alone.

2. Parallel agents editing a shared module

The pattern: three agents each tweak the common error definition, producing conflicts.

Correct pattern: reserve shared-file changes for the parent after the fan-out finishes.

3. Inconsistent result shapes

The pattern: each agent returns findings in a different format, so the merge cannot line them up.

Correct pattern: one output contract for all agents so results merge mechanically.

4. Contradictions silently resolved

The pattern: the parent picks one of two opposing findings and hides the disagreement.

Correct pattern: surface the contradiction, weigh the evidence, and resolve it explicitly or flag it.

5. Parallelizing dependent work

The pattern: forcing a fan-out on tasks that all touch the same shared state.

Correct pattern: parallelize only the independent work; sequence the rest.

6. Fanning out too wide

The pattern: a fan-out so large the parent's context drowns in briefs and results.

Correct pattern: keep the fan-out moderate enough that the parent can fully synthesise it.

Add each pattern to CLAUDE.md with the corrected form. Combined with the write-isolation discipline above, the result is fan-outs that compose instead of collide.

Sequencing what cannot be parallel

Not all work fits a fan-out, and recognising the sequential parts is as important as parallelizing the independent ones. Work where each step depends on the previous, a migration that must run in order, a refactor where a shared change has to land before the dependent ones, belongs in sequence, because forcing it into parallel produces exactly the collisions the isolation rules are there to prevent.

The common pattern is a hybrid: a sequential spine with parallel branches. The parent makes the shared change first, in sequence, then fans out the independent work that depends on it, then merges. The error-type migration above is exactly this shape, the parent lands the shared error definition, then three agents migrate their disjoint modules in parallel against the now-stable shared type. The sequencing of the shared part is what makes the parallel part safe, and seeing which is which is the core skill. A fan-out is a tool for the independent slice of a workflow, not the whole thing.

Building parallel agents that fan out without conflict

The parallel-agent setup in this guide produces fan-outs where only genuinely independent work runs at once, write tasks operate on disjoint file partitions, shared changes are reserved for the parent, every agent returns the same mergeable shape, and contradictions in the results are surfaced and reconciled rather than hidden. The result is parallelism that delivers its promise, more work in less time, because the pieces were designed to compose instead of colliding.

The principle is the same as any concurrency problem. An unmanaged fan-out is not faster; it is the same work plus a reconciliation mess, because nobody decided how the pieces fit before splitting them apart. The isolation rules and the result contracts are what let the parent run agents in parallel and still get back one coherent outcome.

For the single-agent contract each parallel worker is built on, Claude Code subagents covers the agent file anatomy and output shape. For the context budget a fan-out draws down, Claude Code context window management covers how to spend the window on synthesis rather than coordination. For scoping each agent's edit access to its own territory, Claude Code permissions covers the policy layer.

Get Claudify. Run the work that is independent in parallel and merge it into one clean result.