Subagentes no Claude Code: o que fazem e quando usar

Resposta curta: um subagente é um contexto separado ao qual o Claude Code delega trabalho, com seu próprio prompt de sistema, suas próprias permissões de ferramentas e, se você quiser, seu próprio modelo. A documentação da Anthropic lista cinco motivos para usá-los: preservar contexto mantendo exploração e implementação fora da conversa principal, impor restrições limitando quais ferramentas um subagente pode usar, reaproveitar configurações entre projetos, especializar o comportamento com prompts de sistema focados e controlar custos direcionando tarefas para modelos mais rápidos e baratos. O primeiro e o último são os que mais mudam o seu dia a dia.

O problema de contexto que eles resolvem

Cada mensagem numa sessão do Claude Code carrega junto a conversa inteira. Se você ler quarenta arquivos caçando alguma coisa, esses quarenta arquivos ficam no contexto pelo resto da sessão, disputando espaço com o trabalho que realmente importa.

Isso produz dois sintomas visíveis. Sessões longas ficam mais lentas e mais caras, porque o que puxa o custo é a janela de contexto e não o número de mensagens. E a qualidade cai, porque o sinal de que você precisa fica soterrado sob saídas de exploração que só foram relevantes por cinco minutos.

Um subagente resolve isso na estrutura. O trabalho delegado acontece no contexto dele e só o resultado volta. Doze arquivos lidos durante uma busca custam a você um resumo na conversa principal em vez de doze arquivos de ruído.

É por isso que existem os agentes de exploração embutidos, e é por isso que serão os que você mais vai usar, muitas vezes sem perceber.

Os subagentes embutidos

A Anthropic documenta vários tipos que vêm com o Claude Code, e saber a que cada um está restrito explica bastante comportamento que de outro modo confunde.

Dois detalhes dessa tabela merecem uma pausa.

O agente Explore tem teto no Opus na API do Claude, e a Anthropic explica que é para o Explore nunca rodar num modelo mais caro do que aquele que você já escolheu para a sessão. É uma trava de custo deliberada, e significa que vasculhar sua base de código não é cobrado em silêncio à tarifa de modelo de ponta.

Explore e Plan são ambos somente leitura, com Write e Edit negados. É isso que torna a delegação segura: você pode mandar um agente investigar sem qualquer possibilidade de que ele comece a editar enquanto está lá dentro.

Escrever o seu

Um subagente próprio é um arquivo Markdown com frontmatter. A estrutura é curta o bastante para decorar.

---
name: code-improver
description: Analisa arquivos e sugere melhorias de legibilidade, desempenho e boas práticas. Usar depois de escrever ou modificar código.
tools: Read, Grep, Glob
model: sonnet
---
Você é um especialista em melhoria de código. Para cada problema encontrado, explique a causa, mostre o código atual e forneça uma versão melhorada.

Quatro campos fazem todo o trabalho. name é como ele é invocado. description é o que o Claude lê ao decidir se delega, o que a torna a linha mais importante do arquivo. tools restringe o que ele pode fazer. model escolhe o nível.

A descrição merece mais cuidado do que costuma receber. O Claude a usa para decidir quando aquele agente se aplica, então uma descrição vaga produz um agente que nunca é acionado ou é acionado para a coisa errada. Inclua a condição de disparo de forma explícita, como no exemplo acima com “Usar depois de escrever ou modificar código”.

O jeito mais rápido de criar um é pedir ao Claude Code que escreva. Descreva o que você quer, onde deve ficar e o que ele pode fazer, e revise o arquivo gerado antes de usar.

Onde ficam as definições de subagentes

A Anthropic documenta cinco locais com uma ordem de precedência definida, e conhecê-la evita a confusão comum em que um agente se comporta diferente do arquivo que você está olhando.

1. Configurações gerenciadas, distribuídas centralmente para toda a organização. Prioridade máxima.
2. A flag --agents da CLI, que aceita JSON e vale para a sessão atual.
3. .claude/agents/, restrito ao projeto atual.
4. ~/.claude/agents/, disponível em todos os seus projetos.
5. A pasta agents/ de um plugin, onde quer que esse plugin esteja ativo. Prioridade mínima.

A regra prática: definições de projeto passam por cima das pessoais, e o que sua organização distribui por configurações gerenciadas passa por cima das duas.

A flag --agents é subutilizada e útil para trabalho pontual. Você passa um objeto JSON definindo agentes em linha ao iniciar o Claude Code, o que serve quando quer uma configuração especializada uma vez só sem deixar arquivo para trás.

O que saber antes de montar uma frota

Delegar custa uma ida e volta. O subagente precisa ser iniciado, receber contexto e devolver seu resultado. Para uma tarefa que a conversa principal fecharia em dois passos, esse custo extra é perda. A delegação compensa quando o trabalho despejaria muito material no seu contexto principal.

O subagente não enxerga sua conversa. Ele começa do zero com o que você passar. Um briefing que assume contexto compartilhado produz um agente trabalhando no problema errado, e essa é de longe a falha mais comum.

Restrições de ferramentas são o objetivo, não uma limitação. Um revisor somente leitura que não pode editar é mais útil do que um sem restrição, porque você pode rodá-lo sem conferir depois o que ele tocou.

Modelos mais baratos costumam bastar. A Anthropic lista direcionar tarefas para modelos mais rápidos e baratos como o Haiku entre os cinco motivos para usar subagentes. A 1 dólar por milhão de tokens de entrada contra 5 do Opus 5, uma tarefa mecânica delegada ao Haiku é economia real sem custo de qualidade.

Você pode desligá-los. Para bloquear um tipo embutido, adicione-o a permissions.deny. Para cortar a delegação por completo, negue a própria ferramenta Agent. Para remover só Explore e Plan, defina CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, que exige Claude Code v2.1.198 ou posterior e faz o Claude ler os arquivos diretamente. No modo não interativo e no Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 remove todos os tipos embutidos, deixando só os seus.

Um quadro de decisão: delegar ou não

Passe uma tarefa por estas cinco perguntas antes de escrever um agente para ela.

1. Isso vai gerar muita saída que depois eu não preciso? Buscar, explorar, ler muitos arquivos, varrer logs. Se sim, delegue: é o argumento mais forte.
2. Convém impedir a escrita aqui? Revisão, auditoria, análise e investigação se beneficiam de um agente somente leitura, e a restrição é justamente o valor.
3. É mecânico o bastante para um modelo mais barato? Formatação, refatorações mecânicas, consultas diretas. Direcione para o Haiku e mantenha a sessão principal no modelo de que você realmente precisa.
4. Vou fazer isso mais de duas ou três vezes? Algo pontual não justifica um arquivo de definição. Algo semanal justifica, e o reuso se acumula.
5. Consigo instruí-lo sem o meu histórico de conversa? Se a tarefa só faz sentido com três horas de contexto acumulado, a delegação vai decepcionar. Reescreva o briefing ou mantenha no fio principal.

Três ou mais sins significam escrever o agente. Menos significa fazer em linha.

Erros comuns neste momento

• Escrever uma description vaga, de modo que o Claude nunca delega àquele agente ou delega o trabalho errado.
• Dar todas as ferramentas a cada agente próprio, jogando fora o principal benefício de segurança.
• Delegar algo pequeno, em que o custo da ida e volta supera a economia.
• Presumir que o subagente enxerga a conversa e instruí-lo como se enxergasse.
• Construir uma biblioteca grande de agentes antes de constatar que algum deles é usado.

Três agentes que valem a pena escrever primeiro

Se você prefere pontos de partida concretos a princípios, estes três se pagam na maioria das bases de código e levam poucos minutos cada.

Um revisor somente leitura. Ferramentas limitadas a Read, Grep e Glob, modelo em Sonnet, com um prompt de sistema mandando reportar problemas do código atual e uma substituição sugerida em vez de fazer mudanças. Como ele não pode editar, você pode rodá-lo em qualquer coisa sem conferir depois o que foi tocado.

Um investigador de testes que falham. Dê a ele a capacidade de rodar testes e ler arquivos, e um prompt pedindo para encontrar a causa raiz e reportá-la em vez de consertar. A separação importa: um agente que diagnostica e reporta deixa você decidir se a correção vale a pena, enquanto um que diagnostica e conserta te amarra à primeira teoria dele.

Um verificador de documentação no Haiku. Trabalho mecânico de comparar o que a documentação afirma com o que o código faz. É exatamente o perfil para um modelo mais barato: volume alto, pouco julgamento, saída fácil de verificar.

Repare que dois dos três são somente leitura e o terceiro roda no modelo mais barato. Essa proporção não é acidente. Os agentes que acabam sendo usados são os que dá para rodar sem supervisão ou os baratos o suficiente para rodar sempre.

Onde isso entra num fluxo maior

Subagentes combinam naturalmente com o modo plano. Investigar num agente somente leitura, trazer um resumo, planejar contra esse resumo na conversa principal e então executar. A exploração nunca entra no seu contexto principal e o plano é construído sobre um resumo limpo em vez de quarenta arquivos de saída bruta.

Eles também mudam o comportamento de sessões longas. O efeito prático de desviar a exploração é que uma sessão continua utilizável por muito mais tempo antes que a pressão de contexto a degrade, e para quem está tocando uma tarefa grande isso vale mais do que a economia de tokens.

Construir o julgamento por trás da configuração

A mecânica desta página se aprende em vinte minutos. O que demora mais é saber qual trabalho delegar, como instruir um agente para que a saída dele seja aproveitável e quando uma restrição melhora um resultado em vez de limitá-lo.

É o mesmo julgamento que vale para qualquer ferramenta com agentes: decompor uma tarefa em partes que dá para fazer de forma independente, especificar cada uma para que a saída seja verificável e desenhar o passo de revisão que pega o que dá errado. Aprender numa sequência estruturada em vez de por tentativa e erro produz um método que sobrevive quando a ferramenta muda, o que nesta área acontece sem falta. Se você quer uma rota estruturada, explore as aulas da Coursiv e confira os detalhes de plano vigentes no site oficial.

Perguntas frequentes

Seu próximo passo

Pegue a investigação que você mais repete, aquela em que acaba lendo uma dúzia de arquivos para responder a uma pergunta recorrente, e escreva um agente somente leitura para ela com tools: Read, Grep, Glob e uma descrição que diga quando deve ser usado. Rode uma vez e compare como fica sua conversa principal depois com uma sessão em que você fez a mesma busca em linha. Essa única comparação defende a delegação melhor do que qualquer explicação do mecanismo.