Subagente ou mais um prompt no Claude Code: quando dividir a tarefa compensa?

Você abre o Claude Code, manda um prompt, vem resposta, manda outro, e em algum momento a conversa vira um monstro que já leu meio projeto

Aí bate a dúvida de sempre: continuo prompando aqui mesmo ou abro um subagente pra essa parte?

A resposta honesta não é "sempre delegue"

Delegar tem custo, e existe tarefa que rende MUITO mais ficando no fio principal. O que decide não é hype, é o tipo de tarefa. Bora separar isso direito? 🙂

O que é um subagente no Claude Code (e por que isso muda a conta)

Um subagente no Claude Code é uma instância separada do Claude rodando na própria janela de contexto

Na prática: as chamadas de ferramenta e os resultados intermediários ficam lá dentro, e só a mensagem final volta pra conversa principal

Se você já escreveu uma função na vida, a analogia é essa: tu passa os argumentos, a função faz a bagunça dela num escopo isolado e devolve um retorno. O que rolou no meio não suja o escopo de fora

Só que tem o outro lado da moeda, e é ele que quebra a perna de muita gente

O contexto do subagente começa do ZERO

Ele não enxerga o histórico da conversa, não sabe quais arquivos o Claude já leu, não herda nenhuma decisão que vocês tomaram nas últimas duas horas. O único canal do pai pro subagente é a string de prompt da ferramenta Agent, e olhe lá

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

"E se eu quiser justamente que ele saiba de tudo?"

Aí entra o fork. Fork é um subagente que herda a conversa inteira em vez de começar do zero: mesmo system prompt, mesmas ferramentas, mesmo modelo e mesmo histórico da sessão principal. As chamadas de ferramenta dele continuam fora da conversa e só o resultado final volta

Então são dois botões diferentes: o subagente isola a entrada E a saída, o fork isola só a saída. Tudo isso está na documentação de subagentes do Claude Code

Subagente, fork ou mais um prompt: comparação lado a lado

Olhando assim fica fácil: a coluna que dói é a do contexto de entrada

Se a tarefa precisa de tudo que já foi conversado, o subagente puro é o caminho mais trabalhoso, porque tu vai ter que reescrever esse contexto na mão

Casos em que dividir a tarefa compensa

A Anthropic dá um sinal quantitativo bem prático pra isso: quando a tarefa exige explorar dez ou mais arquivos, ou envolve três ou mais peças de trabalho independentes, é sinal forte pra direcionar o Claude a subagentes

E a doc cita três critérios oficiais de uso: saída verbosa que você não precisa no contexto principal, vontade de impor restrição de ferramenta ou permissão, e trabalho autocontido que pode voltar como resumo

Busca profunda, análise de logs e auditoria de dependências

São os exemplos clássicos de tarefa lateral: rendem um caminhão de resultado intermediário que você não vai reler NUNCA

Se isso rola no fio principal, o contexto enche de coisa morta. Num subagente, entra a pergunta e volta a resposta, e o resto fica lá dentro

Revisão sem viés da implementação

Esse caso é interessante porque o isolamento, que era o problema, vira a vantagem

O subagente entrega uma folha em branco: ele não herda as suposições nem os pontos cegos da conversa principal

Ou seja, ele não vai concordar com você só porque vocês passaram a última hora defendendo a mesma ideia 😀

Papéis com permissões diferentes

Cada subagente pode ter permissões e conjunto de ferramentas diferentes

Um subagente de pesquisa fica somente leitura, um de implementação recebe capacidade de edição. É guardrail (limite) de verdade, não promessa no prompt

Três frentes independentes ao mesmo tempo

Vários subagentes podem rodar concorrentes, então subtarefas independentes terminam no tempo da MAIS LENTA em vez da soma de todas

Em fluxos mais avançados, o runtime mantém até 16 agentes rodando simultaneamente (menos em máquinas com poucos núcleos de CPU, ou seja: sem PC da Nasa, menos agentes) e limita uma execução a 1.000 agentes

E tem teto de profundidade: por padrão um subagente pode criar subagentes próprios até três camadas abaixo da conversa principal. No limite, o Claude Code retira a ferramenta Agent de todos os subagentes exceto forks, e o subagente do limite faz o trabalho ele mesmo e devolve um resumo

Casos em que dividir só adiciona ruído

Agora o outro lado, que quase ninguém escreve

Conserto rápido e pergunta focada. A orientação é direta: aqui o overhead da delegação supera o benefício, então é pra continuar prompando na conversa principal mesmo

Mudança fortemente acoplada. Dois subagentes editando o mesmo arquivo em paralelo tendem a conflitar, e mudanças muito acopladas devem ficar numa única janela de contexto. Paralelizar isso não acelera nada, só gera retrabalho

Tarefa que depende de meio histórico. Se o prompt de delegação vira um resumão da sessão inteira, o sinal é claro: ou é caso de fork, ou é caso de continuar no fio principal. Reescrever contexto na mão é onde a delegação costuma falhar

Latência de partida. A doc alerta que um subagente que não é fork começa do zero e pode precisar de tempo pra reunir contexto. Pra uma tarefa de dois minutos, esse tempo é o próprio prejuízo

Procedimento que você quer ver acontecendo. Esse é o corte entre skill e subagente: skill quando você quer o procedimento dentro do fio principal, pra ver e dirigir cada passo; subagente quando uma tarefa lateral entupiria a conversa com resultado intermediário que você não vai reler. Se ficou confuso, vale entender a diferença entre skill e subagente antes de sair criando arquivo

Sinais práticos para decidir na hora

Checklist curto, pra rodar na cabeça no meio do trabalho:

• A saída é verbosa e descartável? Sinal de delegar
• A tarefa é autocontida e volta bem como resumo? Sinal de delegar
• Dá pra escrever TUDO que ela precisa num prompt só (caminhos, erros, decisões)? Se sim, subagente. Se não, fork ou fio principal
• As frentes tocam arquivos diferentes? Se tocam o mesmo arquivo, não paralelize
• Você quer acompanhar e corrigir passo a passo? Fica no fio principal
• São dez ou mais arquivos pra explorar, ou três ou mais frentes independentes? Sinal forte de subagente

E o veredito honesto, sem romantizar a ferramenta: o padrão continua sendo o fio principal

Delegar é exceção com motivo, não estilo de vida. Transformar toda tarefa em subagente troca um problema (contexto cheio) por outro (você reescrevendo contexto em prompt e conferindo resumo de coisa que nem viu acontecer)

Como delegar direito quando a decisão for dividir

Decidiu que vale? Então bora fazer o básico bem feito

1. Escreva o prompt de delegação completo. Como o subagente começa sem histórico, tudo que ele precisa tem que estar ali: caminhos de arquivo, mensagens de erro na íntegra, decisões que já foram tomadas. É a mesma disciplina de descrever tudo no prompt que vale pra qualquer tarefa difícil. O erro comum deste passo é mandar "continua o que a gente estava fazendo": pro subagente, não estava acontecendo nada

2. Comece pelos built-ins. O Claude Code já vem com general-purpose (tarefas multi-etapas que exigem exploração e ação), Explore (busca e navegação rápida no código, somente leitura) e Plan (pesquisa e análise durante o plan mode). O general-purpose pode ser acionado via ferramenta Agent sem você definir nada. O erro comum deste passo é sair criando arquivo de subagente antes de testar se um built-in já resolvia

3. Saiba o que dá pra retomar. Os agentes embutidos Explore e Plan são one-shot e não retornam agentId, então pra retomar o trabalho é preciso usar um agente customizado ou o general-purpose. O erro comum deste passo é planejar um fluxo em cima de retomar um Explore que não volta

4. Force o subagente quando quiser. Digita @ e escolhe o subagente no typeahead (igual a @-mencionar arquivo) ou cita o nome dele no prompt. Tome cuidado com um detalhe: o @-mention controla QUAL subagente é chamado, não o prompt que ele recebe. A mensagem completa vai pro Claude, que escreve a tarefa do subagente. O erro comum deste passo é achar que o texto digitado depois do @ chega palavra por palavra no subagente

5. Crie o subagente por arquivo. Os subagentes definidos por arquivo ficam em .claude/agents/ (escopo de projeto) e ~/.claude/agents/ (escopo de usuário, disponível em todos os projetos), e o Claude Code varre essas pastas de forma recursiva, então dá pra organizar em subpastas. O arquivo é Markdown com frontmatter YAML: só name e description são obrigatórios; tools, model (sonnet, opus, haiku ou inherit) e color são opcionais, e o corpo abaixo do frontmatter é o system prompt do subagente

---
name: revisor
description: Revisa a implementação recém-concluída e aponta problemas antes do commit
model: sonnet
---

Você revisa código que acabou de ser escrito.
Leia os arquivos citados no prompt, aponte bugs, casos não tratados e inconsistências.
Seja específico: arquivo, trecho e o motivo.
Devolva um resumo curto com os problemas em ordem de gravidade.

O erro comum deste passo é escrever uma description vaga tipo "ajuda com código": é por ela que o Claude decide quando chamar esse subagente

6. Não procure o wizard do /agents. A partir da versão 2.1.198 do Claude Code, o comando não abre mais o painel interativo de criação: ele imprime um aviso apontando os locais dos arquivos de subagente. Criar ou editar passa a ser pedir ao Claude ou mexer direto em .claude/agents/. O erro comum deste passo é achar que o recurso morreu: arquivos, frontmatter e pastas seguem iguaizinhos

Quando o problema não é dividir, e sim o contexto cheio

Tem um caso que se disfarça MUITO bem de "preciso de subagente"

O contexto encheu e o Claude começou a ficar lerdo e esquecido, aí a conclusão automática é abrir subagente pra tudo

Só que às vezes o fio principal continua sendo o lugar certo, ele só precisa de uma faxina

• /context mostra um detalhamento ao vivo do uso do contexto por categoria, com sugestões de otimização e quais arquivos CLAUDE.md e de memória foram carregados
• /compact aceita instrução, tipo pedir foco num bug específico, em vez de compactar no chute
• /autocompact recebe uma contagem de tokens pra definir o quão cheio o contexto fica antes da compactação automática (que já acontece sozinha quando o limite se aproxima)

Rodar /context antes de decidir é o tipo de hábito que economiza uma arquitetura inteira de subagente que não precisava existir

Conclusão

A régua é simples e cabe em uma frase: delega quando a tarefa é autocontida, verbosa e independente, e continua no fio principal quando ela é curta, acoplada ou depende do que já foi conversado

Na próxima tarefa, antes de abrir subagente, roda o check: quantos arquivos estão envolvidos, quantas frentes independentes existem, e se a saída é daquelas que você nunca mais vai ler. Passa o /context junto pra ver se o problema não era só contexto entupido

E se quiser um primeiro experimento de baixo risco, cria UM subagente de revisão, somente pra olhar o que acabou de ser implementado

É o caso onde o isolamento joga a favor: folha em branco, sem os pontos cegos da conversa

Testa e tira sua própria conclusão, beleza? 😀

até o próximo post!