Como criar um subagente revisor de código no Claude Code, passo a passo

Um subagente no Claude Code é um assistente especializado que roda em contexto isolado, com seu próprio prompt, ferramentas permitidas e modelo. Neste tutorial você vai criar um revisor de código que só lê arquivos, sem poder alterá-los. Tudo aqui segue a documentação oficial de subagentes da Anthropic.

O que você vai construir

Um arquivo Markdown chamado code-reviewer.md que define um subagente. O Claude Code vai usá-lo quando o pedido combinar com a descrição, por exemplo "revise as mudanças que fiz". Como o subagente terá apenas ferramentas de leitura, ele não consegue editar nada por engano.

Pré-requisitos

• Claude Code instalado.
• Um projeto de código aberto no terminal, onde você possa criar uma pasta .claude/agents.

Como funciona um arquivo de subagente

Segundo a documentação, um subagente é um arquivo Markdown com cabeçalho YAML. O corpo do arquivo vira o prompt de sistema. O subagente recebe esse prompt e informações básicas do ambiente, mas não o prompt de sistema completo do Claude Code.

Só dois campos são obrigatórios: name e description. Os campos opcionais mais usados são:

Campo	Para que serve
tools	Ferramentas permitidas, em lista separada por vírgula ou em lista YAML. Se omitido, herda todas.
disallowedTools	Ferramentas negadas.
model	sonnet, opus, haiku, fable, um ID completo de modelo ou inherit.
permissionMode	Modo de permissão do subagente.
maxTurns	Máximo de turnos antes de o subagente parar.
effort	low, medium, high, xhigh ou max.
isolation	worktree para rodar em um worktree temporário do git.

A documentação alerta que campos com várias palavras usam camelCase e precisam estar escritos exatamente assim, porque campos desconhecidos são ignorados sem aviso de erro.

Passo 1: escolher onde salvar

O local define o alcance do subagente:

Local	Alcance
.claude/agents/	Só o projeto atual
~/.claude/agents/	Todos os seus projetos

Se dois subagentes tiverem o mesmo nome, vence o de local com prioridade maior. A identidade vem apenas do campo name, e não do nome do arquivo ou da subpasta. Para um revisor específico do projeto, use .claude/agents/.

mkdir -p .claude/agents

Passo 2: escrever o subagente

Crie .claude/agents/code-reviewer.md com o exemplo da documentação:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Os pontos importantes: description diz ao Claude quando delegar a tarefa; tools: Read, Glob, Grep limita o subagente a ler e buscar arquivos; model: sonnet define o modelo usado por ele. O texto abaixo do cabeçalho é a instrução que o subagente recebe. Você pode escrevê-lo em português se preferir respostas nesse idioma.

Passo 3: deixar o Claude Code carregar o arquivo

O Claude Code monitora as pastas de agentes, então as edições passam a valer em poucos segundos. A documentação faz uma ressalva: se você criou a pasta agents durante a sessão, é preciso reiniciar o Claude Code.

Dá para pedir ao próprio Claude que escreva o arquivo, descrevendo o subagente e o local, e também é possível definir subagentes só para uma sessão pela linha de comando com claude --agents '<JSON>'.

Passo 4: testar

Abra o Claude Code no projeto e peça algo que combine com a descrição:

Use o subagente code-reviewer para revisar os arquivos que mudei hoje.

O resultado esperado é que o Claude delegue a tarefa ao revisor, que lê os arquivos e devolve um relatório com sugestões. Como ele só tem Read, Glob e Grep, não haverá nenhuma alteração nos arquivos.

Passo 5: ajustar o comportamento

Algumas variações possíveis com os campos da documentação:

• Para um revisor mais profundo, adicione effort: high.
• Para limitar o custo, defina maxTurns com um número baixo.
• Para impedir qualquer escrita de forma explícita, use disallowedTools: Edit, Write.

O changelog do Claude Code também registra, na versão 2.1.295, que subagentes carregam no máximo 32 skills pré-instaladas, informação útil se você pretende anexar muitas skills ao subagente.

Erros comuns

• O subagente não aparece: o arquivo é ignorado sem aviso se faltar o name, se o --- de abertura não estiver na primeira linha ou se o YAML não for válido. Rode claude --debug para ver o motivo no log.
• Campo ignorado: conferir se escreveu disallowedTools e maxTurns exatamente assim, em camelCase.
• Ferramentas demais: se omitir tools, o subagente herda todas as ferramentas disponíveis, inclusive as de escrita.
• Nome duplicado: dois arquivos com o mesmo name entram em conflito, e vence o de maior prioridade.
• Mudança que não surte efeito: reinicie o Claude Code se a pasta agents foi criada depois de abrir a sessão.

Resultado

Você terá um revisor que o Claude aciona sozinho quando o pedido se encaixa na descrição, que só consegue ler o código e que fica versionado no repositório. Se commitar a pasta .claude/agents, o restante da equipe recebe o mesmo revisor.