Subagentes no Claude Code: o que são e como criar o seu

Conforme você usa o Claude Code em projetos de verdade, percebe um problema: a conversa enche de coisa. Resultado de busca, conteúdo de dez arquivos, logs de teste — tudo isso fica empilhado na janela, e o Claude começa a ficar lento e a esquecer o que importava lá no começo.

A solução oficial da Anthropic pra isso são os subagentes. Pensa neles como ajudantes especializados: o Claude delega uma tarefa pesada pra um deles, que trabalha na própria janela, longe da sua conversa, e te devolve só o resultado limpo.

Se você já criou a sua primeira Skill, vai pegar a ideia rápido — mas as duas coisas resolvem problemas diferentes. Já explico a diferença.

O que é um subagente

Um subagente é um Claude dentro do seu Claude. Ele tem:

• A própria janela de contexto — o que ele lê e busca não entra na sua conversa principal.
• O próprio prompt de sistema — instruções focadas num único tipo de tarefa.
• As próprias ferramentas e permissões — você decide o que ele pode (e o que não pode) fazer.

Quando você pede algo que combina com a especialidade de um subagente, o Claude delega: o ajudante faz o trabalho sozinho e volta com um resumo. É como ter um estagiário que vai até o arquivo, lê tudo, e te traz só a resposta — sem te entupir de papel.

Por que isso importa

Subagentes resolvem três dores de uma vez:

• Preservam contexto. A exploração barulhenta fica fora da sua conversa. Você continua com a janela limpa, focada no que realmente importa.
• Cortam custo. Você pode mandar tarefas simples (buscar arquivos, ler código) pra um modelo mais barato e rápido como o Haiku, enquanto a conversa principal segue no Opus ou Sonnet. Se isso te interessa, vale combinar com as dicas de como gastar menos tokens.
• Impõem limites. Um subagente "revisor" pode ser só de leitura — incapaz de editar ou apagar nada. Você delega com segurança.

Skill ou subagente? A diferença em uma frase

Esse é o ponto que mais confunde:

• Uma Skill padroniza como uma tarefa é feita — e roda dentro da sua conversa.
• Um subagente tira o trabalho pra fora da sua conversa, num espaço isolado.

Regra prática: se você só quer que o Claude siga sempre o mesmo procedimento, é Skill. Se você quer que ele faça um trabalho pesado sem poluir a conversa principal, é subagente. E dá pra usar os dois juntos — um subagente pode até carregar Skills.

Os subagentes que já vêm prontos

O Claude Code já traz alguns embutidos, que ele usa sozinho quando faz sentido:

• Explore — um agente rápido e só de leitura, otimizado pra vasculhar e entender bases de código. Roda no Haiku pra ser barato. É ele que o Claude aciona quando precisa "achar onde está tal função" sem mudar nada.
• Plan — usado no plan mode, pra pesquisar o projeto antes de te apresentar um plano de ação.
• General-purpose — o coringa: faz tarefas complexas de vários passos, com leitura e modificação.

Ou seja: mesmo sem criar nada, você já se beneficia de subagentes todo dia. Criar os seus é só dar mais um passo.

Como criar o seu (o jeito fácil)

O caminho recomendado é o comando /agents, que abre uma interface guiada. Dentro do Claude Code:

/agents

Na aba Library, escolha Create new agent, depois Personal (salva em ~/.claude/agents/, vale em todos os projetos) ou Project (salva em .claude/agents/ e dá pra versionar no Git com o time).

Escolha Generate with Claude e descreva o agente em linguagem natural:

Um agente que revisa o código e sugere melhorias de legibilidade,
performance e boas práticas. Deve explicar cada problema, mostrar o
código atual e propor uma versão melhorada.

O Claude gera o nome, o description e o prompt de sistema. Aí você só escolhe as ferramentas (pra um revisor, deixe só as de leitura) e o modelo (Sonnet equilibra bem custo e qualidade pra analisar código). Salve com Enter — e já pode usar:

Use o agente revisor pra sugerir melhorias neste projeto

Como é o arquivo por dentro

Se preferir criar na mão, um subagente é só um arquivo Markdown em ~/.claude/agents/code-reviewer.md (ou .claude/agents/ no projeto). Ele tem duas partes: o frontmatter YAML com a configuração, e embaixo o prompt de sistema:

---
name: code-reviewer
description: Revisa código buscando qualidade e boas práticas. Use depois de mudanças no código.
tools: Read, Glob, Grep
model: sonnet
---
 
Você é um revisor de código. Ao ser chamado, analise o código e dê
feedback específico e acionável sobre qualidade, segurança e boas práticas.

Só name e description são obrigatórios. Vale conhecer os campos mais úteis:

• description — o mais importante. Diz quando o Claude deve delegar pra esse agente. Capriche nos gatilhos ("use depois de mudanças no código").
• tools — a lista do que o agente pode usar. Se você omitir, ele herda todas as ferramentas da conversa. Listar só Read, Glob, Grep cria um agente incapaz de escrever ou apagar arquivos.
• model — haiku, sonnet, opus ou inherit (o mesmo da conversa principal). É aqui que você corta custo mandando tarefas simples pro Haiku.
• disallowedTools — o inverso de tools: herda tudo, menos o que você proibir. Útil pra um agente que faz quase tudo, exceto editar arquivos (disallowedTools: Write, Edit).

Atenção: subagentes são carregados no início da sessão. Se você editar o arquivo na mão, reinicie o Claude Code pra ele aparecer. Os criados pelo /agents já valem na hora.

Um detalhe que economiza dor de cabeça

Um subagente não pode criar outro subagente. Isso é de propósito: evita aninhamento infinito. A conversa principal delega, o subagente executa e devolve — um nível só. Então pense neles como uma camada de ajudantes diretos, não como uma árvore sem fim.

Por onde continuar

• Se ainda não criou uma Skill, comece por como criar sua própria Skill — Skills e subagentes se completam.
• Quer enxugar o gasto? Combine subagentes no Haiku com as dicas de gastar menos tokens no Claude.
• Tá começando agora no terminal? O guia do Claude Code no terminal te deixa pronto pra usar tudo isso.

A ideia central: tarefa pesada e barulhenta não precisa rodar na sua conversa principal. Delegue pra um subagente especializado, com as ferramentas certas e o modelo certo — e mantenha o foco no que importa.

Fonte: documentação oficial da Anthropic, Create custom subagents. Os fatos (subagentes embutidos, caminhos dos arquivos, campos do frontmatter e o comando /agents) vêm de lá; a redação, os exemplos e a comparação com Skills são deste blog.