Subagentes Claude Code: como usar /fork e cortar até 90% dos tokens
Resumo rápido (TL;DR): os subagentes Claude Code são instâncias paralelas do Claude que executam tarefas em segundo plano e devolvem só um resumo para a sessão principal — mantendo seu contexto limpo. A novidade de junho de 2026 é o comando /fork (ativado pela flag CLAUDE_CODE_FORK_SUBAGENT=1): ele faz os agentes-filhos compartilharem o cache de contexto do agente-pai, o que pode cortar até 90% do custo em tokens quando você roda vários agentes ao mesmo tempo. Neste guia você vai entender a diferença entre subagente normal e fork, quando usar cada um, o passo a passo para ativar e os limites reais da função.
O Claude Code, o agente de terminal da Anthropic, recebeu nas versões 2.1.172 e 2.1.173 (10 e 11 de junho de 2026) duas mudanças que reorganizam a forma como ele trabalha com múltiplos agentes: subagentes aninhados em até 5 níveis e o amadurecimento do fork de subagentes, que agora funciona também em sessões não interativas e no SDK. Para quem usa IA para programar de verdade, isso muda a economia da brincadeira — literalmente, porque mexe na conta de tokens.
O que são subagentes no Claude Code
Um subagente é uma cópia separada do Claude, com a própria janela de contexto, disparada pela sessão principal para resolver uma tarefa específica. Ele lê os arquivos que precisa, raciocina sobre o código e devolve para o "agente-pai" um resumo conciso do que fez. A vantagem central é simples: o trabalho pesado acontece numa janela à parte, e a sua sessão principal não fica entupida de logs, leituras de arquivo e tentativas intermediárias.
Pense num exemplo prático. Você pede ao Claude Code para "revisar a segurança de toda a pasta /api". Em vez de ler dezenas de arquivos dentro da conversa principal — gastando contexto e poluindo o histórico —, ele dispara um subagente que faz a varredura isolada e volta só com a lista de problemas encontrados. A conversa principal recebe o resultado, não o processo.
Os subagentes Claude Code existem em algumas formas: a ferramenta Task (disparo programático), arquivos de definição em .claude/agents (agentes especializados com papel fixo, como "revisor", "testador" ou "documentador") e comandos personalizados (slash commands). Em junho de 2026 entrou uma camada nova: o aninhamento, em que um subagente pode, ele próprio, disparar outros subagentes.
Subagentes aninhados: a novidade dos 5 níveis
A partir da versão 2.1.172, os subagentes podem ser aninhados em até 5 níveis de profundidade. Na prática, é recursão com um limite de pilha de 5 quadros — cada quadro carregando o próprio prompt de sistema e podendo até usar um modelo diferente. O número 5 é um teto de segurança, não uma meta: na maioria dos fluxos úteis, as cadeias vivem em profundidade 2 ou 3. Aninhar demais transforma a orquestração num labirinto difícil de depurar e caro de rodar.
O caso de uso real é a especialização em camadas: um agente coordenador delega para um agente "arquiteto", que por sua vez delega tarefas pontuais para agentes "executores". Cada nível resolve um pedaço e resume para o de cima. É o mesmo padrão de uma equipe humana — gerente, líder técnico, desenvolvedores — só que automatizado.
O comando /fork: o que mudou em 2026
Aqui está a parte que importa para o seu bolso. Rodar subagentes em paralelo sempre foi caro, porque cada agente-filho reconstruía do zero três coisas: o prompt de sistema, o array completo de ferramentas e todo o histórico da conversa. Cinco agentes significavam cinco contas cheias de tokens de entrada, sem nenhum compartilhamento.
O fork muda essa matemática. Um subagente "forkado" não recebe uma sessão nova: ele herda os bytes exatos do contexto já renderizado pelo agente-pai — mesmo prompt de sistema, mesmas ferramentas, mesmo histórico de mensagens. Como a serialização fica idêntica byte a byte, o cache de prompt entra em ação: os filhos 2 em diante puxam o prefixo compartilhado direto do cache e pagam apenas pela parte nova, específica da tarefa de cada um.
O resultado é uma redução de custo de aproximadamente 10x por filho adicional, ou até 90% nos tokens de entrada dos filhos 2 a N. O primeiro filho ainda paga preço cheio (não há nada no cache na primeira chamada); a economia aparece do segundo agente em diante.
A conta de tokens, na prática
Para filhos que compartilham um prefixo de cerca de 48.500 tokens, os números ficam concretos:
| Cenário | Custo por filho |
|---|---|
| Sem fork (cada filho reconstrói tudo) | ~48.700 tokens |
| Com fork (filhos 2–N usam o cache) | ~5.050 tokens |
Em um cenário de 5 agentes em paralelo: sem fork, você gastaria cerca de 243.500 tokens só com o contexto compartilhado. Com fork, gasta ~48.700 no primeiro filho e ~20.200 nos outros quatro juntos. O cache faz o resto do trabalho. Para fluxos de revisão, refatoração ou testes que disparam vários agentes de uma vez, essa diferença decide se vale ou não a pena rodar tudo paralelizado.
Subagente normal vs. fork: qual usar
A escolha entre os dois depende de uma pergunta: o filho precisa de muito contexto do pai, ou começa melhor do zero?
| Critério | Subagente normal | Fork (/fork) |
|---|---|---|
| Contexto inicial | Começa limpo, sem o histórico do pai | Herda todo o contexto do pai |
| Custo em paralelo | Cada filho paga prefixo cheio | Filhos 2–N usam cache (até −90%) |
| Janela da sessão principal | Mantém limpa | Filho carrega o histórico completo |
| Melhor para | Tarefas isoladas e bem definidas | Várias abordagens a partir do mesmo ponto; trabalho que exige todo o contexto |
| Risco | Pode faltar contexto ao filho | Sessões longas custam mais no total |
Use o subagente normal quando a tarefa é autocontida — "rode os testes desta pasta", "resuma este arquivo". Use o fork quando o subagente precisaria de muito contexto para ser útil, ou quando você quer testar várias abordagens em paralelo a partir do mesmo ponto de partida (por exemplo, três tentativas diferentes de resolver o mesmo bug, cada uma num filho).
Vale notar um detalhe: o fork só dispara quando o tipo do subagente é omitido na chamada. Se o modelo especifica um tipo nomeado (como "Explore" ou "Plan"), o caminho do fork não é acionado — esses tipos têm a própria lógica.
Como ativar o /fork passo a passo
O fork é opt-in: nada muda sem você ligar a flag. O processo é direto.
Defina a variável de ambiente. No terminal (ou no seu
.bashrc/.zshrc, para valer sempre):export CLAUDE_CODE_FORK_SUBAGENT=1Para pipelines de CI/CD, configure a variável no nível do pipeline. Toda execução de agente daquele pipeline passa a herdar o fork automaticamente.
Dispare os agentes em paralelo normalmente. Com a flag ativa, os filhos 2 em diante já compartilham o prefixo em cache, sem nenhuma configuração extra.
Confira a versão. O fork só existe em builds públicos a partir da v2.1.117; antes disso o caminho era removido na compilação e só rodava internamente na Anthropic. A versão 2.1.173 (11/06/2026) estendeu o suporte para sessões não interativas e o Agent SDK.
Um padrão avançado que o fork libera são as "ilhas de política": comandos com context: fork e agent: <nome> no frontmatter disparam subagentes isolados, com ferramentas pré-declaradas (allowed_tools), que rodam sem pedir aprovação no meio do fluxo e devolvem só um resumo ao pai. Ótimo para automações que você confia e não quer ficar aprovando passo a passo.
Limites e armadilhas que ninguém conta
O fork não é mágica de graça. Há restrições reais que evitam dor de cabeça:
- Janela cresce com a sessão. Os filhos forkados carregam todo o histórico do pai. Em sessões longas, com muitos filhos, o custo total sobe mesmo com cache. É justamente em sessões "quentes" e longas que isso pesa mais.
- Incompatível com o modo coordenador. Um coordenador forkado herdaria o prompt "você é o coordenador, delegue" e começaria a orquestrar em vez de executar. Os dois modos não convivem na mesma sessão.
- Guarda contra recursão. Cada filho forkado recebe uma marcação interna avisando que ele é o fork e não deve gerar novos subagentes. Sem isso, os filhos forkariam filhos infinitamente até estourar o contexto. São dois mecanismos de proteção que precisam concordar antes de liberar a ação.
- É opcional. Sem a variável de ambiente, nada acontece. Não há ativação silenciosa.
Esse cuidado com custo e contexto conversa diretamente com a lógica de economia de tokens que já vimos em outras ferramentas de IA para código. Se você está escolhendo entre editores e agentes, o comparativo de Antigravity vs Cursor vs VS Code mostra onde o Claude Code se encaixa nesse jogo de eficiência.
Onde os subagentes Claude Code se encaixam no seu fluxo
Se você é iniciante em programar com IA, comece pelo básico antes de orquestrar exércitos de agentes. Entender o que é um agente de terminal e como ele difere do chat tradicional é o primeiro passo — o conceito de "IA que tem mãos" está bem explicado no nosso guia sobre o Claude gratuito e o que dá para fazer com ele. E se a ideia de "descrever o que quer e a IA escreve o código" ainda soa nova, vale ler antes sobre vibe coding e seus limites reais.
Os subagentes e o fork brilham em três situações concretas:
Refatoração em larga escala. Vários módulos, vários agentes, cada um cuidando de uma parte — com o fork, quatro dos cinco custam cerca de um décimo do que custariam antes.
Revisão e testes em paralelo. Um agente revisa segurança, outro roda os testes, outro confere a documentação. A sessão principal recebe só os três resumos.
Múltiplas abordagens para o mesmo problema. Quando você não sabe qual caminho seguir, forka três tentativas a partir do mesmo ponto e compara os resultados.
Essa lógica de agentes autônomos não é exclusiva da Anthropic. O Google segue a mesma direção com o Antigravity e sua CLI própria — vale entender o que é o Google Antigravity e como migrar do Gemini CLI para o Antigravity CLI, porque o conceito de orquestrar agentes está virando padrão em todas as ferramentas de desenvolvimento.
Perguntas frequentes
O que são subagentes no Claude Code?
São instâncias separadas do Claude, com a própria janela de contexto, disparadas pela sessão principal para resolver tarefas específicas. Eles leem arquivos, raciocinam sobre o código e devolvem um resumo conciso, mantendo a conversa principal limpa.
O que faz o comando /fork?
O /fork cria um subagente que herda todo o contexto do agente-pai (prompt de sistema, ferramentas e histórico) em vez de começar do zero. Como o conteúdo fica idêntico, os filhos 2 em diante usam o cache de prompt e pagam até 90% menos tokens de entrada.
Como ativar o fork de subagentes?
Defina a variável de ambiente CLAUDE_CODE_FORK_SUBAGENT=1 no seu terminal ou perfil do shell. O recurso está disponível em versões públicas do Claude Code a partir da v2.1.117 e, desde a v2.1.173 (junho de 2026), funciona também em sessões não interativas e no SDK.
Quantos níveis de subagentes aninhados o Claude Code suporta?
A partir da versão 2.1.172, os subagentes podem ser aninhados em até 5 níveis de profundidade. Na prática, a maioria dos fluxos úteis fica em 2 ou 3 níveis — o limite de 5 é um teto de segurança, não uma meta.
Quando usar fork em vez de subagente normal?
Use o fork quando o subagente precisaria de muito contexto do pai para ser útil, ou quando você quer testar várias abordagens em paralelo a partir do mesmo ponto. Use o subagente normal para tarefas isoladas e bem definidas, em que começar com contexto limpo é melhor.
O fork funciona com qualquer modelo?
O fork é um recurso do Claude Code (o agente de terminal), independente do modelo específico. Ele funciona com os modelos Claude disponíveis no Claude Code; a versão 2.1.173 inclusive passou a normalizar nomes de modelo com sufixos como [1m] automaticamente.
Conteúdo produzido pela equipe do Neurônios Artificiais com base na documentação oficial do Claude Code e em testes da comunidade de desenvolvedores. Atualizado em 13 de junho de 2026. Fonte primária: documentação oficial de subagentes da Anthropic.
