Guia de campo do Claude Code em português

Subagentes no Claude Code: um ajudante separado que lê muito e devolve pouco

Pedir ao Claude Code para "usar agentes" virou moda, e a busca por subagentes cresce junto. O recurso é simples de criar e fácil de usar errado: ele não economiza o seu limite de uso, e o subagente não vê a sua conversa. Abaixo, o que ele é, como criar o seu no Windows e quando não usar, só pelo que a doc oficial em português dizia em 18/10/2026 e pelo capítulo 8 do guia (p. 67).

O que é um subagente

A doc oficial abre assim: "Subagentes são assistentes de IA especializados que lidam com tipos específicos de tarefas". O uso típico é a tarefa lateral que encheria a sua conversa de texto que você não vai reler: rodar a suíte de testes, varrer uma pasta de logs, ler a documentação de uma biblioteca. Nas palavras da doc, "o subagente faz esse trabalho em seu próprio contexto e retorna apenas o resumo".

Cada um roda "em sua própria janela de contexto com um prompt de sistema personalizado, acesso a ferramentas específicas e permissões independentes". A sua conversa só vê duas coisas: a mensagem com que o Claude delegou a tarefa e o resumo que voltou (figura 8.1 do guia, p. 68).

Economiza janela, não economiza cota

É o erro mais comum. O subagente faz requisições próprias, e elas contam para os mesmos limites de uso que a sua conversa principal, diz a doc. Vários subagentes em paralelo, cada um gastando os próprios tokens, podem custar mais do que fazer o trabalho na conversa (p. 68). A conta só fecha quando o que ele lê é grande e o que ele devolve é pequeno. Por isso o pedido bom pede o resumo, não o material:

Use um subagente para rodar a suíte de testes e me devolver só
os testes que falharam, com a mensagem de erro de cada um.

O que ele não vê

Fora o fork, o subagente nasce sem a sua conversa. A doc é direta: "Ele não vê seu histórico de conversa, as skills que você já invocou ou os arquivos que Claude já leu." O Claude escreve uma mensagem de delegação e o subagente parte dela. Os arquivos CLAUDE.md chegam a ele; o que você combinou só no chat ("não mexa na pasta vendor/") não chega. Regra que importa vai no pedido ou no CLAUDE.md (p. 69).

A exceção é o fork, "que herda a conversa pai em vez de começar do zero". Na sessão interativa o modo fork vem ligado e o próprio Claude pode abrir um; você abre o seu com /subtask seguido da tarefa (p. 69).

Os que já vêm prontos

O Claude Code traz subagentes integrados, que o Claude chama sozinho:

NomePara quê
Explore"Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código." Nasce sem os CLAUDE.md e sem o git status, para ser rápido
PlanPesquisa o código durante o modo plan, também só leitura
general-purposeTarefas de várias etapas que leem e alteram arquivos, com todas as ferramentas disponíveis a subagentes

Criar o seu: um arquivo Markdown

O jeito mais curto é pedir ao Claude ("crie um subagente revisor em .claude/agents/, só leitura, em Sonnet"), que escreve o arquivo. Escrito à mão, é um .md com cabeçalho YAML. Pela doc, "Apenas name e description são obrigatórios"; o corpo, depois do segundo ---, vira o prompt de sistema dele. Este é o modelo do guia (p. 71), sem os campos effort e color:

---
name: revisor
description: Revisa o código alterado atrás de defeitos de lógica e de
  segurança. Use logo depois de mudanças no código.
tools: Read, Grep, Glob, Bash
model: sonnet
---
Você revisa código. Para cada problema, diga o arquivo e a linha,
explique o defeito em uma frase e mostre a correção mínima.
Não altere arquivos. Se não achar nada, responda "sem achados".

Onde salvar: o lugar decide quem enxerga

PastaVale para
.claude/agents/O projeto atual; vai para o git com a equipe
~/.claude/agents/Todos os seus projetos

No Windows, ~ é a sua pasta de usuário (C:\Users\voce). Quando dois têm o mesmo name, vale o do lugar de maior prioridade, e o de projeto ganha do pessoal (figura 8.3, p. 70). Se a pasta agents não existia quando a sessão abriu, reinicie o Claude Code: "uma sessão em execução não detecta um diretório agents recém-criado". O comando /agents não abre mais um gerenciador: ele "imprime um lembrete para pedir ao Claude ou editar .claude/agents/ e ~/.claude/agents/ diretamente".

Para testar sem criar arquivo, o PowerShell aceita a definição em JSON numa here-string, só para aquela sessão:

claude --agents @'
{
  "revisor": {
    "description": "Revisa código alterado. Use depois de mudanças.",
    "prompt": "Você revisa código. Aponte arquivo, linha e correção.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}
'@

Chamar o seu subagente

  1. Pelo nome, em português: "use o subagente revisor nas mudanças de hoje". O Claude decide se delega.
  2. Por @-menção: digite @ e escolha na lista, ou escreva @agent-revisor. A doc diz que isso "garante que o subagente seja executado para uma tarefa"; o pedido que ele recebe ainda é escrito pelo Claude.
  3. A sessão inteira como ele: claude --agent revisor.

Na sessão interativa, o subagente roda em segundo plano: você continua conversando e o resultado chega numa notificação (p. 74).

Três armadilhas

Quando não usar

A doc manda ficar na conversa principal quando a tarefa pede ida e volta com você, quando planejar, implementar e testar dividem muito contexto, ou quando a mudança é rápida e direcionada. E use subagente quando "A tarefa produz saída detalhada que você não precisa em seu contexto principal". Instrução que se repete é skill; o mesmo passo em dezenas de arquivos é workflow. O guia resume a escolha numa figura de quatro perguntas (figura 8.7, p. 78).

Fora do livro: code.claude.com/docs/pt/sub-agents, lida em 18/10/2026.

Leia também