Subagentes do Claude Code parecem a solução perfeita pra quem quer organizar fluxo de IA. Você cria um pra revisar código, outro pra buscar arquivo, outro pra rodar teste, outro pra escrever documentação. Em duas semanas, descobre que o custo subiu, o resultado piorou e os subagentes começaram a se atrapalhar entre si.
Não é exagero. Eu mesmo já caí nessa.
Trabalho com IA aplicada todo dia e venho usando o Claude Code desde antes da feature de subagente virar mainstream. Vi gente colocar um subagente pra cada coisa e o resultado ficar pior do que um agente principal bem configurado, com mais lentidão e conta mais salgada no fim do mês.
Esse artigo vai te ajudar a entender quando faz sentido criar subagentes no Claude Code e quando você está só se complicando à toa. Vou cobrir o que eles são na prática, em quais cenários compensam, quando o agente principal resolve melhor e quais são as armadilhas que ninguém te conta antes.
O que são subagentes no Claude Code
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 pro agente principal. Ele tem seu próprio contexto, suas próprias ferramentas e, mais importante, esquece tudo depois que termina.
Pensa nele como um colega que você chama pra resolver uma coisa específica. Você passa o briefing, ele volta com o resultado, fim. Não tem memória da conversa anterior, não tem acesso ao histórico do principal, não compartilha o que aprendeu com outros subagentes que rodaram em paralelo.
Essa isolação é o ponto forte e o ponto fraco ao mesmo tempo. Resolve poluição de contexto, mas exige que você tenha clareza do que quer antes de chamar.
Quando usar subagentes no Claude Code (sinais de que vale a pena)
Tem três cenários onde subagentes no Claude Code pagam o custo extra. Fora desses três, na minha visão, você quase sempre faz melhor sem.
Tarefa com escopo isolado e fechado
Quando você precisa fazer algo que não depende do resto da conversa, subagente é ouro. Buscar um arquivo específico, validar um link externo, contar quantos lugares chamam uma função em três pastas diferentes. Coisas onde a entrada é clara e a saída é pequena.
Trabalho que poluiria o contexto principal
Se a tarefa vai puxar dois mil tokens de output bruto e você só precisa de uma resposta de uma linha, o subagente segura essa sujeira pra ele. O principal recebe só a conclusão. Isso preserva contexto pras etapas que realmente importam.
Trabalho independente que pode rodar em paralelo
Quando você tem três investigações que não dependem entre si, dá pra disparar três subagentes em paralelo. Cada um faz o seu, todos voltam, você compila o resultado. Em pesquisa multi-fonte, isso muda a velocidade real de quem trabalha o dia inteiro com IA.
Como funciona o subagente do Claude Code na prática
Vou direto nos detalhes que pegam quem está começando agora.
Cada subagente nasce sem memória
Ele não viu sua conversa, não conhece os arquivos que você editou, não sabe da decisão que você tomou no parágrafo anterior. Tudo que ele precisa, você precisa colocar no prompt dele. Briefing curto demais gera trabalho ruim. Briefing exagerado gasta token à toa. O equilíbrio vem com prática.
O retorno é uma mensagem só
O subagente devolve um único bloco de texto pro principal. Sem ida e volta, sem perguntas no meio, sem “deixa eu confirmar antes de continuar”. O que ele decidir, você recebe pronto. Se ele se enrolou no meio do caminho, você só descobre lendo a resposta final.
Custo entra no caixa por separado
Cada subagente é uma conversa nova, com tokens de input e output próprios. Se você manda quatro de uma vez, paga quatro vezes. Em tarefa simples isso é desprezível. Em pesquisa que puxa muito contexto, vira surpresa no fim do mês.
Subagente vs agente principal bem-prompted (qual escolher)
Essa é a comparação que mais me pedem pra fazer.
Quando o agente principal resolve melhor
Tarefa que precisa de continuidade, decisão progressiva, ajuste em cima do que veio antes. Refatoração que depende de entender o estilo de código que você vinha usando na sessão. Debugging que exige correlacionar três pistas que apareceram em momentos diferentes da conversa. Subagente perde tudo isso porque começa do zero.
Quando o subagente compensa
Trabalho isolado, sem dependência de histórico, com saída pequena ou ruidosa. Tudo que se encaixa em “vai lá, faz isso, me traz só a resposta”. Aí o custo extra se paga em contexto preservado e em paralelismo real.
Na prática, quando eu tô em dúvida, eu pergunto uma coisa só: “isso aqui depende do que eu já discuti?”. Se sim, fica no principal. Se não, vira subagente. Esse padrão tem tudo a ver com a forma de pensar sobre delegação entre agentes de IA: o que define se a delegação compensa é o quanto de contexto precisa atravessar a fronteira.
O que esperar quando você começa a usar subagentes
Antes de criar o primeiro, vale ajustar a expectativa pra evitar frustração.
- Resultado mais consistente em tarefas de busca: subagente focado em search bate o principal multitarefa quase sempre.
- Latência um pouco maior por tarefa: cada chamada paga o overhead de subir um contexto novo.
- Mais facilidade pra debugar contexto: o principal fica limpo, então quando algo dá errado é mais óbvio onde olhar.
- Custo proporcional ao número de chamadas: três subagentes em paralelo gastam o equivalente a três conversas separadas.
- Necessidade de prompts mais explícitos: sem briefing claro, o subagente vai longe na direção errada antes de você perceber.
O impacto de criar subagente pra tudo
Tem gente que descobre a feature e quer transformar todo o fluxo em uma rede de subagentes. Na minha experiência, o resultado costuma ser pior do que começar com o principal e ir extraindo o que realmente justificar.
Quando você quebra demais, o principal vira só roteador. Cada decisão vira “vou perguntar pro subagente X, depois pro Y”. O custo dispara, a latência sobe, e a qualidade muitas vezes cai porque cada subagente perde o contexto que daria a melhor resposta. É um padrão clássico de over-engineering com cara nova.
Vale acompanhar de perto o custo e latência de LLMs ao adotar subagentes em massa. Não é raro a conta dobrar sem ganho perceptível na qualidade do que volta.
Dúvidas comuns sobre subagentes no Claude Code
Subagente é a mesma coisa que MCP server?
Não. MCP server é uma fonte de ferramentas externas, tipo conectar o agente a um banco, a uma API ou ao sistema de arquivos. Subagente é uma instância do modelo executando uma tarefa em isolado. Os dois podem se combinar, mas resolvem problemas diferentes.
Dá pra encadear subagentes (um chamando outro)?
Tecnicamente sim, mas raramente é boa ideia. Cada nível adicional perde mais contexto, paga mais token e fica mais difícil de auditar. Quando eu vejo gente fazendo isso, geralmente o problema podia ser resolvido com um único subagente bem briefado.
Faz sentido criar subagente pra refatorar código?
Depende. Refatoração isolada em um arquivo, com instrução clara, funciona bem. Refatoração que cruza múltiplos arquivos e depende do estilo da base de código fica melhor no principal, que tem o contexto acumulado da sessão.
Tem como ver o que o subagente fez por dentro?
Sim, o Claude Code mostra a execução do subagente em detalhe. Vale a pena olhar nas primeiras vezes pra calibrar o briefing. Subagente que volta com resposta meia-boca quase sempre teve briefing meia-boca.
Conclusão e próximo passo
Subagentes no Claude Code são ferramentas poderosas pra três cenários específicos: tarefa isolada, contexto que ia poluir o principal e trabalho paralelo independente. Fora disso, na maior parte do tempo, agente principal bem-prompted faz melhor com menos esforço e menos custo.
O caminho que eu recomendo é começar sem subagente nenhum. Identifica a tarefa que mais sobrecarrega o contexto principal, extrai ela pra um subagente focado, observa se o ganho compensa o custo. Repete só quando o padrão se confirmar.
Se você quer aproveitar melhor o Claude Code no dia a dia, o próximo passo é:
- Mapear duas ou três tarefas no seu fluxo que poluem o contexto principal e poderiam virar subagente.
- Escrever um briefing curto e específico pra cada uma antes de criar o subagente.
- Acompanhar custo e qualidade por uma semana antes de adicionar mais subagentes ao fluxo.
Pra aprofundar, vale ler a documentação oficial dos subagentes do Claude Code, que cobre os parâmetros de configuração e os padrões recomendados. E se quiser entender melhor a outra ponta do trabalho com IA, dá uma olhada em como projetar ferramentas para agentes de IA e em qual escolher entre Cursor e Claude Code no dia a dia.