Subagentes no Claude Code: quando usar e quando evitar

Subagente no Claude Code é uma instância separada do modelo que recebe uma tarefa, executa do começo ao fim e devolve uma resposta curta para o agente principal. Ele compensa em três cenários: tarefa isolada, trabalho que poluiria o contexto principal e investigação que pode rodar em paralelo. Fora disso, o agente principal bem configurado costuma fazer melhor, com menos custo e menos lentidão.

Eu mesmo já caí na armadilha de criar um subagente para cada coisa. Em duas semanas o custo subiu, o resultado piorou e eles começaram a se atrapalhar entre si. Este post é o critério que eu uso hoje para decidir quando vale e quando é só complicação. Se você ainda está montando a base, o guia completo de Claude Code em português cobre o que vem antes de qualquer subagente, do CLAUDE.md ao limite do plano.

O que é um subagente no Claude Code?

Pensa nele como um colega que você chama para resolver uma coisa específica. Você passa o briefing, ele volta com o resultado, e acabou. Ele tem o próprio contexto e as próprias ferramentas, não tem memória da conversa anterior, não acessa o histórico do principal e não compartilha o que aprendeu com outros subagentes que rodaram ao mesmo tempo. Quando termina, esquece tudo.

Essa isolação é o ponto forte e o ponto fraco ao mesmo tempo. Ela resolve a poluição de contexto, porque o barulho fica no subagente e só a conclusão volta. Só que ela exige clareza do que você quer antes de chamar, porque não existe ida e volta no meio. A documentação oficial de subagentes lista os parâmetros de configuração, e o que este post acrescenta é o critério de uso.

Quando vale a pena usar subagente?

Primeiro cenário: tarefa com escopo fechado, que não depende do resto da conversa. Buscar um arquivo específico, validar um link externo, contar quantos lugares chamam uma função em três pastas. Entrada clara, saída pequena. Segundo cenário: trabalho que poluiria o contexto principal. Se a tarefa vai puxar dois mil tokens de saída bruta e você só precisa de uma linha de resposta, o subagente segura a sujeira e o principal recebe só a conclusão.

Terceiro cenário: trabalho independente que pode rodar em paralelo. Três investigações que não dependem entre si viram três subagentes disparados juntos, cada um faz o seu, todos voltam, você compila. Em pesquisa com várias fontes isso muda a velocidade real de quem trabalha o dia inteiro com IA. Fora desses três, na minha visão, você quase sempre faz melhor sem, e a tabela abaixo é o resumo que eu uso na dúvida.

Como o subagente funciona na prática?

Cada subagente nasce sem memória. Ele não viu a sua conversa, não conhece os arquivos que você editou e não sabe da decisão do parágrafo anterior. Tudo que ele precisa vai no prompt dele. Briefing curto demais gera trabalho ruim, briefing exagerado gasta token à toa, e o equilíbrio vem com prática. Nas primeiras vezes vale abrir a execução dele em detalhe, porque o Claude Code mostra, e calibrar o briefing pelo que voltou.

O retorno é uma mensagem só. Sem pergunta no meio, sem "deixa eu confirmar antes de continuar". O que ele decidir, você recebe pronto, e se ele se enrolou no caminho você só descobre lendo a resposta final. E o custo entra separado: cada subagente é uma conversa nova, com tokens de entrada e saída próprios. Quatro de uma vez são quatro conversas, o que é desprezível em tarefa simples e vira surpresa no fim do mês em pesquisa pesada.

Subagente ou agente principal bem configurado, qual escolher?

O principal resolve melhor tudo que precisa de continuidade: decisão progressiva, ajuste em cima do que veio antes, refatoração que depende do estilo que você vinha usando na sessão, debug que correlaciona pistas de momentos diferentes. O subagente perde tudo isso porque começa do zero. Ele compensa no trabalho isolado, sem dependência de histórico, com saída pequena ou ruidosa, o "vai lá, faz isso e me traz só a resposta".

Na dúvida, eu faço uma pergunta só: isso aqui depende do que eu já discuti? Se sim, fica no principal. Se não, vira subagente. É o mesmo raciocínio de delegação entre agentes de IA: o que define se a delegação compensa é o quanto de contexto precisa atravessar a fronteira. Quanto mais contexto atravessa, menos vale a pena separar.

O que esperar quando você começa a usar?

Resultado mais consistente em tarefa de busca, porque subagente focado bate o principal multitarefa quase sempre. Latência um pouco maior por tarefa, já que cada chamada paga o custo de subir um contexto novo. Mais facilidade para depurar, porque o principal fica limpo e fica óbvio onde olhar quando algo dá errado. Custo proporcional ao número de chamadas. E necessidade de prompt mais explícito, porque sem briefing claro ele vai longe na direção errada antes de você perceber.

O que acontece quando você cria subagente para tudo?

O principal vira só roteador. Cada decisão vira "vou perguntar para o subagente X, depois para o Y", o custo dispara, a latência sobe e a qualidade cai, porque cada subagente perde o contexto que daria a melhor resposta. É over-engineering com cara nova. Não é raro a conta dobrar sem ganho perceptível, e por isso vale acompanhar o custo de tokens quando adotar subagente em massa.

Quais são as dúvidas mais comuns?

Subagente não é a mesma coisa que MCP. MCP é fonte de ferramenta externa, tipo conectar o agente a um banco, a uma API ou ao sistema de arquivos, e subagente é uma instância do modelo executando uma tarefa isolada. Os dois se combinam, e resolvem problemas diferentes. Encadear subagente chamando subagente é tecnicamente possível e raramente boa ideia. Quase sempre o problema cabia num único subagente bem briefado.

Refatoração em subagente depende do escopo. Isolada em um arquivo, com instrução clara, funciona bem. Cruzando vários arquivos e dependendo do estilo da base, fica melhor no principal. E dá para ver o que o subagente fez por dentro, sim, o Claude Code mostra a execução em detalhe. Subagente que volta com resposta meia-boca quase sempre teve briefing meia-boca, então o lugar de corrigir é o briefing.

Por onde começar?

Começa sem subagente nenhum. Identifica a tarefa que mais sobrecarrega o contexto principal, extrai ela para um subagente focado, observa se o ganho compensa o custo, e repete só quando o padrão se confirmar. Mapeia duas ou três tarefas do seu fluxo que poluem o contexto, escreve um briefing curto para cada uma e acompanha custo e qualidade por uma semana antes de adicionar mais. A outra ponta desse trabalho, projetar as ferramentas que o agente usa, está em como projetar ferramentas para agentes de IA.