Guia

Como usar subagentes no Claude Code

Buscas longas e saídas de teste cheias de ruído enchem rápido a sua conversa no Claude Code. Os subagentes levam esse trabalho para um contexto separado e devolvem um resumo. Este guia explica o que eles são, como criar os seus e quando valem a pena.

Atualizado em 30 de outubro de 2026

Resposta rápida: um subagente é um ajudante especializado para quem o Claude Code passa uma tarefa. Ele trabalha na própria janela de contexto, com instruções e acesso a ferramentas próprios, e devolve só um resultado. Para criar um, salve um arquivo Markdown com name e description no frontmatter em .claude/agents/ (um projeto) ou ~/.claude/agents/ (todos os projetos) e depois peça ao Claude que o use pelo nome ou escolha-o com @.

Os detalhes abaixo vêm da documentação do Claude Code da Anthropic em outubro de 2026. O Claude Code muda com frequência, então rode claude update se algo descrito aqui estiver faltando.

O que são subagentes

Quando o Claude encontra uma tarefa que combina com a descrição de um subagente, ele pode delegá-la. O subagente começa do zero: ele não vê a sua conversa, só as instruções que o Claude repassa. Ele faz o trabalho, como ler dezenas de arquivos ou rodar uma suíte de testes, e devolve um resumo. Sua conversa principal continua curta.

O Claude Code já vem com subagentes embutidos, entre eles:

Explore: busca e análise rápidas e somente leitura de uma base de código.
Plan: pesquisa somente leitura enquanto você está no plan mode.
General-purpose (uso geral): tarefas de vários passos que exigem tanto explorar quanto mudar coisas.

Você não precisa configurá-los; o Claude os usa quando fazem sentido.

Crie seu próprio subagente

Decida o escopo. Para um subagente que o time inteiro possa usar em um repositório, crie a pasta .claude/agents/ no projeto. Para um que acompanhe você em todos os projetos, use ~/.claude/agents/.
Crie um arquivo Markdown nessa pasta, por exemplo code-reviewer.md.
Comece o arquivo com o frontmatter entre duas linhas ---. A primeira linha do arquivo precisa ser ---.
Adicione os dois campos obrigatórios: name (um identificador único, por exemplo code-reviewer, sem dois-pontos) e description (quando o Claude deve usá-lo, por exemplo Reviews code for quality and best practices. Use after code changes.).
Se quiser, adicione tools para limitar o que ele pode usar, por exemplo Read, Glob, Grep para um revisor somente leitura, e model (um apelido de modelo como sonnet ou haiku, um ID de modelo completo ou inherit).
Abaixo do --- de fechamento, escreva as instruções do subagente em linguagem simples: o papel dele, o que conferir e o que devolver.
Salve o arquivo. O Claude Code reconhece mudanças em uma pasta de agentes já existente em poucos segundos; se você criou a pasta durante a sessão, reinicie o Claude Code.

Você também pode simplesmente pedir ao Claude, em uma sessão, que crie um subagente para você. Nas versões atuais, o comando /agents indica exatamente isso, ou editar as pastas diretamente.

Use um subagente

Deixe o Claude escolher: o Claude compara o seu pedido com a description de cada subagente. Expressões como "use proactively" (use de forma proativa) na descrição o incentivam a delegar.
Peça pelo nome: por exemplo Use o subagente code-reviewer para conferir minhas mudanças recentes.
Mencione-o: digite @ e escolha o subagente. Isso garante que esse subagente cuide da tarefa.
Para uma sessão inteira: rode claude --agent code-reviewer.

Quando os subagentes ajudam e quando não

A orientação da Anthropic se resume a isto:

Use um subagente quando	Fique na conversa principal quando
A tarefa gera muita saída que você não precisa guardar, como logs ou resultados de busca	Você precisa de muita troca de mensagens
Você quer restringir quais ferramentas podem ser usadas	Vários passos compartilham muito contexto
O trabalho é independente e pode terminar em um resumo	É uma mudança rápida e pontual
Você quer que pesquisas independentes rodem em paralelo

Bom saber

Se dois subagentes têm o mesmo nome, vence o local de maior prioridade: configurações gerenciadas, depois a opção --agents, depois a pasta do projeto, depois a sua pasta de usuário e, por fim, os plugins.
Um subagente não vê o seu histórico de chat nem os arquivos que o Claude já leu, então depende das instruções que o Claude passa para ele.
Por padrão, até 20 subagentes podem rodar ao mesmo tempo.
Os nomes dos campos são em camelCase (por exemplo disallowedTools, maxTurns), e campos não reconhecidos são ignorados em silêncio, então confira a grafia.
Os arquivos de subagentes do projeto podem ir para o commit, assim o time inteiro recebe os mesmos ajudantes.

Se não funcionar

O Claude não encontra o subagente novo: se a pasta de agentes não existia quando a sessão começou, reinicie o Claude Code.
O arquivo é ignorado sem aviso: as causas comuns são name ou description faltando, YAML inválido ou o --- fora da primeira linha. Rode claude --debug e leia o log de depuração, ou rode claude plugin validate .claude/agents para achar arquivos cujo frontmatter não pode ser lido.
O Claude informa um erro citando ferramentas não resolvidas: quando nenhuma das entradas em tools corresponde a uma ferramenta real, o Claude Code normalmente não inicia o subagente. Corrija a grafia dos nomes das ferramentas.
Modelo errado: rode /tasks para ver qual modelo cada subagente realmente usa.

Guarde os resultados, não só o resumo

O relatório de um subagente fica na sua sessão, que some de vista quando a sessão fecha. Com o plugin do Workbranch para o Claude Code, dizer "save this to Workbranch" (salve isto no Workbranch) organiza as tarefas, decisões e dúvidas em aberto da sessão em um projeto, e a próxima sessão nessa pasta começa mostrando o que ainda está pendente. Veja Workbranch para o Claude. Se uma sessão ficou sem espaço, como retomar uma sessão do Claude Code explica como voltar a ela.

Fontes

Use Claude Code with your Pro or Max plan (Central de Ajuda do Claude, conferido em 30 de outubro de 2026)
Create custom subagents (Claude Code docs, conferido em 30 de outubro de 2026)

Perguntas frequentes

Os subagentes gastam uso extra?

As requisições dos subagentes contam para os mesmos limites de uso da sua conversa principal. Mandar trabalhos simples para um modelo mais barato, como o Haiku, pelo campo model pode ajudar a reduzir custos.

Um subagente pode iniciar os próprios subagentes?

Sim, por padrão até três níveis abaixo da conversa principal. Para impedir que um subagente específico faça isso, deixe Agent fora da lista tools dele.

Posso rodar uma sessão inteira como subagente?

Sim. Inicie o Claude Code com claude --agent seguido do nome do subagente, e a sessão usa o prompt, as ferramentas e o modelo desse subagente.