🔧 Diagnóstico, Custo & Encerramento

Sintoma: cada teammate trava perguntando permissão para npm, git, etc.

Sem isso o time vira sequencial. Pré-aprovar é a primeira correção que dobra produtividade.

Allowlist em .claude/settings.json; usar padrões (Bash(npm *)); nunca skip permissions em produção.

Dois teammates editam o mesmo arquivo; o segundo sobrescreve o primeiro silenciosamente.

É o erro mais difícil de detectar — não há crash, só código faltando. Auditoria via git diff é essencial.

Territórios por pasta no spawn; "Backend Dev possui src/api/, ninguém mais escreve lá".

Teammate fica esperando outro; trabalho dele depende do anterior por dependência mal modelada.

Se 1 dos 5 fica ocioso 80% do tempo, você está pagando 5× mas obtendo 4×. Custo silencioso.

Tasks paralelas iniciais; QA roda mocks enquanto Dev codifica; lead nunca espera por todos.

Conta dispara, throughput não acompanha. Sintoma típico de "swarm" de 10+ agentes.

Reduzir teammates ou trocar Sonnet por Haiku no QA já corta 30–50% do custo.

3–5 teammates; modelos por papel; preferir subagent quando der; cortar contexto inicial.

Sessão fecha mal e algumas decisões/análises ficam só na memória do teammate — perdidas.

Salvar em arquivo é a única "memória durável" de um team. Sem isso, replay é impossível.

Arquivos temporários por papel; resumos em docs/; commit incremental no git.

Lead aprova planos ruins ou rejeita planos bons; critério mal calibrado.

No início, peça revisão humana de planos para calibrar critério; depois delegue ao lead.

"Send all plans to me" temporário; critérios precisos no prompt; medir taxa de aprovação x retrabalho.

Trabalho atravessa 3+ camadas técnicas independentes. Cross-layer é o caso de ouro do Teams.

É a situação onde Teams ganham subagentes com folga: 3 contextos especializados em paralelo.

Front + back + DB; Mobile + API + analytics; ML + serving + observability.

Debug com várias teorias; PR review com múltiplas lentes; reproduzir bug por caminhos diferentes.

Anchoring é o inimigo da investigação; teammates "adversários" colapsam o tempo de descoberta.

5 teammates testando 5 hipóteses; debate estruturado; consenso ao fim.

Squad com QA reativo: Dev entrega, QA reprova/aprova, Dev refaz. O loop Dev↔QA é o ouro.

Subagent não consegue "rejeitar e devolver" para o caller — só Teams faz quality gate dinâmico.

Critérios de QA explícitos; mailbox para feedback; QA tem direito de bloquear release.

Tarefa que vai 1→2→3 sem ramificações: rename de função, refactor pequeno, tipagem.

Team aqui só adiciona overhead e tokens. Sessão única + subagent pontual basta.

Sequencial = não paraleliza; coordenação custa; "use a ferramenta certa".

Vários teammates editam o mesmo arquivo ou precisam de TODO o contexto compartilhado.

Você vai pagar 5× e ter overwrite ou agentes copiando contexto. Sessão única ou subagent é melhor.

"Quem dorme com qual arquivo?"; se a resposta for "todos", não use Team.

Pergunta 1: precisam conversar entre si? Pergunta 2: precisa paralelo real? Pergunta 3: cabe em 1 contexto?

Ter as 3 perguntas decoradas evita a maioria dos erros de uso. Decida em 30 segundos.

Sim/Sim/Não → Team; Não/Sim/Não → Subagentes; Não/Não/Sim → Single session.

Cada teammate = 1 contexto = 1 multiplicador linear de tokens. 5 agentes ≈ 5× sessão única.

Saber a "lei do custo" antes te impede de cair na sedução do "swarm com 10 agentes".

Custo = N × tokens médios × preço modelo; ganho ≠ N×; coordenação tem custo.

A doc oficial e a prática convergem: 3–5 é o melhor balanço entre paralelismo e coordenação.

Acima de 5, ganhos diminuem rápido. Menos de 3, raramente vale Teams sobre subagentes.

5–6 tasks/teammate; se 15 tasks, comece com 3; promova só com evidência.

QA simples ou doc → Haiku. Implementação padrão → Sonnet. Arquitetura/decisão crítica → Opus.

Misturar modelos por papel reduz custo total em 30–50% sem perda de qualidade.

Especifique no spawn por role; subagent definitions já trazem modelo no frontmatter.

Use /cost no Claude Code, hooks PostToolUse para logar tokens, e relatórios por teammate.

Sem números, "sentir caro" vira intuição ruim. Medir sempre antes de cortar.

Tokens por papel; tempo de wall-clock; ratio output/input; identifique o role mais caro.

Pesquisa, busca de arquivos, sumário de logs — não precisa conversar entre si. Subagent ganha em custo.

Misturar Teams (onde precisa) + Subagent (onde não precisa) é como bons engenheiros operam.

Subagent = 1 chamada extra; Team = N sessões; nunca use Team para "buscar arquivo".

Se um teammate vai para o caminho errado, não espere ele "achar"; desligue e respawne com prompt corrigido.

Cada minuto adicional de teammate descarrilado é custo zero retorno. Reset é barato.

Shutdown via lead; reentrar com novo prompt; manter context do que deu errado em arquivo.

Antes de qualquer cleanup, peça que cada teammate consolide arquivos finais e relatórios.

É a única "memória" que sobra após shutdown. Sem isso, todo o trabalho vira efêmero.

Deliverables previstos no spawn; resumo final por papel; commit incremental.

Lead pede shutdown a cada teammate; quando todos confirmam, roda cleanup the team.

Apenas o lead deve rodar cleanup; teammate fazendo isso pode deixar resources inconsistentes.

Cleanup falha se há teammate ativo; ordem importa; teammate pode rejeitar shutdown se não terminou.

Após cleanup, encerre a sessão do lead. Os artefatos ficam, o estado do team some.

Não tente "reusar" o lead após cleanup; spawne novo team se precisar continuar.

Lead é fixo na sessão de origem; sem promoção/transferência; saída limpa = sem zumbis.

Matar processo no terminal sem cleanup. Resultado: arquivos órfãos, configs órfãs, estado desconhecido.

Saber o custo do shortcut te impede de usá-lo por preguiça. É reservado para emergências.

Limpe manualmente ~/.claude/teams/<team>/ e tasks órfãos; tmux kill quando aplicável.

Após cleanup, audite git diff, deliverables vs spawn e custo total para fechar o ciclo.

É a hora de aprender. Pós-mortem rápido feeds melhora dos próximos prompts.

Cheklist: deliverables ok? testes passam? custo previsto? armadilha encontrada?

Quando uma run dá certo, salve prompt, settings e resultados para repetir o sucesso.

Times reusáveis com prompts versionados é o pulo do gato para escalar produtividade do squad.

Pasta prompts/; changelog do prompt; templates parametrizados.

Após /resume, o lead pode tentar mensagear teammates que não existem mais; mande respawnar.

Saber a limitação evita confusão "por que ele está mandando para o nada?"

Spawne novos teammates; informe o lead da troca; aceite o "reset parcial".

Teammate às vezes esquece de marcar task como completed e bloqueia dependentes.

Saber que existe te faz desbloquear na hora ao invés de "ficar esperando".

Marque manualmente; cutuque o teammate via mensagem; auditar antes de cleanup.

Teammate termina request/tool atual antes de sair, então shutdown pode demorar minutos.

Não force kill se der tempo; espera é mais limpa.

Pacientemente; só force kill em deadlock real; tools longas (build) são as principais culpadas.

Um lead gerencia apenas um team de cada vez; clean up antes de spawnar outro.

Não há "mudança de time" no meio; planeje a sessão em torno do team que vai existir.

Cleanup → novo spawn; sessões separadas para teams independentes.

Apenas o lead pode criar/gerenciar team. Teammates não criam sub-teams nem outros teammates.

Modelagem hierárquica não funciona em Teams hoje. Use subagents para "ajudantes" do teammate.

Subagent dentro do teammate é OK; flat model only; lead = único orquestrador.

VS Code Terminal, Windows Terminal e Ghostty NÃO suportam split. Use in-process ou outro terminal.

Ajuda a planejar workflow; muitos times trabalham só em VS Code e isso impacta diagnóstico.

Cheque which tmux; default in-process funciona em qualquer terminal.