Subagentes do Claude Code: como criar e usar

Os subagentes do Claude Code são ajudantes para os quais a sessão principal do Claude Code entrega uma única tarefa. Cada um roda na própria janela de contexto, com seu próprio system prompt, lista de ferramentas e modelo, e só a resposta final volta para a conversa principal. Você define um subagente como um arquivo Markdown em .claude/agents/, e o Claude o usa automaticamente quando a tarefa combina com a descrição dele, ou quando você pede por ele pelo nome.

Este post explica como os subagentes funcionam, o formato do arquivo, os campos tools e model, como chamá-los e a fronteira entre um subagente e um agente separado rodando ao lado do primeiro. Os fatos vêm da documentação oficial de subagentes. Para a versão em um parágrafo, veja o verbete de subagente no glossário.

Como os subagentes funcionam

Quando o Claude decide delegar, ele chama a ferramenta Agent (chamada Task antes da versão 2.1.63) com um briefing curto. O subagente começa com um contexto novo. Ele recebe o próprio system prompt, a mensagem de delegação, o seu CLAUDE.md, o git status e quaisquer skills que você pré-carregou para ele. Ele não vê o histórico da conversa principal.

Em seguida, ele trabalha na tarefa com as ferramentas permitidas e devolve um único resultado. Tudo o que ele leu pelo caminho, como dezenas de arquivos, saídas longas de grep ou logs de testes, fica no contexto dele. Esse é o principal motivo para usar subagentes: a conversa principal recebe um resumo, não o ruído.

Alguns limites que vale conhecer:

• Subagentes podem iniciar seus próprios subagentes, até três níveis de profundidade por padrão.
• Até 20 podem rodar ao mesmo tempo por padrão.
• As solicitações deles contam para os mesmos limites de uso da sessão principal.
• Um subagente pode rodar em primeiro plano, enquanto o agente principal espera, ou em segundo plano enquanto o agente principal segue trabalhando.

Subagentes embutidos

O Claude Code vem com alguns subagentes que você pode usar sem escrever nada:

O Explore é o que você mais vai ver. Quando o Claude precisa descobrir onde algo está definido ou como uma feature funciona entre vários arquivos, ele costuma passar isso para o Explore, para que os despejos de arquivos não caiam no seu contexto principal.

Onde ficam os arquivos de subagentes

Subagentes são arquivos Markdown com frontmatter YAML. O Claude Code os carrega de vários lugares e, quando dois têm o mesmo nome, vence o que está mais acima nesta lista:

Os subagentes de projeto em .claude/agents/ são os que você deve commitar, para que a equipe inteira compartilhe o mesmo revisor ou executor de testes.

O formato do arquivo de subagente

Só name e description são obrigatórios. O corpo depois do frontmatter é o system prompt do subagente.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.

A description importa mais do que parece. É o que o Claude lê quando decide se vai delegar, então diga o que o subagente faz e quando usá-lo. Frases como “use after writing code” (use depois de escrever código) ajudam o Claude a escolhê-lo por conta própria.

O campo tools

tools é uma lista de permissões. Com tools: Read, Grep, Glob, Bash, o revisor acima consegue ler e rodar comandos, mas não consegue editar arquivos. Se você deixar tools de fora, o subagente herda todas as ferramentas da sessão principal, incluindo as ferramentas MCP. Também existe disallowedTools, para quando é mais fácil dizer o que remover do que o que manter.

Mantenha a lista tão curta quanto o trabalho permitir. Um revisor não precisa de Edit. Um pesquisador não precisa de Bash. Menos ferramentas significa menos surpresas e uma tarefa mais clara.

O campo model

model aceita um alias (sonnet, opus, haiku), um ID de modelo completo ou inherit para usar o modelo da sessão principal. Quando o subagente é chamado, o Claude Code escolhe o modelo nesta ordem: um modelo passado naquela chamada, depois o campo model do arquivo, depois a variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL e, por fim, o modelo da sessão principal.

É aqui que os subagentes podem economizar dinheiro de verdade. Buscas amplas em arquivos e leitura de logs raramente precisam do modelo mais forte. Coloque-as no Haiku e mantenha a sessão principal no modelo maior para as decisões. O post sobre uso de tokens do Claude Code traz mais formas de cortar gastos.

Outros campos úteis

Como chamar um subagente

Há três formas:

1. Deixe o Claude decidir. Se o pedido combina com a descrição de um subagente, o Claude delega por conta própria.
2. Peça pelo nome. “Use the code-reviewer subagent to check my last commit.” (use o subagente code-reviewer para checar meu último commit). Você também pode mencioná-lo com @ pelo menu.
3. Rode uma sessão inteira como ele. claude --agent code-reviewer inicia uma sessão que usa o prompt, as ferramentas e o modelo desse subagente.

Para uma sessão avulsa, você pode passar subagentes como JSON sem criar arquivos:

claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Para impedir o Claude de usar um subagente específico, adicione-o à lista de negação nas suas permissões, por exemplo Agent(Explore).

Subagentes vs agentes paralelos separados

Subagentes e agentes paralelos dividem o trabalho, mas resolvem problemas diferentes.

Use um subagente quando o agente principal precisa de uma resposta para continuar: “encontre todos os chamadores desta função”, “revise este diff”, “resuma estes logs”. O trabalho é curto, o resultado é o que importa e você não precisa acompanhar.

Use agentes separados quando cada parte é um trabalho de verdade por si só: uma feature, uma migração, uma suíte de testes. Você quer ver o que cada um está fazendo, responder às perguntas dele e revisar as mudanças como uma branch. Esse é o setup descrito em agentes de código em paralelo e em rodar vários agentes do Claude Code, com cada agente na sua própria git worktree.

Os dois combinam bem. Um agente separado ainda pode usar subagentes para as próprias buscas e revisões. Um bom padrão é agentes separados para o trabalho que você daria a uma pessoa, e subagentes para as tarefinhas que esses agentes executam. Para equipes maiores, o post sobre equipes de agentes de IA cobre papéis e passagens de tarefa, e o verbete de orquestração multiagente cobre a ideia geral.

O Claude Code também tem um recurso separado chamado agent teams, em que várias sessões do Claude trabalham juntas. Isso não é o mesmo que subagentes e fica fora deste post.

Dicas para subagentes que funcionam

• Uma tarefa por subagente. “Revisor” e “executor de testes” funcionam melhor que “ajudante”.
• Escreva a descrição para o Claude. Diga quando usá-lo, não só o que ele é.
• Limite as ferramentas. Subagentes somente leitura para pesquisa e revisão, ferramentas de edição só onde for preciso.
• Escolha o modelo de propósito. Haiku para busca e resumos, um modelo mais forte para design e correções difíceis.
• Peça um relatório curto. O resultado vai para o contexto principal, então diga ao subagente para devolver conclusões, não despejos de arquivos.
• Versione os subagentes do projeto. .claude/agents/ no git significa que todo mundo recebe os mesmos ajudantes.

Como o AgentVera mostra os subagentes

O AgentVera é um app desktop para rodar vários agentes de código, como Claude Code, Codex e outros, lado a lado. Ele lida com subagentes de duas formas.

Você consegue vê-los. No painel de um agente Claude Code, o botão “Subagents” abre uma visão ao vivo dos subagentes que esse agente iniciou e do que eles estão fazendo agora. Cada um mostra seu status (Running, Done, Error, Stopped), se roda “in background”, a “Assigned task” que recebeu e seu “Report”. Enquanto alguns estão trabalhando, aparece uma linha “{count} subagents running — show” para você não perdê-los de vista. O tour do projeto e mapa de código também tem uma linha do tempo de subagentes com tipo, status, número de ferramentas e duração. Ambos leem as transcrições locais e, por enquanto, são para agentes Claude Code.

Um Explore mais barato. Em Settings → “Token saving”, a opção “Explorer subagent” dá aos agentes Claude um explorador somente leitura para buscas amplas. A varredura de arquivos roda em um modelo mais barato, o Haiku por padrão, e só o resultado volta para a conversa principal. Se você já tem seu próprio arquivo de subagente Explore, o AgentVera mantém o seu. Ela fica ao lado das smart tools na mesma seção.

Agentes separados quando o trabalho é maior. A visão de equipe mostra até 24 agentes ao mesmo tempo. A equipe paralela (planos Pro e Team) divide um objetivo em partes, roda cada uma na própria worktree e as junta em um único PR. As mensagens entre agentes permitem que eles façam perguntas uns aos outros, até entre CLIs diferentes, e a coordenação de agentes avisa quando dois agentes mexem no mesmo arquivo. Isso dá a você o lado de agentes separados da tabela acima, com os subagentes ainda disponíveis dentro de cada agente Claude.

Conclusão

Subagentes são a ferramenta certa quando o agente principal precisa de uma resposta e você não precisa acompanhar o trabalho: busca, revisão, pesquisa. Escreva um arquivo Markdown com uma descrição clara, uma lista curta de ferramentas e um modelo escolhido de propósito. Quando o trabalho for grande o bastante para merecer uma branch própria e a sua atenção, rode um agente separado.

Leia mais:

• Subagente (glossário)
• Agentes de código em paralelo
• Tour do projeto e mapa de código
• Equipe paralela
• Agente Claude Code

Para experimentar o AgentVera, comece pela página inicial.