📦 Subagentes: contexto isolado
Subagent é uma instância dentro da sessão atual. Tem contexto próprio, tools restritas por allowlist, executa a task e devolve um resultado para quem chamou. Não conversa com outros subagents.
📌 Quando usar subagent
Quando você quer paralelizar pesquisa/sumarização sem poluir o contexto principal e sem precisar que os workers troquem mensagens.
- •Pesquisa de docs/repos
- •Sumário de logs
- •Análise de PRs (read-only)
- •Verificações que não escrevem código
💡 Custo baixo
Subagents são o jeito mais barato de ganhar paralelismo: 1 chamada extra, retorno em texto.
👥 Teams: contexto + mailbox
Em um team, cada teammate é uma sessão Claude Code completa e independente. O que muda é o canal de mailbox que permite comunicação P2P direta — mais a task list compartilhada.
📌 Quando usar team
Quando teammates precisam trocar contratos, pedir retrabalho, debater hipóteses ou cobrir camadas distintas em paralelo.
- •Cross-layer (front + back + tests)
- •PR review com 3 lentes
- •Debug com hipóteses concorrentes
- •Squad Dev↔QA com retrabalho
⚠️ Custo alto
Cada teammate é uma sessão completa. 5 teammates ≈ 5× tokens da sessão equivalente.
💰 Custo: 1x → 3x → 5x
A doc oficial e a prática convergem: cada teammate adiciona ~1x ao custo da sessão. 5 teammates ≈ 5x. Times grandes parecem mais inteligentes, mas raramente entregam 5x mais.
📊 Numbers que importam
- 3-5 teammates é o doce-spot
- 5-6 tasks por teammate
- > 10 teammates = retorno cai rápido
- Misturar Haiku/Sonnet/Opus por papel reduz 30-50%
💡 Decisão prática
Comece sempre com 3 teammates. Só aumente se medir ganho real, não percepção.
⏱️ Latência: paralelo vs sequencial
Subagents geralmente rodam em sequência dentro do caller. Teams rodam concorrentes — o tempo de parede colapsa para o do gargalo.
✓ Quando teams ganham
- ✓Tarefas independentes
- ✓Caminhos paralelos de pesquisa
- ✓5 hipóteses testadas em paralelo
✗ Quando teams empatam
- ✗Trabalho intrinsecamente sequencial
- ✗Tudo depende de um único output anterior
- ✗Time fica esperando 1 teammate
🛡️ Permissões: herança e propagação
Subagents têm tools controlados por allowlist no frontmatter. Teammates herdam permissões do lead no spawn. Erro grave de configuração se propaga para todo o time.
⚠️ Cuidado com --dangerously-skip-permissions
Se o lead roda em modo permissivo, todo o time também roda. Risco real, especialmente com QA com Bash livre.
💡 Pre-aprove no settings
Allowlist específica em .claude/settings.json resolve sem abrir tudo.
🧭 Árvore de decisão: 3 perguntas
Decida em 30 segundos com 3 perguntas: (1) precisam conversar entre si? (2) precisa paralelo real? (3) cabe em 1 contexto?
Pergunta 1
Workers precisam trocar mensagens?
Sim → Team. Não → continua.
Pergunta 2
Trabalho paraleliza?
Sim → Subagents (paralelos). Não → continua.
Pergunta 3
Cabe em uma sessão?
Sim → Single session. Não → divida em subagents.
💡 Dúvida persistente?
Comece com subagents. Migra para team só se sentir falta de mailbox.
📌 Resumo do Módulo
Próximo módulo:
1.3 — Estado da arte fora do Claude Code