A13: Multi-Agent Coordination Patterns

Related chapters: Ch9 Multi-Agent Orchestration, Ch14 Advanced Automation & CI/CD

When a single Claude Code session is not enough, you split the work across multiple agents. But coordination is hard -- agents can conflict, duplicate work, or produce inconsistent results. This appendix is a deep dive into the coordination patterns that make multi-agent systems reliable, along with practical cost models and scaling guidance.

Fundamental Coordination Patterns

Every multi-agent system is built from three primitive patterns. More complex workflows combine these primitives.

Pattern 1: Fan-Out (Parallel Independent Subtasks)

The simplest multi-agent pattern: divide work into independent pieces, run them in parallel, and collect results.

                    ┌─── Agent A ──► Result A ───┐
                    │                            │
Orchestrator ──────┼─── Agent B ──► Result B ───┼──► Merge
                    │                            │
                    └─── Agent C ──► Result C ───┘

When to use: Tasks that decompose into independent units with no shared state.

Implementation with Claude Code:

#!/bin/bash
# Fan-out: review 3 modules in parallel using git worktrees

REPO_DIR=$(pwd)
MODULES=("auth" "payments" "notifications")

for module in "${MODULES[@]}"; do
  # Create isolated worktree for each agent
  git worktree add "/tmp/review-$module" HEAD

  # Launch agent in background
  (
    cd "/tmp/review-$module"
    claude -p "Review the src/$module/ directory for security issues. \
      Output findings as JSON to /tmp/review-$module-results.json" \
      --model claude-sonnet-4-6-20250514
  ) &
done

# Wait for all agents to complete
wait

# Merge results
claude -p "Merge these security review results into a unified report:
  $(cat /tmp/review-*-results.json)" \
  --model claude-opus-4-7-20250219

Key design decisions:

• Each agent gets its own worktree so file reads never conflict
• Results are written to separate output files so there is no write contention
• A merge step at the end combines results (often using a stronger model)

Failure handling: If one agent fails, the others continue. The merge step should handle missing results gracefully:

# Check which agents succeeded
for module in "${MODULES[@]}"; do
  if [ ! -f "/tmp/review-$module-results.json" ]; then
    echo "WARNING: Review of $module failed" >> /tmp/review-failures.txt
  fi
done

Pattern 2: Pipeline (Sequential Specialized Processing)

Each agent performs one stage and passes results to the next. Agents are specialized for their stage.

Input ──► Agent A ──► Agent B ──► Agent C ──► Output
          (Plan)     (Implement)   (Review)

When to use: Tasks with distinct phases where each phase requires different skills or models.

Implementation:

#!/bin/bash
# Pipeline: Plan → Implement → Review

TASK="Add rate limiting to the upload API endpoint"

# Stage 1: Planning (Opus for deep reasoning)
PLAN=$(claude -p "Create a detailed implementation plan for: $TASK
  Include: files to modify, approach, edge cases, test strategy.
  Output as structured markdown." \
  --model claude-opus-4-7-20250219 --output-format text)

# Stage 2: Implementation (Sonnet for efficient coding)
claude -p "Implement this plan:
$PLAN

Follow the plan exactly. Write code and tests." \
  --model claude-sonnet-4-6-20250514

# Stage 3: Review (Opus for quality assurance)
DIFF=$(git diff)
claude -p "Review this implementation for correctness and security:
$DIFF

The original plan was:
$PLAN

Flag any deviations from the plan or issues found." \
  --model claude-opus-4-7-20250219 --output-format text

Model routing in pipelines: Use the right model for each stage. Planning and review benefit from Opus's stronger reasoning. Implementation is well-served by Sonnet's balance of speed and capability.

Pattern 3: Debate (Multiple Agents Critique Each Other)

Two or more agents propose solutions, then critique each other's proposals. A judge selects the best approach or synthesizes a consensus.

              ┌─── Agent A: Proposal A ───┐
              │                           │
Task ─────────┤                           ├──► Judge ──► Final
              │                           │
              └─── Agent B: Proposal B ───┘

When to use: Architectural decisions, design choices, or any task where multiple valid approaches exist and you want the best one.

Implementation:

#!/bin/bash
QUESTION="How should we restructure the authentication module? \
  Currently it's 2000 lines in a single file."

# Two agents propose independently
PROPOSAL_A=$(claude -p "Propose an approach: $QUESTION
  Focus on maintainability and testing." \
  --model claude-sonnet-4-6-20250514 --output-format text)

PROPOSAL_B=$(claude -p "Propose an approach: $QUESTION
  Focus on performance and minimal API surface change." \
  --model claude-sonnet-4-6-20250514 --output-format text)

# Each agent critiques the other's proposal
CRITIQUE_A=$(claude -p "Critique this proposal. Find weaknesses:
$PROPOSAL_B" --model claude-sonnet-4-6-20250514 --output-format text)

CRITIQUE_B=$(claude -p "Critique this proposal. Find weaknesses:
$PROPOSAL_A" --model claude-sonnet-4-6-20250514 --output-format text)

# Judge synthesizes (use Opus for best judgment)
claude -p "Two approaches were proposed for: $QUESTION

Proposal A: $PROPOSAL_A
Critique of A: $CRITIQUE_B

Proposal B: $PROPOSAL_B
Critique of B: $CRITIQUE_A

Synthesize the best approach, incorporating strengths from both proposals
and addressing the critiques." \
  --model claude-opus-4-7-20250219

Why debate works: Individual agents have blind spots. By forcing explicit critique, you surface weaknesses that a single agent would miss. The judge role benefits from seeing all perspectives.

Consensus Algorithms for Agent Disagreements

When multiple agents produce outputs that must agree (e.g., code changes to overlapping files), you need a consensus mechanism.

Majority Vote

The simplest approach: run N agents on the same task and take the majority answer.

# Run 3 agents on the same code review
RESULTS=()
for i in 1 2 3; do
  RESULTS+=("$(claude -p "Is this code safe to deploy? Answer YES or NO with reasoning." \
    --model claude-sonnet-4-6-20250514 --output-format text)")
done

# Count votes
YES_COUNT=$(printf '%s\n' "${RESULTS[@]}" | grep -c "^YES")
if [ "$YES_COUNT" -ge 2 ]; then
  echo "CONSENSUS: Safe to deploy ($YES_COUNT/3 agents agree)"
else
  echo "CONSENSUS: NOT safe to deploy ($YES_COUNT/3 agents agree)"
fi

When to use: Binary decisions (deploy/don't deploy, approve/reject). Less useful for open-ended tasks.

Hierarchical Resolution

A senior agent (Opus) resolves disagreements between junior agents (Sonnet/Haiku):

Agent A (Sonnet): "Refactor using Strategy pattern"
Agent B (Sonnet): "Refactor using simple if/else chain"
      │
      ▼
Resolver (Opus): Reviews both approaches with full context,
                  selects or synthesizes the best option

This mirrors how human teams work: peers propose, a senior decides.

Iterative Convergence

Agents share their outputs and refine until they agree:

Round 1: Agent A proposes X, Agent B proposes Y
Round 2: Agent A sees Y, revises to X', Agent B sees X, revises to Y'
Round 3: X' and Y' are close enough → merge

Warning: This can loop indefinitely if agents oscillate. Set a maximum number of rounds (typically 3) and fall back to hierarchical resolution.

Conflict Resolution for Overlapping Changes

The hardest multi-agent problem: two agents edit the same file.

Prevention: Partition the File Space

The best conflict resolution is conflict prevention. Assign each agent exclusive ownership of specific files or directories:

# Agent A owns src/auth/
# Agent B owns src/payments/
# Neither touches the other's directory
claude -p "Refactor src/auth/. DO NOT modify any files outside src/auth/."

Detection: Git-Based Conflict Check

After parallel agents complete, check for conflicts before merging:

# Each agent works on its own branch
git checkout -b agent-a-changes
# ... Agent A runs ...
git checkout -b agent-b-changes
# ... Agent B runs ...

# Try to merge both into a combined branch
git checkout -b combined
git merge agent-a-changes
if ! git merge agent-b-changes; then
  echo "CONFLICT DETECTED -- invoking resolution agent"
  # Pass conflict markers to a resolution agent
  claude -p "Resolve these git merge conflicts. Prefer the more correct change.
    $(git diff --name-only --diff-filter=U)" \
    --model claude-opus-4-7-20250219
fi

Resolution: Semantic Merge

When conflicts are detected, a resolution agent reads both versions and produces a correct merge:

# Get both versions of conflicted files
for file in $(git diff --name-only --diff-filter=U); do
  git show agent-a-changes:"$file" > "/tmp/version-a-$file"
  git show agent-b-changes:"$file" > "/tmp/version-b-$file"

  claude -p "Two agents modified $file independently.
    Version A (from agent-a): $(cat /tmp/version-a-$file)
    Version B (from agent-b): $(cat /tmp/version-b-$file)
    Original: $(git show main:$file)

    Produce a correct merged version that preserves both agents' changes." \
    --model claude-opus-4-7-20250219
done

Scaling Patterns: How Many Agents?

The Diminishing Returns Curve

Quality / Throughput
       │
  100% │                          ·····················
       │                    ·····
       │               ····
       │          ····
       │      ···
       │   ··
       │  ·
       │ ·
       │·
       └──────────────────────────────────── Agents
        1    2    3    5    8    10   15   20

In practice:

• 1 to 3 agents: Near-linear improvement. Each additional agent adds significant value.
• 3 to 5 agents: Good returns. Coordination overhead is manageable.
• 5 to 10 agents: Diminishing returns. Coordination becomes the bottleneck, not capability.
• 10+ agents: Rarely worth it. The merge/conflict resolution cost dominates.

Recommended Scaling by Task Type

Task	Optimal Agent Count	Rationale
Code review	2-3	Each reviewer catches different issues; more than 3 produces redundant findings
Module refactoring	1 per module	Natural partition boundary; no coordination needed
Test generation	3-5	Tests are independent; easy to merge
Architecture design	2 (debate)	Two perspectives plus a judge; more adds noise
Bug triage	5-10 (Haiku)	High volume, low complexity, easy to parallelize
Security audit	2-3 (Opus)	Different angles of analysis; expensive per agent

Cost Modeling for Multi-Agent Systems

Multi-agent workflows consume more tokens than single-agent workflows. Use this framework to estimate costs before committing to a multi-agent approach.

Cost Formula

Total cost = (N_agents x cost_per_agent) + cost_merge + cost_conflict_resolution

Where:
  cost_per_agent = input_tokens x input_price + output_tokens x output_price
  cost_merge = typically 1 agent-turn with combined context
  cost_conflict_resolution = 0 if no conflicts, else 1-3 agent-turns per conflict

Example Cost Estimate

Task: Review a 50-file PR with 3 parallel Sonnet agents + 1 Opus merge.

Per Sonnet agent:
  Input:  ~30,000 tokens (code + prompt)     = $0.09
  Output: ~5,000 tokens (review findings)    = $0.075
  Subtotal per agent:                         = $0.165

3 Sonnet agents:                              = $0.495

Opus merge:
  Input:  ~20,000 tokens (3 reports + prompt) = $0.30
  Output: ~3,000 tokens (merged report)      = $0.225
  Subtotal:                                   = $0.525

Total:                                         ≈ $1.02

Compare with single Opus agent:

  Input:  ~80,000 tokens (all files + prompt) = $1.20
  Output: ~8,000 tokens (full review)        = $0.60
  Total:                                       ≈ $1.80

The multi-agent approach is cheaper AND faster (parallel execution). This is the sweet spot for multi-agent: parallelizable tasks with independent subtasks.

When Multi-Agent Is NOT Cost-Effective

• Tasks that cannot be partitioned (sequential dependency between all steps)
• Small tasks where coordination overhead exceeds the task itself
• Tasks where context sharing is critical (every agent needs the full picture)

Case Studies

ECC (Ensemble Claude Code)

The ECC pattern runs multiple Claude Code instances against the same task and selects the best result:

Same task ──► Instance 1 ──► Result 1 ──┐
          ──► Instance 2 ──► Result 2 ──┼──► Evaluator ──► Best Result
          ──► Instance 3 ──► Result 3 ──┘

Key insight: Different runs of the same model produce different results due to sampling temperature. Running 3 instances and picking the best is often cheaper than running 1 instance of a stronger model.

Best for: Tasks with clear success criteria (tests pass/fail) where you can automatically evaluate results.

GStack (Git-Stacked Agents)

GStack uses git branches as the coordination mechanism. Each agent works on its own branch:

main ──► branch/agent-1 ──► PR #1 ──┐
     ──► branch/agent-2 ──► PR #2 ──┼──► Sequential merge
     ──► branch/agent-3 ──► PR #3 ──┘

Key insight: Git is already a conflict resolution system. Let agents commit to separate branches and use git merge to detect conflicts. Human reviewers merge PRs in priority order.

Best for: Large refactoring tasks where each agent handles one module or feature area.

GSD (Get Stuff Done)

GSD combines a planning agent with execution agents:

Planning Agent (Opus) ──► Task 1 ──► Worker Agent A (Sonnet)
                      ──► Task 2 ──► Worker Agent B (Sonnet)
                      ──► Task 3 ──► Worker Agent C (Sonnet)
                                          │
                      Review Agent (Opus) ◄┘

Key insight: Separate planning from execution. The planning agent uses a stronger model to decompose the task correctly. Worker agents use a cheaper model to execute the plan. A review agent verifies the results.

Best for: Complex features that require architectural thinking upfront but straightforward implementation.

Practical Implementation Tips

Tip 1: Use Worktrees, Not Branches in the Same Checkout

# GOOD: Each agent gets its own worktree (isolated filesystem)
git worktree add /tmp/agent-1 HEAD
git worktree add /tmp/agent-2 HEAD

# BAD: Agents share the same working directory
# (race conditions on file reads and writes)

Tip 2: Structure Output for Machine Parsing

# GOOD: JSON output that can be merged programmatically
claude -p "Review the code. Output as JSON: {findings: [{file, line, severity, message}]}" \
  --output-format json

# BAD: Free-form text that requires another agent to parse
claude -p "Review the code and tell me what you think"

Tip 3: Set Timeouts per Agent

# Prevent a single slow agent from blocking the entire workflow
timeout 300 claude -p "Review src/auth/" --model claude-sonnet-4-6-20250514
if [ $? -eq 124 ]; then
  echo "Agent timed out -- skipping this module"
fi

Tip 4: Log Everything

# Each agent logs to a separate file for debugging
claude -p "$TASK" --model claude-sonnet-4-6-20250514 \
  2>&1 | tee "/tmp/agent-$MODULE-$(date +%s).log"

Decision Framework: Single Agent vs Multi-Agent

Can the task be done in one session within budget?
  ├── YES ──► Single agent (simpler, cheaper coordination)
  └── NO  ──► Can the task be partitioned into independent subtasks?
                ├── YES ──► Fan-out pattern
                └── NO  ──► Does the task have distinct sequential phases?
                              ├── YES ──► Pipeline pattern
                              └── NO  ──► Is there genuine uncertainty about approach?
                                            ├── YES ──► Debate pattern
                                            └── NO  ──► Single agent with /compact

Most tasks are better served by a single well-prompted agent than by a multi-agent system. Use multi-agent when you have a clear partitioning strategy and the task is large enough to justify the coordination overhead.

Key Takeaways

1. Fan-out, pipeline, and debate are the three primitive patterns. All complex multi-agent workflows combine them.
2. Prevent conflicts by partitioning the file space. Detection and resolution are expensive; prevention is cheap.
3. Diminishing returns set in around 5 agents for most tasks. More agents means more coordination overhead.
4. Cost model before you build. Multi-agent is not always cheaper than a single stronger agent.
5. Use git worktrees for filesystem isolation between parallel agents. Shared working directories cause race conditions.
6. Structure output as JSON for machine-parseable results that can be merged programmatically.

---

See also: A04 Agent Architecture Patterns for the single-agent patterns that underpin multi-agent coordination, and A11 Model Selection Guide for choosing the right model for each agent role.