Subagentes do Claude Code: Como Funcionam e Quando Usar na Prática

Um subagente é uma função para a qual você delega: o Claude entrega um trabalho a ele, ele resolve em uma janela separada que você nunca vê e retorna uma resposta limpa. Bem usado, é a maior alavanca isolada para manter o Claude Code coerente ao longo de uma sessão de várias horas. Mal usado, é uma forma de queimar tokens e adicionar latência sem ganho nenhum. Este guia cobre os dois lados: a mecânica exata, o arquivo que define um subagente e a regra honesta para saber quando ele se paga.

A versão de 20 segundos

Um subagente executa uma tarefa paralela autocontida no próprio contexto isolado e devolve um resumo curto para a sua conversa principal. É essa a ideia inteira. Ele existe para resolver um problema específico: sessões agênticas longas se enchem de ruído (resultados de grep, logs de build, arquivos lidos uma vez e nunca mais referenciados) até que o modelo passe a gastar mais atenção gerenciando bagunça do que fazendo o seu trabalho.

Mova esse trabalho barulhento para dentro de um subagente e a bagunça fica lá. A sua thread principal enxerga apenas a conclusão. Ou seja: o modelo mental correto não é "um time de engenheiros de IA colaborando". É higiene de contexto com valor de retorno. Guarde isso e todas as outras decisões sobre subagentes ficam mais fáceis.

O que é de fato um subagente do Claude Code

Um subagente roda na própria janela de contexto, com um system prompt customizado, acesso específico a ferramentas e permissões independentes. Quando o Claude encontra uma tarefa que combina com a função declarada de um subagente, ele delega; o subagente trabalha de forma independente e retorna o resultado. Essa é a definição oficial, e as partes que importam são janela de contexto própria e retorna o resultado.

Aqui está o ponto que a maioria das explicações erra. Um subagente começa do zero. Ele não enxerga o seu histórico de conversa, os arquivos que o Claude já leu nem as skills que você já invocou. O Claude compõe uma mensagem curta de delegação que resume a tarefa, e o subagente trabalha a partir dali com apenas o próprio system prompt e detalhes básicos do ambiente, como o diretório de trabalho, e não o system prompt completo do Claude Code. Quando termina, só o resumo dele volta.

Esse isolamento corta dos dois lados, e entender essa troca é o jogo inteiro:

• O ganho: todo o meio verboso (os doze arquivos que ele leu, o grep que falhou, o log que ele varreu) nunca encosta no seu contexto principal. Você recebe a resposta sem a bagunça.
• O custo: o subagente precisa reunir de novo o contexto que você já tinha. Se a tarefa depende do histórico da conversa para fazer sentido, um subagente que começa do zero vai patinar.

O arquivo que define um subagente

Um subagente customizado é um arquivo Markdown com frontmatter YAML. O frontmatter é a configuração; o corpo em Markdown vira o system prompt do subagente. Só dois campos são obrigatórios: name e description.

---
name: code-reviewer
description: Revisa código em busca de qualidade e boas práticas. Use imediatamente após escrever ou modificar código.
tools: Read, Glob, Grep
model: sonnet
---

Você é um revisor de código sênior. Ao ser invocado, rode git diff para ver as
mudanças recentes, foque nos arquivos modificados e revise clareza, nomes,
tratamento de erros, segredos expostos, validação de entrada e cobertura de
testes. Agrupe seu feedback por prioridade: problemas críticos, alertas e
depois sugestões.

Esse é um subagente completo e funcional. A description não é decoração: o Claude a lê para decidir quando delegar, então "revisa código, use imediatamente após escrever ou modificar código" puxa o subagente no momento certo, enquanto um vago "ajudante de código" o deixa parado sem uso. Escreva a descrição como se fosse um anúncio de vaga para um especialista.

Você não precisa escrever o arquivo à mão. O comando /agents do Claude Code abre uma interface com abas para gerenciar subagentes: uma aba Running, que lista os subagentes ativos e os recém-finalizados (onde você pode abri-los ou pará-los), e uma aba Library, para criar, editar e organizar. Um detalhe importante: os subagentes são carregados no início da sessão, então, se você editar um arquivo direto no disco, precisa reiniciar a sessão para que a mudança valha. Subagentes criados ou editados pela interface /agents valem na hora.

Onde ficam os subagentes e qual definição vence

O mesmo arquivo de subagente se comporta de forma diferente dependendo de onde você o coloca, e o local decide quem pode usá-lo e qual definição vence quando os nomes colidem.

Quando dois subagentes têm o mesmo nome, vence o local de maior prioridade: definições gerenciadas ganham do projeto, e o projeto ganha do usuário. Subagentes de projeto são descobertos subindo a partir do seu diretório de trabalho e, a partir da v2.1.178, a definição mais próxima do diretório de trabalho vence em caso de conflito de nomes. Existe ainda uma opção só de sessão: passar subagentes como JSON com a flag --agents ao iniciar o Claude Code. Eles existem naquela sessão sem nunca serem salvos em disco, o que é prático para scripts de automação e testes rápidos.

A regra prática: um subagente que codifica como este código deve ser revisado ou testado pertence a .claude/agents/ e vai para o controle de versão, para que o time inteiro receba. Um subagente que reflete como você pessoalmente gosta de trabalhar vai para ~/.claude/agents/ e te acompanha em todos os projetos.

Modelo e ferramentas: os dois botões que importam

Dois campos do frontmatter fazem quase todo o trabalho real, e acertar neles é o que leva os subagentes de "bacana" a genuinamente vantajosos em custo.

Modelo. O campo model aceita um alias (sonnet, opus, haiku, fable), um ID completo de modelo como claude-opus-4-8, ou inherit. Se você omitir, o padrão é inherit, ou seja, o subagente usa o mesmo modelo da sua conversa principal. Essa é uma alavanca de orçamento escondida à vista de todos. Um subagente cuja função inteira é "dar grep no código e resumir o que encontrar" não precisa de um modelo de fronteira. Defina model: haiku e o trabalho braçal roda em um modelo mais barato e mais rápido, enquanto a sua sessão principal continua no Opus para pensar.

Ferramentas. Por padrão, um subagente herda todas as ferramentas internas e ferramentas MCP que a sua conversa principal tem. Você estreita isso com um de dois campos: tools é uma lista de permissão (só estas), disallowedTools é uma lista de bloqueio (todas menos estas). Um subagente de pesquisa que nunca deve encostar nos seus arquivos recebe tools: Read, Grep, Glob, Bash e fica fisicamente impedido de editar qualquer coisa. Isso não é só organização. É uma fronteira real de segurança: um revisor somente leitura não consegue reescrever por acidente o arquivo que está revisando.

Mais um botão que vale conhecer: isolation: worktree roda o subagente em um git worktree temporário, uma cópia isolada do seu repositório, que é limpa automaticamente se o subagente não fizer alterações. Recorra a ele quando quiser que um subagente tente algo arriscado sem pisar na sua árvore de trabalho.

Quando usar um subagente do Claude Code e quando não usar

Esta é a seção que os despejos de configuração do GitHub pulam, e é a que de fato economiza tempo e dinheiro. Um subagente não é de graça, então a pergunta nunca é "eu poderia usar um aqui", e sim "o isolamento se paga aqui".

E os casos em que o subagente é a ferramenta errada, direto de como o recurso deve ser usado:

• Vai e volta iterativo. Se a tarefa exige refinamento frequente e o seu julgamento no laço, mantenha na conversa principal. Delegar quebra o laço.
• Fases que compartilham contexto. Um fluxo de planejamento, depois implementação, depois testes, em que cada fase se apoia na anterior, pertence a uma thread só, e não a três subagentes isolados que começam cegos.
• Mudanças rápidas e pontuais. Subir um subagente para corrigir um erro de digitação custa mais do que a correção.
• Trabalho sensível a latência. Subagentes começam do zero e precisam de tempo para reunir contexto. Quando você quer a resposta agora, fazer inline é mais rápido.

Subagente, skill, fork ou time de agentes: qual usar

O Claude Code agora tem quatro maneiras de estruturar trabalho, e é fácil confundi-las. A diferença é inteiramente sobre contexto.

A divisão que mais confunde é skill x subagente, porque as duas parecem "conhecimento salvo". Uma skill é um conjunto de instruções reutilizáveis que rodam no contexto da sua conversa principal, então ela enxerga tudo o que você está fazendo. Um subagente é o oposto: é isolado por design e não vê nada além da tarefa que você entrega. Se você quer que o Claude aplique um estilo da casa enquanto continua trabalhando com você, isso é uma skill. Se você quer que uma investigação barulhenta aconteça fora de vista e reporte de volta, isso é um subagente.

O fork é o meio-termo útil: ele herda toda a conversa até ali (mesmo system prompt, ferramentas, modelo e histórico de mensagens), então você não reexplica nada, mas as chamadas de ferramenta dele continuam fora do seu contexto principal e só o resultado final volta. Use um fork quando um subagente nomeado precisaria de contexto demais para ser útil. (O modo fork fica atrás da variável de ambiente CLAUDE_CODE_FORK_SUBAGENT.)

Os recursos avançados e seus limites

Duas capacidades mais recentes deixam os subagentes muito mais poderosos, e cada uma vem com uma borda real a respeitar.

Aninhamento. A partir do Claude Code v2.1.172, um subagente pode gerar os próprios subagentes. Um subagente revisor pode despachar um verificador por achado, e toda essa saída intermediária fica enterrada; só o resumo do subagente de nível mais alto chega até você. O limite é fixo: o aninhamento vai até cinco níveis de profundidade, não é configurável, e um subagente no nível cinco não recebe a ferramenta Agent, então não consegue gerar mais nenhum. Esse teto existe por um motivo. Um fan-out profundamente aninhado é como você lança um enxame sem querer e vê o gasto de tokens disparar, então trate a profundidade como orçamento, não como meta.

Memória. Adicione memory: project (ou user, ou local) e o subagente ganha um diretório de memória persistente do qual ele lê e no qual escreve entre sessões. Um code-reviewer com memória de projeto acumula ao longo do tempo um registro das suas convenções e dos problemas recorrentes, então ele fica mais afiado quanto mais você o usa. project é o padrão recomendado porque é compartilhável pelo controle de versão. Com a memória ligada, o Claude Code injeta as primeiras 200 linhas (ou 25KB) do MEMORY.md do subagente no system prompt dele na inicialização, então mantenha esse arquivo curado.

Um bom primeiro passo: construa um subagente focado (um code-reviewer somente leitura é o exemplo canônico), versione-o em .claude/agents/ e deixe-o rodar após cada mudança. Quando isso provar seu valor, adicione um subagente de pesquisa em um modelo mais barato. Os times que extraem valor aqui não estão rodando trinta agentes. Estão rodando três, e cada um faz um trabalho bem feito. Se a sua escolha ainda é entre ferramentas de programação, essa é outra decisão, tratada em Codex x Claude Code x Cursor e no panorama mais amplo em os melhores agentes de IA para programar.

Se você está integrando o Claude Code ao jeito como de fato entrega software, é sobre isso que escrevo na maior parte do tempo. Assine a newsletter para receber as configurações que funcionam, não o hype de dia de lançamento.