Coordination Without Chaos

Multi-agent failure is usually not "the models disagreed." It is two sessions editing the same files, or five sessions inventing five sources of truth in chat. Coordination is an engineering problem: the repository is the bus; context windows are not. Roles define what each agent may do (Agent Roles); this page defines how they share state without contaminating each other's judgment.

The only shared channels

Channel	Shared?	Why
Git branches / PRs / commits	Yes	Durable, reviewable, mergeable
Repo docs (CLAUDE.md, specs, ADRs)	Yes	Persistent memory across sessions
Issue / PR description	Yes	Human-visible contract for the task
Builder chat transcript	No	Poisons reviewers; not a handoff format
"The agent said it handled X"	No	Unverified claim; demand the diff

If a fact matters to another agent, it belongs in a file or a PR — not in a conversation you plan to paste later.

Avoiding conflicting edits

Agents do not negotiate file locks. You do, by partitioning work before they start.

Strategy	When	Rule
File ownership	Parallel builders	Spec lists which paths each agent may touch; others are read-only
Interface-first	Cross-cutting feature	Land types/contracts in a thin PR; builders implement against the merge
Sequential slices	High coupling	Merge A before starting B; no parallel on the same module
Worktrees	Concurrent Claude Code sessions	One worktree per agent; never two processes on one dirty tree

Weak split: "Agent A does backend, Agent B does frontend" with a shared types.ts both will rewrite.

Strong split: "Agent A owns packages/api/src/invoices/** and may not edit packages/web/**. Agent B owns packages/web/src/invoices/** and consumes InvoiceDTO from packages/api as already merged on main. Shared DTO changes go through a third, human-approved PR first."

Git worktrees and Claude Code

Claude Code subagents share the parent's working directory. That is fine for read-only review. It is a footgun for two builders: they will overwrite each other's uncommitted files and neither will notice until merge hell.

For concurrent builders:

git worktree add ../proj-billing -b feat/billing-api main
git worktree add ../proj-billing-ui -b feat/billing-ui main

Run one Claude Code process per worktree. Each opens a PR against main. Reconcile via review, not via shared chat. Subagents stay useful inside one worktree for review/research with separate context windows — see Agent Roles.

Shared context via the repo

Handoff note that works:

## Handoff: feat/billing-api → reviewer

- Spec: docs/specs/billing-invoices.md (commit abc123)
- Branch: feat/billing-api
- Assumptions accepted by human: (1) idempotency via invoice_id unique
  constraint (2) no partial refunds in v1
- Out of scope still out of scope: dunning, tax
- Tests: npm test -- invoices (paste summary)
- Open questions: none — or list them

Handoff that fails: pasting the builder's chain-of-thought into the reviewer session. The reviewer will agree with the rationalizations. Independence requires information hygiene, not politeness.

Update durable docs when a decision survives the task: invariants → CLAUDE.md / architecture docs; product rules → the spec. That is docs as memory. Chat is ephemeral on purpose.

Branches and PRs as the control plane

Rules that prevent chaos:

1. One mandate per PR. Builder PRs do not include drive-by refactors.
2. Reviewer never pushes fixes to the builder branch unless the human explicitly switches roles — otherwise nobody reviewed the fix.
3. Rebase/merge from main often so parallel agents do not diverge for days.
4. Human merges. Agents may prepare; merge authority stays human (responsibility split).

Reconciling conflicting outputs

When two agents produce incompatible solutions (different error types, different table shapes, both "complete"):

1. Do not average them in chat. Pick a source of truth (usually the spec or an ADR).
2. Write the decision down in the spec or a short ADR.
3. Designate one builder to align the other branch — or discard the losing branch.
4. Fresh reviewer against the decision doc, not against either builder's defense.

If the conflict reveals an underspecified requirement, that is a win: fix the spec, then rebuild. Thrashing between two implementations without updating the spec is stuck loops.

Claude Code subagent coordination

Pattern	Parent does	Subagent does	Shared state
Review after build	Holds the branch	Read-only review of diff vs spec	Git + spec files only
Research then build	Approves findings	Codebase/web research report	Findings written to docs/ or PR body
Parallel explore	Synthesizes	Two research subagents, different questions	Parent merges reports; no file edits

Keep the task prompt to the subagent thin: paths, spec link, mandate. Do not include "I implemented it by doing X because Y." That sentence destroys the independence property.

Custom agents in .claude/agents/*.md version the mandates so every session gets the same boundaries. Tool allowlists enforce "reviewer cannot edit."

Failure table

Symptom	Cause	Fix
Merge conflicts across agent PRs	Overlapping file ownership	Repartition; interface-first PR
Reviewer finds nothing; bugs ship	Shared builder context	Fresh session; diff + spec only
Two sources of truth in chat	Decisions never landed in repo	ADR/spec update before next agent
Subagent "fixes" while reviewing	Edit tools enabled	Read-only agent definition
Silent overwrite of work	Two processes, one working tree	Worktrees or strict serial

Related

• Agent Roles — mandates and the independence rule this page operationalizes.
• Patterns — builder+reviewer and other compositions that use this coordination model.
• Docs as Memory — why the repo is the bus.
• CLAUDE.md and AGENTS.md — shared ground truth every agent reads.
• Case Study: Multi-Agent Feature — end-to-end example.
• Large Tasks — decomposition that makes coordination possible.