Orchestration — patterns for multi-Claude systems
When a task is too large for one context window, or needs parallel work, or requires different kinds of thinking in sequence — you need multiple agents. These are the patterns that actually work. Discovered building this project.
Use when: you're starting something new and don't want to build on wrong assumptions. The most common mistake is building before understanding.
Each agent is briefed by the previous. No agent writes code without a plan. No plan exists without research. Sequential but fast — each step is focused.
// Step 1 — Explore (read-only, no edits) Agent({ subagent_type: "Explore", description: "Research codebase", prompt: ` Find all files related to [feature]. How does [system] currently work? What are the edge cases? Do NOT edit anything. ` }) // Step 2 — Plan (uses research output) Agent({ subagent_type: "Plan", description: "Design solution", prompt: ` Context: [paste research findings] Design: [what to build] Constraints: [what not to change] Return: step-by-step implementation plan. ` }) // Step 3 — Build (uses plan, may edit) // Execute plan in main conversation // with full context from steps 1+2
Use when: multiple tasks don't depend on each other. Running them sequentially is waste. Running them together saves 60-80% of wall-clock time.
All agents start simultaneously. Main conversation waits for all to complete, then synthesizes. No agent blocks another.
// Launch all at once — single message, multiple tool calls // These run in PARALLEL (not sequential) Agent({ description: "Search auth patterns", prompt: "Find all authentication-related files...", run_in_background: true }) Agent({ description: "Search API endpoints", prompt: "Find all API route definitions...", run_in_background: true }) Agent({ description: "Search test coverage", prompt: "Find all test files and what they cover...", run_in_background: true }) // You will be notified when each completes // Don't sleep, poll, or check manually
Use when: you want Claude to try something that might break things. Worktree isolation means experiments are completely safe — main branch untouched.
Agent works in its own git branch. If the result is good, you merge. If not, you discard. Zero pollution of your working state.
Agent({ description: "Refactor auth module", isolation: "worktree", // ← isolated branch prompt: ` Context: [what exists] Goal: refactor authentication to use [pattern] Stack: [your stack] Constraints: - Don't change the public API - Keep existing tests passing - Don't add new dependencies ` }) // Returns: worktree path + branch name (if changes made) // Auto-cleanup if no changes // After reviewing: // git merge [branch] ← if good // git branch -D [branch] ← if not
Use when: a task requires genuinely different capabilities — deep research, creative generation, rigorous review. One agent doing all three compromises all three.
Each specialist has a narrow focus. The researcher doesn't write. The writer doesn't review. The reviewer doesn't create. Each is better at its role for not doing the others.
// RESEARCHER — gather, don't create const research = await Agent({ subagent_type: "Explore", prompt: ` Research [topic] thoroughly. Find: existing patterns, edge cases, prior art. Return raw findings — don't synthesize yet. ` }) // WRITER — create from research, don't evaluate const draft = await Agent({ prompt: ` Research findings: [research output] Write [the thing]. Don't second-guess the research. Don't add caveats. Just create. ` }) // REVIEWER — critique, don't create await Agent({ prompt: ` Review this [draft] against [criteria]. Find: what's wrong, what's missing, what's unclear. Don't rewrite. Just diagnose. ` })
Use when: you need output that meets a measurable standard. Loop until the condition is satisfied. Claude stops when it's done, not when it's tired.
The loop runs until tests pass, quality threshold is met, or a max iteration count is reached. Autonomous refinement without human intervention on each cycle.
// In your CLAUDE.md or prompt: ` Work in iterations until all tests pass: 1. Generate / modify [thing] 2. Run: npm test (or your test command) 3. If tests fail: - Read error output carefully - Diagnose root cause before fixing - Fix, then go to step 2 4. If tests pass: done. Max iterations: 5 If still failing at 5: stop and explain why. ` // Claude runs this loop autonomously // You see the result, not the iterations // Only interrupts if genuinely stuck
A subagent has no conversation history. It only knows what you put in its prompt. Treat every agent spawn as briefing a new colleague who just walked in. Include context, constraints, what's already decided.
The best agent prompts have one job. Research or write or review — not all three. When scope is narrow, quality is high. When scope is broad, everything is mediocre.
If two tasks have no dependency between them, run them at the same time. Sequential execution of parallel work is wasted wall-clock time. Check: "does B need A's output?" If no, run together.
Any agent that might make significant changes should run in a worktree. This costs nothing and protects everything. "I'll review before merging" is not isolation — it's optimism.
The orchestrating agent's job is synthesis. It doesn't do the detailed work — specialists do. It reads their outputs, resolves conflicts, and makes decisions. Keep it at the meta level.
Every loop needs a stop condition. "Run until tests pass" plus "max 5 iterations" plus "if stuck, explain why." Without a stop condition, autonomous agents can run indefinitely on unsolvable problems.