A pergunta que decide

Subagentes são poderosos — mas usar um quando não é necessário é pior do que não usar: você fragmenta raciocínio contínuo e desperdiça contexto. A heurística deste módulo cabe numa linha, mas precisa de sinais concretos para funcionar.

Fluxo de decisão — use a pergunta principal primeiro; se "não", percorra as sub-perguntas.

Conteúdo detalhado

O que é

A heurística não é técnica — é sobre o que o resultado faz com o seu contexto. Se a tarefa produz uma montanha de dados que você vai receber como resumo e nunca vai reler linha a linha, o trabalho pertence a um subagente. O chat principal é sua memória de trabalho — não despeje entulho nele.

Uma pergunta filtra 80% dos casos — sem regra complexa.

Output que não relê: logs, listas, resultados brutos de busca.

Resumo de volta: instrua "traga só o resumo" — é parte do prompt.

O que é

Cinco padrões recorrentes que quase sempre pedem subagente — reconhecê-los evita o ciclo de "começar no chat e perceber tarde demais que deveria ter delegado".

Os cinco sinais

📁

Muitos arquivos

Varrer um repositório inteiro, auditar 40 componentes, refatorar uma pasta — qualquer coisa que precise ler N arquivos antes de agir.

📊

Parede de output

Logs de CI, resultados de grep, listas longas de erros — você quer o diagnóstico, não a saída bruta.

🔁

Tarefa repetível

Algo que você vai pedir de novo amanhã, com dados diferentes. Subagente é mais fácil de reusar do que um prompt improvisado.

⚡

Jobs paralelos/independentes

Três análises que não dependem uma da outra podem rodar ao mesmo tempo — o maestro espera todos terminarem e agrega.

🔍

Revisor imparcial

O mesmo chat que escreveu o código tem viés para defendê-lo. Um subagente sem memória do que foi escrito revisa sem filtros.

Escopo fechado: começo e fim claros — o subagente sabe quando terminou.

Output contido: "traga só N bullets" define o tamanho do retorno antes de disparar.

Independência: o subagente não faz perguntas durante a execução.

Os cinco sinais de evitar

✗

Edição rápida

Ajustar uma linha, renomear uma variável, corrigir um typo — o overhead de criar o agente é maior que a tarefa.

✗

Passos dependentes em sequência

Se o passo B só pode começar depois que você viu o resultado do passo A e decidiu, é raciocínio — fique no chat.

✗

Agentes que precisariam conversar entre si

Subagentes não se falam — se a tarefa exige coordenação lateral, ela não é paralelizável.

✗

Precisa do contexto da conversa

O subagente começa com contexto limpo — se ele precisa saber o que foi dito antes, ele está no lugar errado.

✗

Precisa te fazer perguntas

Se o agente vai pausar para pedir esclarecimento, a independência que justifica o subagente não existe.

Raciocínio contínuo: decisões A→B→C pertencem ao chat, não a agentes separados.

Custo de setup: criar agente tem fricção; para 10 segundos de tarefa, não compensa.

Contexto limpo = cego ao passado: se o agente precisar do histórico, passe tudo no prompt.

O que é

Quando você ainda está em dúvida após a pergunta-filtro, existe um critério numérico que resolve a maioria dos casos restantes: 10 ou mais arquivos, ou qualquer output que, se despejado no chat, você nunca iria ler linha a linha.

💡

Regra prática

10+ arquivos para varrer, ou qualquer output que você nunca vai reler = subagente. Abaixo de 10 arquivos e output legível = fique no chat.

Critério numérico: 10 é concreto e rápido de avaliar — sem ambiguidade de "muitos".

Output que não relê: 3 arquivos de log gigantes também disparam — não é só contagem.

Escala: 5 arquivos hoje viram 50 amanhã — projete o subagente cedo.

O que é

A decisão nem sempre é binária — o maestro começa a trabalhar, percebe que o scope cresceu, e decide na hora disparar subagentes. Isso é um workflow dinâmico: delegação em runtime, não no prompt original.

Decisão em runtime: o maestro delega quando vê o tamanho real — não precisa ser definido no prompt original.

Fan-out dinâmico: 1 tarefa → N agentes gerados na hora, cada um com escopo claro.

Maestro como roteador: decide, delega e agrega — nunca executa o trabalho bruto.

O que é

Depois de aprender subagentes, existe uma tendência natural de querer usá-los em tudo — a armadilha da nova ferramenta. Forçar subagente onde não é necessário fragmenta contexto, aumenta latência e complica o debug.

Consequências de forçar

✗ Contexto fragmentado: o subagente começa do zero; o raciocínio que deveria fluir fica partido em pedaços.

✗ Latência sem ganho: criar um agente leva tempo — para tarefas rápidas, você termina mais devagar.

✗ Debug difícil: o que deu errado? Foi o maestro? Foi o subagente? Foi o prompt de delegação?

Princípio da simplicidade: subagente é uma escada — use só quando precisar subir.

Custo real: setup + latência + debug potencial — precisa ser compensado pelo ganho.

Volta ao chat: quando em dúvida, comece no chat; delegue se o scope crescer.

Exemplo: o mesmo tipo de pedido em dois cenários

✓ Vira subagente

"Varre todos os arquivos em src/components/ (há ~60 componentes), verifica quais estão importando a lib legada lodash diretamente, e me traz só a lista com o caminho e a linha. Sem me mostrar o conteúdo dos arquivos."

→ 60 arquivos para varrer (10+)
→ Output nunca será relido linha a linha
→ Escopo fechado e independente

✗ Fica no chat

"Olha esse arquivo utils/format.ts — faz sentido mover essa função para o módulo de helpers? O que você acha?"

→ 1 arquivo, decidível no chat
→ Precisa da conversa anterior (contexto)
→ Raciocínio contínuo, não uma tarefa isolada

Como fica na prática: o maestro tomando a decisão

claude-code — maestro

You: audita todos os módulos em src/ e me fala quais têm coverage abaixo de 60%

Claude: São 48 módulos. Vou disparar um subagente para varrer — ele trará só a lista com coverage. Um momento...

⚙ Subagente iniciado: escaneando 48 arquivos de cobertura...

Claude: Concluído. 7 módulos abaixo de 60%: auth/session.ts (42%), api/retry.ts (38%), e mais 5. Quer que eu priorize por risco ou por facilidade de corrigir?

You: por risco

✓ Output bruto ficou no subagente. Chat ficou limpo.

Prompts prontos para usar

Prompt 1 — varredura de repo

"Varre todos os arquivos em [pasta], encontra [padrão/problema], e me traz só a lista de arquivos afetados com a linha relevante. Não cole o conteúdo dos arquivos."

Aplica o critério: muitos arquivos + output que não relê = subagente.

Prompt 2 — análise paralela

"Analisa [módulo-A], [módulo-B] e [módulo-C] em paralelo — cada um independente. Para cada um, traga: maior risco técnico e sugestão de refator em 3 bullets. Nada mais."

Jobs independentes + output contido = subagente em paralelo.

Prompt 3 — revisor imparcial

"Revisa o código em [arquivo] sem olhar o histórico da nossa conversa. Procura só por: bugs lógicos, edge cases não tratados e código morto. 5 findings máximo, ordenado por severidade."

Revisor imparcial + contexto limpo = subagente é vantagem, não limitação.

🏋️

Exercício: aplique a pergunta a 5 tarefas suas

Use a heurística deste módulo para classificar tarefas reais do seu dia.

O que fazer

Liste 5 tarefas que você costuma pedir ao Claude Code — quanto mais variadas, melhor.
Para cada uma, responda: "Isso vai despejar output que nunca vou reler?"
Se a resposta for "não", percorra as sub-perguntas: 10+ arquivos? Paralelo? Revisor imparcial?
Classifique cada tarefa: subagente, chat direto ou depende do escopo.
Anote o motivo em uma frase.

Critério de sucesso

✓ Consegue classificar sem hesitar em pelo menos 4 das 5 tarefas.

✓ Para cada "subagente", consegue formular o prompt com output contido em uma frase.

✓ Para cada "chat direto", consegue explicar qual sinal de EVITAR se aplica.

✓ Identifica pelo menos 1 tarefa onde a decisão depende do scope real revelado na hora.

Resumo do módulo

✓

A pergunta central — "Isso vai despejar output que nunca vou reler?" decide 80% dos casos.

✓

5 sinais de USAR — muitos arquivos, parede de output, repetível, paralelo, revisor imparcial.

✗

5 sinais de EVITAR — edição rápida, passos dependentes, conversa lateral, precisa do contexto, precisa te perguntar.

✓

Regra dos 10+ — 10 ou mais arquivos ou output que não relê = subagente, sem discussão.

✓

Workflow dinâmico — a decisão pode acontecer em runtime quando o scope crescer.

→

Não force — simples é melhor; use subagente só quando a heurística apontar, não por hábito.

Próximo módulo:

1.6 — Anatomia de um subagente. O arquivo .md: frontmatter (config) + corpo (cérebro).

← Módulo anterior Próximo módulo →