Orchestrator + worker patterns for tasks that exceed a single context window.
Multi-agent orchestration is for tasks that exceed what a single Claude session can reliably complete: tasks with too many files, too many sequential steps, or genuinely independent work streams that can run in parallel. This lesson covers when to use it, how to design the orchestrator/worker split, and how to manage outputs without creating new complexity.
⬡ What you'll build
Multi-agent is not the default. It adds coordination overhead. Use it when:
Condition 1: The task would fill or approach the context window.
200k tokens sounds large. A single agent reading 50 files (many at 100–300 lines each), generating 20 modified files, and tracking the whole transformation will approach limits. Signs: Claude starts making mistakes it wouldn't have made earlier, or responses become less specific.
Condition 2: Genuinely independent work streams exist.
Two features that touch completely different files can run in parallel. One agent builds the email notification system while another builds the CSV export — they don't share files, so they can't conflict.
Condition 3: The task has a natural stage boundary.
Stage 1: Audit all 200 posts for missing alt text (read-only, fast). Stage 2: Generate alt text for the flagged posts (write-heavy, slow). These are naturally separate — audit first, then a separate agent does the writes based on the audit results.
Condition 4: Error in one stream should not block the other.
If the auth refactor fails, the dashboard feature should still be completable. Independent agents fail independently.
Orchestrator: Knows the full task. Breaks it into atomic pieces. Delegates to workers. Collects and verifies outputs. Integrates the results.
Workers: Each gets one atomic task. Full context for that task only. Produce a structured, verifiable output. Do not know about other workers or the full goal.
The orchestrator never does implementation work directly — it delegates, verifies, and integrates.
The orchestrator prompt is a coordination document, not a task prompt:
You are coordinating a multi-step codebase transformation.
Full goal:
Migrate all API routes from the legacy response format { success: bool, data: any }
to the new format { status: 'ok' | 'error', payload: unknown, error?: string }
Your coordination tasks:
1. Audit: Find every API route in app/api/ that uses the legacy format
Output: a list of files with the specific lines to change
2. Delegate transformation: For each file identified in the audit,
the transformation is: update the response object shape and update
the TypeScript return type annotation
3. Collect results: Verify each transformation passed TypeScript checks
4. Integration check: After all transformations, run tsc --noEmit and report
Do the audit first. Show me the complete list of files to change
before any transformation begins.The orchestrator's first output is always the audit or plan — before any worker starts.
Each worker gets a complete, self-contained task:
You are working on a single file transformation as part of a larger migration.
Project context:
- Next.js 15 App Router, TypeScript 5.4
- We're migrating API response format from { success, data } to { status, payload, error }
Your single task:
Transform the API route at app/api/user/profile/route.ts
Specific changes:
1. Line 34: change { success: true, data: user } to { status: 'ok', payload: user }
2. Line 52: change { success: false, data: null } to { status: 'error', payload: null, error: 'User not found' }
3. Update the return type annotation from Response<LegacyFormat> to Response<ApiResponse>
where ApiResponse is imported from lib/types.ts (already exists there)
Constraints:
- Only modify app/api/user/profile/route.ts
- Do not change the business logic, only the response format
- Do not modify any imported types
Verification:
After making changes, run: tsc --noEmit
Report: ✓ TypeScript passed OR ✗ Error: [paste the error]Notice the worker prompt has:
In Claude Code, you can run multiple sessions simultaneously using separate terminal windows. Each runs independently.
Parallelism safety rules:
Practical parallel session setup:
Terminal 1 (Orchestrator):
> Run the audit. List all files that need the format change.
[Produces list of 8 files]
Terminal 2 (Worker A — files 1-4):
> [Worker prompt with files 1-4]
Terminal 3 (Worker B — files 5-8):
> [Worker prompt with files 5-8]
[Both complete — report back to Terminal 1]
Terminal 1 (Orchestrator):
> Worker A reported: 4 files transformed, TypeScript passed
> Worker B reported: 3 files transformed, 1 TypeScript error in route.ts:67
> Handle the error in route.ts:67, then run full tsc --noEmitAfter workers complete, the orchestrator runs integration:
All workers have completed their transformations. Integration phase:
1. Run the full TypeScript check: tsc --noEmit
Report all errors if any.
2. If TypeScript passes: run the build: node node_modules/next/dist/bin/next build
Report whether the build succeeds.
3. Do a quick sanity check: grep -r "success: true" app/api/ to confirm
no legacy format remains.
4. Report the final status: how many files changed, any remaining issues.The integration phase is where conflicts surface — two workers that were each correct independently might produce an incompatible combined state. TypeScript check catches most of these.
When a worker fails:
Failure Pattern — Workers modifying shared files
✕ Before (broken pattern)
Worker A: modifies lib/types.ts to add ResponseFormat type Worker B: modifies lib/types.ts to add the same ResponseFormat type differently Both complete "successfully" — but when integrated, lib/types.ts has a conflict or a duplicate type that breaks the build.
✓ After (production pattern)
Orchestrator rule: lib/types.ts changes happen in a preliminary step by the orchestrator before any workers start. Workers only consume shared types — they never modify shared files. If shared types need changes: do it once, verify it, then start workers.
Lesson: Shared file writes must be serialized. Multi-agent parallelism is safe only when each agent has exclusive ownership of the files it modifies.
Multi-agent adds real coordination overhead. Don't use it when:
The rule: if you're spending more than 5 minutes designing the orchestration, step back. Can the task be decomposed and run sequentially in one context instead? Usually yes.
You're ready for multi-agent work when:
Milestone 7
You can now run coordinated multi-agent workflows — parallel execution for independent tasks, orchestrator verification for integration, and failure isolation that keeps the whole operation recoverable. This is the architecture for serious AI-assisted engineering work.
Claude Code Multi-Agent Documentation
Official reference for spawning sub-agents, the Agent tool, and orchestration patterns.