Armadilhas e correções
🔍 O que mostra
Tabela de triagem com 6 pares "Erro comum → Correção". Cobre os sintomas mais frequentes em equipes de produção: pedidos repetidos de permissão, conflitos de arquivo, agente ocioso, gasto excessivo de tokens, trabalho perdido e aprovação incorreta.
🎯 Como aplicar
Quando algo der errado, identifique o sintoma na coluna esquerda e aplique a correção da direita. É a ponte entre "alguma coisa não está funcionando" e "ação concreta". Imprima e cole na parede do time.
🗺️ Decodificando os 6 pares
- 🔒 Pedir permissões → Pré-aprovar ferramentas — configure o allowlist no
settings.jsonantes do spawn. - 📁 Conflitos de arquivo → Atribuir donos — territórios disjuntos no prompt.
- 😴 Agente ocioso → Trabalho independente — se está parado, virou bloqueio sequencial; reformule a tarefa.
- 🔥 Muitos tokens → Menos agentes — reduza para 3 e veja se ainda escala.
- 💾 Trabalho perdido → Arquivos temporários — force gravação intermediária via Bash dentro do papel.
- ❓ Aprovação incorreta → Revisão humana — em decisões irreversíveis, sempre humano no loop.
Consciência de custos
🔍 O que mostra
A escala de custos lado a lado: 1 agente sozinho = 1x; 3 agentes = 3x; 5 agentes ≈ 5x. Embaixo, 4 dicas práticas: máx. 3 por vez quando possível, mantenha-os em paralelo (não sequencial), use subagentes quando só precisa do resultado, desligue cedo quando o trabalho terminou.
🎯 Como aplicar
Custo de equipe é multiplicativo, não aditivo. Antes de spawnar 5, faça a pergunta dura: "a wall-clock economizada compensa pagar 5x?" Se a tarefa termina em 20 min sozinho, equipe de 5 que termina em 8 min custa 5x — mau negócio para tarefas curtas.
🗺️ Decodificando as 4 dicas
- 👥 Máx. 3 por vez — sweet spot custo/benefício; acima disso a coordenação degrada.
- ⚙️ Mantenha em paralelo — equipe sequencial é o pior dos mundos: paga 5x e não economiza wall-clock.
- 🎯 Use subagentes — quando o output cabe num resultado isolado, subagente é dramaticamente mais barato.
- 🔌 Desligue cedo — não deixe teammates ociosos rodando; eles continuam consumindo tokens em idle.
Encerramento limpo
🔍 O que mostra
Os dois caminhos de shutdown lado a lado. Caminho limpo (verde): colegas salvam → equipe de limpeza varre ~/.claude/team/ → fechar sessão. Forçar encerramento (vermelho): arquivos corrompidos, configs órfãs, estado desconhecido — o que sobra quando você dá Ctrl+C cego. O rodapé sintetiza: "Salve primeiro, limpe tudo, depois feche".
🎯 Como aplicar
Encerrar uma equipe é tão importante quanto criá-la. Antes de fechar a sessão, percorra os 3 passos do caminho verde. Ctrl+C cego deixa rastros em ~/.claude/team/ que quebram a próxima execução — diagnosticar isso depois custa muito mais tempo do que os 30 segundos do shutdown limpo.
🗺️ Decodificando os dois caminhos
- ✅ Colegas salvam — cada teammate persiste seu estado intermediário em arquivo.
- ✅ Equipe de limpeza — varre
~/.claude/team/removendo locks e PIDs. - ✅ Fechar sessão — só agora encerra o orquestrador.
- ❌ Arquivos corrompidos — escrita interrompida deixa JSON inválido que o próximo spawn não consegue ler.
- ❌ Configs órfãs — settings de equipe que não foram limpos confundem futuras sessões.
- ❌ Estado desconhecido — impossível diagnosticar depois "por que essa equipe não inicializa".
🎉 Você completou a Trilha 6
Os 12 cards cobrem o ciclo inteiro: topologia → setup → operação → custo → encerramento.
Agora aplique de verdade no seu próximo spawn — e use estas imagens como cola sempre que precisar lembrar de uma regra.