Mapa da trilha
Conteúdo detalhado
⚡ Setup do Claude Code
Flag experimental, settings.json, modos de display e treinar o repo com a doc oficial.
Verifique claude --version ≥ 2.1.32 e ative CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 em settings.json.
Sem isso, nada da feature funciona — e o erro silencioso aparece como "Claude não criou agentes".
Settings em .claude/settings.json (projeto) ou ~/.claude/settings.json (user); env vs JSON.
teammateMode aceita auto (default), tmux (split-pane) ou in-process (tudo no mesmo terminal).
Ver os teammates ao vivo é o que separa "fé cega" de "diagnóstico". Tmux é o ouro padrão.
VS Code/Windows Terminal/Ghostty NÃO suportam split; flag --teammate-mode sobrescreve por sessão.
Teammates herdam permissões do lead. Pré-aprove tools comuns no permissions.allow do settings.
Sem pré-aprovação, cada teammate pausa para perguntar — o time vira sequencial na prática.
Allowlist por padrão de comando (Bash(npm *)); evite --dangerously-skip em produção.
Salve a doc oficial em docs/agent-teams-reference.md para o lead consultar localmente.
Lead com referência local toma decisões melhores e mais rápidas; reduz busca web em runtime.
CLAUDE.md aponta para os docs; subagent definitions em .claude/agents/ ficam acessíveis a teammates.
Teammates carregam CLAUDE.md, MCP servers e skills do projeto e do user — igual a uma sessão normal.
Configurar MCP/skill bem feito uma vez vale para todos os teammates; reduz prompt boilerplate.
Subagent definitions usadas como teammates NÃO carregam skills/mcpServers do frontmatter.
Rodar o prompt do vídeo (Backend + Frontend + QA) e observar o ciclo: spawn → trabalho → QA reprova → retrabalho.
Se o smoke passa, seu setup está sólido. Se trava, você sabe que é configuração — não prompt.
3 teammates Sonnet; deliverable = landing page funcional; observar idle notifications no log.
📝 Anatomia do prompt de spawn
Goal → Team → Roles → Final deliverables: o template canônico em 4 blocos.
Frase única que descreve o objetivo final do time, não o passo-a-passo. Ex: "construir app que rode em localhost:3000".
Teammates acordam sem contexto; o Goal dá norte para decisões locais que o lead não pode antecipar.
Goal é compartilhado com todos os teammates; deve ser observável (ter critério de aceite).
"Crie um time de N teammates usando Sonnet/Haiku/Opus" — explicite tamanho e modelo padrão da equipe.
Sem N explícito o lead chuta. Sem modelo, default herda do lead — pode ser caro demais.
3–5 teammates é o ponto ótimo; misture modelos por papel; nomeie o time (facilita auditoria).
Cada role tem 3 campos: o que faz, o que entrega, e para quem manda mensagem ao terminar.
Sem destinatário explícito, todos voltam ao lead — o que vira gargalo. Sem entrega, há retrabalho.
Use nomes ("Backend Dev manda para Frontend Dev"); território de arquivos por role.
Lista explícita de artefatos que devem existir ao fim: app rodando, tests/report.md, docs/build-summary.md, etc.
Define o critério de "terminei" do lead. Sem isso, o time pode encerrar com trabalho parcial.
Deliverables observáveis (paths e formatos); critérios mensuráveis; "executável" > "código pronto".
Mantenha prompts/spawn-fullstack.md, spawn-pr-review.md, spawn-debug.md versionados.
Times bem desenhados são reutilizáveis. Salvar bons prompts vale ouro — escala para o time todo.
Variáveis (módulo a revisar, papel principal); changelog do prompt; "playbook por situação".
Lab de transformar "faça uma equipe pra criar um app" em prompt de 4 blocos com roles e deliverables claros.
Ver o "antes/depois" treina o olho — depois o aluno corrige no automático.
Eliminar ambiguidades; nomear destinatários; explicitar formato do entregável; checar "quem dorme com qual arquivo".
✓✗ Faça vs Não Faça
As 5 práticas que multiplicam qualidade e os 5 antipatterns que arruínam a equipe.
Cada arquivo tem um único teammate responsável. Nada de "front e back editam App.js".
Sem ownership, há overwrite silencioso. É a fonte #1 de "trabalho perdido" em times de agentes.
Pastas por papel (src/api/ = backend; src/ui/ = frontend); contratos via mailbox.
Cada role entrega um artefato verificável: arquivo, endpoint, teste passando — não "um relatório".
Artefato força o agente a fechar; relatório vago vira ping-pong.
Path + formato + critério de aceite; "ver no terminal" > "descrever em texto".
"Quando terminar, mande para Frontend Dev". Nome explícito no prompt do papel.
Sem destinatário, todos retornam ao lead — eliminando a vantagem do mailbox.
Nomes consistentes; "envie para Y após terminar X"; lead cuida só de exceções.
3 a 5 teammates é o doce-spot de paralelismo vs coordenação. Acima disso, retornos diminuem.
Times grandes parecem "mais sérios" mas geram coordenação demais e desperdício de tokens.
5–6 tasks/teammate; se > 15 tasks, comece com 3 teammates; escale só se medir ganho real.
Inclua links, arquivos relevantes, severidade desejada, formato do report — diretamente no prompt do papel.
Teammates "acordam zerados". O que não estiver no spawn, não existe para eles.
CLAUDE.md ajuda; mas instruções específicas da tarefa têm que ir no prompt; explicite tom/severidade.
5 erros comuns: arquivo compartilhado, deliverable vago, presumir o plano, 10+ integrantes, nenhum contexto.
Reconhecer cada um por nome ajuda a corrigir prompts no instante — em vez de relançar a equipe.
Cada antipattern tem contraparte FAÇA; checklist mental de 5 itens antes de dar enter.