How to Run a Team of Parallel AI Coding Agents

Running one AI coding agent is a prompting problem. Running five is a management problem — and the skills transfer from managing people better than they transfer from prompting. This is the playbook we've converged on: how to isolate agents so they can't corrupt each other, how to split work so parallelism actually helps, which coordination pattern to use, and the mistakes that cost us the most time.

It's tool-agnostic. The mechanics are the same whether you're driving terminals by hand or using a platform.

Rule zero: parallelism is not the goal

Throughput is. Five agents on work that doesn't decompose is slower than one agent, because you pay decomposition cost, coordination cost, and merge cost for no gain — and you pay five times the tokens.

Before splitting anything, ask whether the task has independent parts with a clear contract between them. If the answer is "sort of," run one agent. This single check saves more time than every optimisation below.

The three isolation layers

Agents corrupt each other at three levels, and each needs its own answer. Skip a layer and you'll spend your afternoon debugging something that isn't a bug.

Layer 3 deserves emphasis. Git will happily merge two agents' work when they touched different lines of the same file, and hand you something that compiles and is wrong. The fix isn't a better merge strategy — it's deciding up front who owns what, and saying so in each agent's brief. Ours reads roughly: you own these files; these other files belong to concurrent tasks; if you need something outside your set, request it rather than editing it.

The escape hatch matters as much as the fence. An agent that discovers it genuinely needs a neighbouring file must have somewhere to go — a request that a coordinator can grant once the owner is finished. Without that, agents either stall or defect and edit it anyway.

Coordination patterns

Three shapes, in increasing order of how much they can go wrong.

Fan-out. One planner splits the work, agents run independently, nobody talks. Every task must be fully specified up front. This is the default and it should stay the default — it's the only pattern where an agent failing doesn't corrupt the others.

Hub-and-spoke. A coordinator holds shared state and mediates: it grants file ownership, injects "here's what already landed" context into tasks that start later, and arbitrates conflicts. Agents still don't talk to each other — everything goes through the hub. This is what you graduate to when tasks have real dependencies, and it's where we live.

Shared memory. Every agent reads and writes a common store, so a later agent sees an earlier one's reasoning. Powerful and genuinely risky: one agent's wrong conclusion becomes every subsequent agent's premise. If you use it, keep it to facts (what changed, what passed) rather than opinions.

The failure mode nobody warns you about is the middle one done badly: a coordinator that injects too much context. Handing every agent the full history of the run buries its actual task in noise and costs you a fortune in tokens. Inject what changed, not everything that happened.

What parallelises, and what doesn't

Sorted by how well it works in practice.

Works well

• Layered features. Endpoint, UI, tests — three lanes with a contract between them. The canonical win.
• Mechanical migrations. A rename across 40 call sites, a library swap, a config pattern. One agent per directory.
• Independent backlog items. A dozen small specified issues. Many little problems, which is exactly what one sequential agent is worst at.
• Test coverage. Test files are naturally isolated and pass/fail is unambiguous. This parallelises almost perfectly.

Works badly

• Debugging. Inherently single-threaded — you're following one causal chain. Five agents produce five theories and no fix.
• Exploratory work. If requirements change as you learn, decomposition is a guess that goes stale immediately.
• Anything downstream of one big decision. Make the decision first — with one agent, or yourself — then fan out. Five agents each inventing their own data model is five rewrites.
• Tightly coupled code. If everything imports everything, there are no lanes to assign. Fix the coupling first; it's the real problem.

The five mistakes that cost us most

1. Splitting by "size" instead of by boundary. Five equal-looking chunks that all touch the auth module is not parallel work. Split along interfaces, even when the pieces are lopsided.
2. No verification gate. If "done" means the agent said done, parallelism multiplies your defects by N. You need something independent — tests, review, ideally both — between an agent finishing and its work counting.
3. Merging straight to main. Accumulate agent work on an integration branch and open one pull request you actually read. Five auto-merged PRs a human skimmed is not review.
4. Forgetting the combination. Each task can be individually correct and the merged result still broken, because one task's behaviour change breaks another's test. Something has to run the full suite on the combined branch — that step catches a class of bug nothing else does.
5. Retrying the same wall. An agent that fails review three times for the same reason will fail a fourth. Detect repeated identical rejections and stop, rather than burning the retry budget. And when you re-review a revision, re-run only the checks that failed — a reviewer that already approved shouldn't get another chance to invent objections. That one change alone ended most of our runaway retry loops.

A concrete loop

What a good run looks like, start to finish:

1. Scope it. One feature, described at the altitude you'd give a senior engineer. Not an epic.
2. Decompose and assign lanes. Three to five tasks, each with declared file ownership and explicit dependency order.
3. Isolate. Worktree, port, database, cache namespace per agent.
4. Run, capped. Start the independent tasks; queue the dependent ones behind what they need. Resist raising the cap — decomposition is nearly always the better lever.
5. Gate every task. Tests and review before anything merges. Rejections go back with the findings attached, in the same workspace, so the agent builds on its work instead of restarting.
6. Integrate and verify. Merge to an integration branch, then run the full suite on the combination.
7. Read the diff. One PR, one human. This step is not optional and it's not a formality.

Frequently asked questions

How many agents should I actually run? Three to five for a feature. Below three the coordination overhead isn't repaid; above five, wall-clock gains flatten while token cost and merge pain keep climbing. If you want more parallelism, split into two sequential rounds instead.

Do the agents need to talk to each other? No, and it's usually better if they don't. Route everything through a coordinator. Direct agent-to-agent chat multiplies the ways a wrong conclusion propagates, and it's far harder to debug after the fact.

How do I stop two agents rewriting the same file? Declare ownership before they start and put it in each brief. Branch isolation alone won't save you — git merges non-overlapping edits happily, including two incompatible ones.

What if an agent needs a file it doesn't own? Give it a request channel and have a coordinator grant the file once the current owner is finished. The alternative is an agent that stalls, or one that edits it anyway.

How much context should each agent get? Its task, its file lane, the project conventions, and a short summary of what already landed. Not the full run history — that buries the task and costs a fortune in tokens.

When is this just not worth it? Small changes, unclear requirements, debugging, and repos with no test signal. In all four, one agent is faster.

Key takeaways

• Parallelism is a means to throughput, not a goal. Check the work decomposes before you split it.
• Isolate at all three layers: filesystem, runtime, and semantic ownership. The third is the one people skip.
• Fan-out by default; hub-and-spoke when there are dependencies; shared memory only for facts.
• Split along interfaces, never by size.
• A verification gate is what makes parallelism safe. Without one you're just generating defects faster.
• Verify the combination, not only the parts.
• Three to five agents. Better decomposition beats more agents, every time.

The mechanics of layer 1 are in Git Worktrees for Parallel AI Coding Agents; the architecture this playbook assumes is in What Is AI Agent Swarm Coding?.