Multi-Agent Coordination — When Subagents Step on Each Other

Ten Agents, One Repo

Spawning multiple agents in parallel is the killer feature of 2026 coding tools. Claude Code can run up to 10 subagents at once. Cursor's cloud agents run in parallel branches. Codex CLI has `codex cloud` for background work. Done well, this collapses a day of work into an hour. Done badly, it's ten agents fighting for the same files.

When parallelism is a clear win

When parallelism breaks

• Two agents editing the same file — last writer wins, lost work
• Refactors that touch shared abstractions — types drift across agents
• Tasks with sequential dependencies — agent B can't start until A finishes
• Anything where global consistency matters more than local progress

The coordination patterns that work

A real Claude Code subagent setup

# .claude/agents/scout.md --- name: scout description: Read-only codebase exploration tools: [Read, Grep, Glob] # NO write/edit tools --- Your job is to explore and summarize. Never edit files. Return a Markdown report with file:line references. # .claude/agents/builder.md --- name: builder description: Implementation tools: [Read, Edit, Write, Bash] --- Implement based on the plan provided. Run tests after each edit. Never edit files in test/ or migrations/. # .claude/agents/reviewer.md --- name: reviewer description: Read-only PR review tools: [Read, Bash] --- Review the diff. List bugs and risks. Never edit.Three subagents with different tool grants. Scout finds, builder builds, reviewer audits. Roles by permission, not by polite request.

Spawning them right

# In Claude Code main session: "Spawn a scout subagent. Have it explore src/auth/ and write a Markdown plan for the refactor we discussed. Wait for its report." # Once the plan exists: "Spawn a builder subagent for each of the 4 plan steps in parallel, with each one on its own branch named refactor/auth-step-1 through 4. Do not start step 2-4 until step 1's branch passes CI." # Then: "Spawn a reviewer subagent for each PR. Aggregate the findings into one report."Sequenced parallelism. Some steps fan out, some serialize. The orchestrator (you, or the main session) decides.

Merge conflict survival

1. Branch-per-agent is the only safe pattern when changes touch shared code
2. After all agents finish, merge serially — pick the most surgical first, rebase the rest on top
3. When two agents propose conflicting changes, do not let a third agent resolve it; you do
4. Use `git rerere` to remember conflict resolutions across rebases
5. Run the full test suite after each merge, not just at the end

Communication between agents

Subagents in Claude Code don't share memory. They communicate via the orchestrator (the main session) or via files written to disk. A common pattern: each subagent writes a `.claude/scratch/<agent-name>.md` report; the orchestrator reads all of them and synthesizes. Files are the message bus.

When to NOT use multiple agents

• Tasks under 30 minutes — coordination overhead exceeds parallelism win
• Refactors touching shared types or core abstractions
• Anything you wouldn't comfortably hand to multiple junior engineers without coordination
• When you don't have CI green on the base branch — agents can't tell what their changes broke

Ten agents in parallel is ten interns who never sleep. Ship the standards, not the code.

— A staff engineer adopting subagents

The big idea: parallel agents are an organizational skill more than a technical one. Pick the coordination pattern that matches the work, scope each agent's tools and paths, branch aggressively, and serialize merges. Done well, you outpace the team. Done poorly, you create the kind of mess one engineer would never make alone.