Claude Code Multi-Agent Orchestration

Why multi-agent?

A single Claude Code agent can do a lot. But as your workflow grows, you hit limits: one agent trying to plan, implement, review, and test produces mediocre results at each step. Multi-agent orchestration splits these roles so each agent focuses on what it does best.

Single agent:
  You -> Claude (does everything, context gets noisy)

Multi-agent:
  You -> /plan-feature
    -> Main session delegates to PM (opus) for planning
    -> Main session delegates to Developer (sonnet) for implementation
    -> Main session delegates to Tester (sonnet) for verification
    -> Result back to you

Key detail: Subagents cannot spawn other subagents. The main Claude Code session always coordinates — it delegates to one agent at a time, reads the result, and decides which agent to call next.

How agents delegate: the Task tool

The main Claude Code session uses the Task tool to delegate work to specialist agents. It reads each agent's description and routes matching tasks to the right specialist:

# In the PM agent's instructions:

## Team
| Agent | When to delegate |
|-------|-----------------|
| developer | New features, bug fixes, implementation |
| tester | After implementation — build, lint, tests |
| ux-designer | UX evaluation, accessibility checks |

## Rules
- Never implement code yourself — delegate to developer
- Always verify outputs via tester before completing

When the main session uses the PM agent, it follows these instructions to plan the work. The main session then delegates implementation to the developer agent, and verification to the tester agent. Each agent runs with its own model, tools, and permissions.

Designing delegation chains

The key design decision is: who delegates to whom? A well-designed chain follows a clear hierarchy:

Principles: orchestrators use opus (complex reasoning), implementers use sonnet (fast code generation), researchers use haiku (quick lookups). Advisory agents don't need Edit or Write tools.

Example: 4-agent team

Here's how a PM, developer, tester, and UX designer work together on a feature request:

You: /plan-feature Add user profile page with avatar upload

Step 1: PM (opus) plans the work
  - Reads CLAUDE.md for project conventions
  - Breaks feature into 3 tasks with RICE scores
  - Task 1: Build profile page (developer, P0)
  - Task 2: Review UX (ux-designer, P1, blocked by 1)
  - Task 3: Run tests (tester, P1, blocked by 1)
  - Returns plan to main session

Step 2: Main session delegates Task 1 to Developer (sonnet)
  - Developer reads existing page patterns
  - Implements profile page with avatar upload
  - Runs build check -> passes
  - Returns result

Step 3: Main session delegates Task 2 to UX Designer (sonnet)
  - Reviews against Nielsen's 10 heuristics
  - Checks WCAG 2.1 AA accessibility
  - Reports: 2 warnings (contrast ratio, touch target)

Step 4: Main session delegates fix to Developer
  - Developer fixes UX issues

Step 5: Main session delegates Task 3 to Tester (sonnet)
  - Runs build, lint, type checks
  - All pass

Step 6: Main session returns final summary to you

File structure for a multi-agent setup

your-project/
  .claude/
    agents/
      product-manager.md      # Orchestrator (opus, plan)
      developer.md             # Implementer (sonnet, acceptEdits)
      tester.md                # Verifier (sonnet, plan)
      ux-designer.md           # Reviewer (sonnet, plan)
    skills/
      plan-feature/SKILL.md    # -> product-manager
      implement/SKILL.md       # -> developer
      code-review/SKILL.md     # -> tester
      test/SKILL.md            # -> tester
      ux-check/SKILL.md        # -> ux-designer
  CLAUDE.md                     # Project conventions

Common patterns

Auto-fix loop

When a build or lint check fails, the main session delegates a fix to the developer, then re-runs the check via the tester. Cap at 2 rounds to prevent infinite loops.

Tester: npm run build -> FAIL (reports to main session)
Main session -> Developer: fix the build error
  -> Developer fixes -> returns
Main session -> Tester: re-run checks
Tester: npm run build -> PASS (round 1)

If still failing after 2 rounds -> escalate to user

Specialist delegation

A pipeline skill routes specific stages to specialist agents:

/ship pipeline (coordinated by main session):
  Stage 1-3: Tester runs build/types/lint
  Stage 4: Main session delegates to ux-designer
  Stage 5: Main session delegates to security-reviewer
  Stage 6: Main session delegates to performance-reviewer
  Stage 7: Main session compiles final report

Advisory agents

Some agents never get called directly by the user. They only activate when another agent delegates to them. These agents don't need skills — they exist as agent files only, and the orchestrator's instructions specify when to call them.

Pitfalls to avoid

• Every agent uses opus — Expensive and slow. Only orchestrators need opus. Implementers work better on sonnet.
• Unclear delegation flow — If the main session can't tell which agent handles which task, it stalls or picks the wrong one. Write clear agent descriptions with specific triggers.
• Restrictive orchestrator tools — If the PM agent only has read-only tools, the main session may not delegate effectively. Give orchestrators enough tools to analyze and plan.
• Too many agents — Start with 2-4 agents. Add specialists only when you have a specific workflow that needs them.
• Vague delegation rules — "Delegate when appropriate" is too vague. Specify exact triggers: "Delegate to tester after every implementation task."