Core Concept & Activation
Coordinator mode e um modo operacional onde Claude nunca executa tools diretamente. Todas operacoes com side-effects sao delegadas para worker agents. Ativado via:
CLAUDE_CODE_COORDINATOR_MODE=1isCoordinatorMode()
Le env var em runtime sem caching, permitindo mudancas de modo em sessoes resumidas.
matchSessionMode()
Garante que sessoes resumidas restaurem o modo correto mutando process.env.CLAUDE_CODE_COORDINATOR_MODE.
flowchart TD
U["User"]
C["Coordinator
CLAUDE_CODE_COORDINATOR_MODE=1"]
W1["Worker A
research"]
W2["Worker B
implementation"]
W3["Worker C
verification"]
U -->|"request"| C
C -->|"Agent(...)"| W1
C -->|"Agent(...)"| W2
C -->|"SendMessage(...)"| W2
C -->|"Agent(...)"| W3
W1 -->|"task-notification"| C
W2 -->|"task-notification"| C
W3 -->|"task-notification"| C
C -->|"synthesis + status"| U
style U fill:#1a1816,stroke:#c47a50,color:#b8b0a4
style C fill:#22201d,stroke:#c47a50,color:#c47a50
style W1 fill:#1f241d,stroke:#6e9468,color:#6e9468
style W2 fill:#241f2a,stroke:#8e82ad,color:#8e82ad
style W3 fill:#262117,stroke:#b8965e,color:#b8965e
Four-Phase Task Workflow
Workers paralelos investigam codebase. Read-only tasks rodam livremente em paralelo.
Coordinator cria specs com file paths e line numbers. Nunca "based on your findings."
Workers fazem changes, rodam tests, commit. Write-heavy: one at a time per overlapping file set.
Workers provam que codigo funciona independentemente. Pode rodar alongside implementation em areas diferentes.
Ponto critico: "Never write 'based on your findings.'" O coordinator deve sintetizar findings em file paths e line numbers especificos. Synthesis e o trabalho mais importante.
Continue vs Spawn Fresh Decision
O criterio chave e context overlap: quanto do contexto anterior e util para a proxima tarefa?
| Situacao | Acao | Razao |
|---|---|---|
| Research explorou exatos files para edit | Continue | Worker tem files no context |
| Research broad, implementation narrow | Spawn fresh | Evita exploration noise |
| Corrigindo falha ou estendendo trabalho | Continue | Worker tem error context |
| Verificando codigo de outro worker | Spawn fresh | Verifier precisa fresh eyes |
| Primeira tentativa usou approach errado | Spawn fresh | Wrong-approach context polui |
| Task unrelated | Spawn fresh | Sem context util |
Worker Prompt Guidelines
Workers nao tem contexto do coordinator. Tudo deve estar no prompt. Prompts devem ser fully self-contained.
❌ Bad Prompts
- "Fix the bug we discussed"
- "Based on your findings, implement the fix"
Delegam entendimento ao worker que nao tem contexto.
✅ Good Prompts
"Fix null pointer in src/auth/validate.ts:42. The user field is undefined when Session.expired is true. Add null check before user.id access -- return 401 with 'Session expired' if null. Run tests, commit, report hash."
Tool Restrictions & Worker Context
| Dimensao | Single-Agent | Coordinator |
|---|---|---|
| Role | Does work itself | Dispatches and synthesizes |
| Tool count | Full set | 4 tools only |
| Filesystem | Direct read/write | None -- must delegate |
| Parallelism | Sequential tool calls | Multiple concurrent workers |
Coordinator (4 tools)
Workers (full set)
Simple mode (CLAUDE_CODE_SIMPLE=1) restringe workers a apenas Bash, Read e Edit.
The Scratchpad: Cross-Worker Knowledge
O scratchpad e um diretorio compartilhado onde workers podem ler e escrever sem permission prompts, criando um workspace duravel para findings que sobrevivem entre workers.
getCoordinatorUserContext() -- 3 componentes
- Tool enumeration: Computed at runtime
- MCP server advertisement: Connected server names appended
- Scratchpad injection: Shared directory path para cross-worker knowledge