🎨 Equipes em Imagens

Diagrama "Você → Orquestrador → Agente A/B/C/D" com setas de mailbox bidirecional entre os teammates. Os agentes não conversam direto com você; conversam pelo orquestrador e entre si por mensagens.

Quando alguém perguntar "como funciona Agent Teams?", esta é a primeira imagem que você desenha. Fixa a hierarquia e o canal de comunicação.

Lado esquerdo: agente principal cria N subagentes paralelos, cada um devolve um resultado isolado. Lado direito: líder distribui tarefas para integrantes que se comunicam entre si via lista compartilhada.

Pergunta-chave: "preciso só de respostas paralelas ou de coordenação?" Se for paralelo puro, subagent. Se precisa de mailbox e contexto compartilhado, equipe.

Tabela em 3 colunas: Use Teams (3+ áreas, pesquisa paralela, colaboração com React, quality gates). Evite Teams (sequencial 1→2→3, contexto único, mesmos arquivos, tarefa simples). Subagentes (resultado focado, sem cross-talk, preservar tokens).

É a árvore de decisão antes de qualquer spawn. Se sua tarefa cair na coluna do meio, você está prestes a queimar tokens à toa.

Bloco JSON em settings.json com "env": { "AGENT_TEAMS": 1 } à esquerda; à direita, status "Equipes Ativas ✓" com 3 agentinhos ligados.

Sem essa flag, qualquer prompt sobre "criar equipe" cai em fluxo de subagent comum. Confira no início de toda sessão nova.

Esqueleto: "Crie uma equipe de [N] usando [modelo]…" seguido de 1–N linhas "[Papel] → possui + produz". Três exemplos derivados (Designer de API → /api → rotas + spec; Engenheiro de BD → migrações + esquema; Redator de Testes → testes + suíte).

Sempre que for spawnar uma equipe, escreva o prompt nesse formato literal. "Possui" define território (arquivos), "produz" define entregável (mailbox).

Tabela espelhada. FAÇA: defina responsáveis por arquivo, defina entregáveis, nomeie destinatários, 3–5 integrantes, dê contexto completo. NÃO FAÇA: compartilhar mesmo arquivo, entregáveis vagos, pressupor o plano, 10+ integrantes, sem contexto prévio.

Use como checklist antes de enviar o prompt. Cada linha do "NÃO FAÇA" é um bug que aparece nas Trilhas 4 (diagnóstico) — esse card os previne de origem.

Três blocos numerados: (1) Tenha seu território — um arquivo, um dono. (2) Mensagens diretas — formato API, evite líder central. (3) Comece em paralelo — sequencial é antipattern, todos começam agora.

Antes de aceitar qualquer plano sugerido pelo orquestrador, faça o pente-fino com essas 3 regras. Quebrar uma delas é causa raiz de 80% das falhas.

Esquerda (vermelho): "Sem contexto" — histórico de chat bloqueado, sem prompt. Direita (verde): "Permissões OK" — mesmas permissões (Bash, Editar, Escrever) e auto-load de CLAUDE.md, servidores MCP e Skills.

Cada teammate começa cego sobre a conversa anterior. Tudo que ele precisa saber tem que vir no prompt de spawn ou no CLAUDE.md auto-carregado.

4 estágios numerados: (1) Pesquisa — somente leitura. (2) Enviar plano. (3) Líder revisa — pode pedir nova revisão. (4) Executar — só aqui o teammate ganha acesso total de escrita.

É o gate que separa "agente que toca os arquivos sem pensar" de "agente revisado". Para qualquer mudança não-trivial, force plan mode antes do execute.

Tabela "Erro comum → Correção": pedir permissões → pré-aprovar; conflitos de arquivo → atribuir donos; agente ocioso → trabalho independente; muitos tokens → menos agentes; trabalho perdido → arquivos temporários; aprovação incorreta → revisão humana.

Quando algo der errado em produção, esta é a tabela de triagem. Identifique o sintoma da esquerda e aplique a correção da direita.

Topo: 1 agente sozinho = custo 1x; 3 agentes ≈ 3x; 5 agentes ≈ 5x. Embaixo, 4 dicas: máx. 3 por vez; mantenha em paralelo; use subagentes (resultado-only); desligue cedo.

Custo de equipe é multiplicativo, não aditivo na percepção. Antes de spawnar 5, pergunte: "isso vale 5x o custo do solo? a wall-clock economizada compensa?"

Esquerda (verde): caminho limpo — colegas salvam, equipe de limpeza limpa ~/.claude/team/, fechar sessão. Direita (vermelho): forçar — arquivos órfãos, configs órfãs, estado desconhecido. Rodapé: "Salve primeiro, limpe tudo, depois feche".

Encerrar uma equipe é tão importante quanto criá-la. Sempre passe pelos 3 passos antes de fechar a sessão — Ctrl+C cego deixa rastros que quebram a próxima execução.