Guia prático de quando usar sub-agents
O Claude Code tem um Agent tool que permite iniciar sub-agents independentes durante uma conversa. Cada sub-agent tem seu próprio contexto, executa a tarefa e devolve o resultado para o agent principal.
Parece poderoso, mas na prática, na maioria das vezes você não precisa disso. Este artigo explica quando usar sub-agents realmente faz diferença e quando só complica sem necessidade.
Você não consegue chamar o Agent tool diretamente pelo CLAUDE.md ou por um slash command -- é uma ferramenta interna que o Claude Code decide usar por conta própria. O que você pode fazer é influenciar essa decisão através dos seus prompts.
O fluxo funciona assim:
Características principais:
- Contexto independente: o sub-agent não enxerga o histórico da conversa principal, apenas o prompt que recebeu na inicialização
- Compressão de resultados: não importa quantos arquivos leu ou quantos comandos rodou internamente, o que volta para o agent principal é um resumo
- Execução em paralelo: vários sub-agents podem ser iniciados simultaneamente
O caso mais clássico. Você pede para o Claude Code investigar um problema e precisa explorar várias frentes ao mesmo tempo.
Por exemplo: "Como a autenticação está implementada nesse projeto?"
Sem sub-agents, o Claude Code executaria tudo em sequência: ler o auth controller, depois o middleware, depois as rotas, depois o model, depois o config... passo a passo. Lento.
Com sub-agents:
Iniciar 3 sub-agents em paralelo:
- Agent 1: investigar a lógica de autenticação em controllers e middleware
- Agent 2: analisar o design de usuários e sessões na camada de models
- Agent 3: verificar arquivos de configuração e variáveis de ambiente relacionadas à autenticação
Três frentes ao mesmo tempo, resultados consolidados. No seu CLAUDE.md você pode orientar assim:
## Tarefas de investigação
Quando precisar investigar um problema que abrange múltiplos módulos,
priorize iniciar vários sub-agents em paralelo para explorar cada área,
e depois consolide as conclusões.
A janela de contexto do Claude Code é limitada. Se uma subtarefa precisa ler muitos arquivos mas no final você só precisa de uma conclusão, um sub-agent pode absorver todo esse "lixo de processo" sem poluir o contexto principal.
Exemplos típicos:
O que essas tarefas têm em comum: muita entrada, pouca saída. O sub-agent digere toda a informação internamente e devolve só o essencial.
Para tarefas onde você não tem certeza do resultado, pode usar um sub-agent com o parâmetro isolation: "worktree". Isso faz ele trabalhar em um git worktree separado. Se algo der errado, seu diretório de trabalho atual não é afetado.
## Refatorações de alto risco
Para refatorações de grande escala, use sub-agents com isolamento worktree.
Confirme que o resultado está correto antes de fazer merge.
Cenários ideais:
- Refatorações exploratórias: não sabe se uma abordagem vai funcionar, deixa o sub-agent testar primeiro
- Comparação de abordagens em paralelo: implementar a mesma funcionalidade de duas formas e comparar
- Geração de código: gerar código boilerplate em volume, revisar e depois integrar
"Renomear essa função de camelCase para snake_case" -- é só fazer direto. O overhead de iniciar um sub-agent (montar contexto, esperar retorno, interpretar resultado) acaba sendo maior do que simplesmente executar a tarefa.
Regra prática: se um Grep + um Edit resolvem, não divida em sub-agents.
"Ler a configuração → alterar o código com base na configuração → atualizar os testes com base nas alterações"
Em tarefas com dependência em cadeia, cada passo depende do resultado do anterior. Se dividir em sub-agents, você teria que passar resultados intermediários de um prompt para outro: é complicado e fácil de perder informação. Melhor executar em sequência.
Um sub-agent retorna texto resumido, não dados estruturados. Se você precisa que ele faça uma alteração exata (como inserir código específico na linha 47), é mais confiável deixar o agent principal fazer diretamente.
Sub-agents são bons para "investigar e dar conclusões", não para "executar alterações com precisão".
Se a conversa acabou de começar e a janela de contexto está praticamente vazia, não faz sentido dividir em sub-agents para "proteger o contexto". Espere a conversa crescer e o agent principal começar a comprimir o histórico; aí sim considere delegar trabalho pesado para sub-agents.
Veja um cenário concreto: investigar todos os controllers que usam before_action em um projeto Rails e analisar os padrões de autenticação e autorização.
Sem sub-agents:
O Claude Code lê os arquivos de controllers um por um, e cada leitura ocupa espaço no contexto principal. Com 20 controllers, só o conteúdo dos arquivos já pode consumir uma quantidade enorme de tokens. Na hora de entregar a análise final, os detalhes lidos no início provavelmente já foram comprimidos e perdidos.
Com sub-agents:
Iniciar sub-agent: "Leia todos os controllers em app/controllers/,
encontre todos os callbacks before_action, analise os padrões
de autenticação e autorização, e retorne um resumo categorizado."
O sub-agent lê todos os arquivos no próprio contexto e devolve um resumo limpo. O contexto do agent principal quase não é consumido, e com a conclusão em mãos ele pode seguir em frente.
Você não pode forçar o Claude Code a usar ou não usar sub-agents, mas pode estabelecer preferências pelo CLAUDE.md:
## Preferências de uso de agents
### Tarefas que valem delegar a sub-agents
- Investigação transversal (consultar 3 ou mais diretórios)
- Busca e análise de código em larga escala
- Refatorações exploratórias (com isolamento worktree)
### Tarefas que NÃO devem usar sub-agents
- Modificações em um único arquivo
- Operações sequenciais com dependências
- Bug fixes onde já se sabe exatamente o que mudar
O "processo" dessa tarefa é muito maior do que a "conclusão"?
Se sim -- use um sub-agent para digerir o processo e devolver só a conclusão.
Se não -- faça direto, sem camadas intermediárias.
Sub-agents não são melhores por serem mais numerosos. São uma ferramenta de gerenciamento de contexto, não um framework de programação concorrente. Bem usados, mantêm o Claude Code lúcido em projetos grandes. Mal usados, só desperdiçam tempo de inicialização.