O subagente revisor

O autor está predisposto a defender o que escreveu

Suponha que o /work acabou de fechar uma fatia. Pode ser schema, validação, route e form num produto que cobra, ou um passo de pipeline (parser de um CSV oficial, ETL, uma página de dados públicos) num produto de transparência. O Claude escreveu cada parte e, ao longo da sessão, foi acumulando as razões de cada escolha: "usei any aqui porque o tipo certo dava trabalho", "deixei sem o caso de borda porque era raro". Essas justificativas ficam na janela de contexto. Quando você pergunta "está tudo certo?", o mesmo agente que produziu o código responde com a memória de por que cada atalho pareceu razoável na hora, e tende a defender o que escreveu.

A saída é separar quem escreve de quem revisa. Um roda numa janela de contexto própria: ele recebe o diff e o critério de aceite, mas não recebe a conversa onde o código nasceu. Ele avalia o resultado sem as justificativas que o tornaram aceitável pro autor.

Por que o contexto limpo muda a revisão

A documentação do Claude Code descreve esse passo como : antes de tratar uma tarefa como pronta, um subagente revisa o diff num contexto novo e reporta lacunas.

"A reviewer running in a fresh subagent context sees only the diff and the criteria you give it, not the reasoning that produced the change, so it evaluates the result on its own terms."

(Em pt-BR: um revisor que roda num contexto de subagente novo vê só o diff e os critérios que você passou, não o raciocínio que produziu a mudança, então avalia o resultado pelos próprios termos.)

Fonte: Claude Code best practices — Add an adversarial review step.

O que é um subagente, mecanicamente

Não é mágica nem um modelo diferente. É uma janela de contexto separada com um system prompt próprio e um conjunto de ferramentas restrito. A doc oficial define:

Três propriedades fazem ele servir pra revisão:

Contexto próprio: não herda a conversa do /work. É justamente disso que a lição trata.
Ferramentas restritas: você dá só Read, Grep, Glob. Um revisor não precisa editar nem rodar comando; ele lê e reporta.
System prompt próprio: você dita o foco. Aqui é onde você escopa pra correção, não pra estilo.

Passo 1 — Crie o revisor em `.claude/agents/code-reviewer.md`

O subagente é um arquivo Markdown com frontmatter. Cole no Claude:

prompt · text

Crie o arquivo `.claude/agents/code-reviewer.md` com este conteúdo exato (frontmatter + system prompt em pt-BR). Mostre o diff antes de criar.

---
name: code-reviewer
description: Revisa o diff de uma fatia recém-implementada em contexto limpo. Reporta só gaps de correção e requisitos não cumpridos — não estilo. Use logo depois que o /work fecha uma fatia, antes do commit.
tools: Read, Grep, Glob
model: opus
---

Você é um revisor de correção. Recebe um diff e o critério de aceite da fatia. Você NÃO escreveu este código e não tem acesso ao raciocínio de quem escreveu.

Sua única função é encontrar problemas REAIS de:
- **Correção**: o código faz o que diz fazer? Tem bug, caso de borda não tratado, ou um destes erros clássicos:
- valor monetário guardado em float (number com vírgula) — erro porque float arredonda centavos e o total não fecha; dinheiro vai em inteiro de centavos ou decimal.
- validação ausente na borda — dado externo (request, upload, CSV) entra sem ser checado.
- integridade dos dados em relação à fonte — parser que perde linha silenciosamente, valor que não bate com o documento original, campo truncado. Crítico em pipeline de dados públicos.
- referência quebrada entre tabelas (FK quebrada) — um registro aponta pra outro que não existe.
- **Requisito não cumprido**: o critério de aceite pedia X e o diff não entrega X?

NÃO reporte:
- Preferência de estilo, nomenclatura, formatação.
- Refator que não corrige bug ("isso poderia ser mais limpo").
- Camada de abstração ou defensividade extra "por garantia".

Se não houver problema real de correção ou requisito, responda exatamente: "nenhum problema". Não invente lacuna pra parecer útil.

Para cada problema real, dê: arquivo + linha, o que está errado, e por que afeta correção ou requisito.

Cada erro clássico no prompt vem com o motivo embutido ("float arredonda centavos e o total não fecha", "parser que perde linha silenciosamente"), e isso é de propósito.

Os campos do frontmatter, um a um:

tools: Read, Grep, Glob: read-only. O revisor não edita, não roda comando, não comita. A restrição é a garantia: ele não pode "consertar" enquanto revisa, só apontar.
model: opus: a revisão é o último filtro antes do commit, então é onde menos compensa economizar. O tipo de achado que um modelo mais forte tende a pegar e um mais barato deixa passar é o sutil: o >= que devia ser > numa fronteira, o centavo que some no arredondamento, a linha do CSV que o parser descarta sem erro. Se custo por revisão for um problema no seu caso, é um trade-off legítimo testar sonnet, mas comece no opus e baixe só se o gasto pesar.
description em pt-BR: é o que o Claude lê pra decidir quando delegar. Diz claramente quando (depois do /work, antes do commit) e o quê (correção, não estilo).

Por que o system prompt PRECISA dizer 'só correção'

Um revisor instruído a "achar problemas" quase sempre acha, mesmo quando o código está são, porque foi isso que você pediu. A própria doc avisa:

"A reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. [...] Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional."

(Em pt-BR: um revisor instruído a achar lacunas geralmente acha algumas, mesmo quando o trabalho está sólido, porque foi o que pediram. Diga ao revisor pra sinalizar só lacunas que afetam correção ou os requisitos, e trate o resto como opcional.)

Sem essa cláusula, você cai em over-engineering: o revisor inventa camadas de abstração, código defensivo e teste pra caso que não acontece, e você gasta a tarde perseguindo cada um.

Fonte: Claude Code best practices — Add an adversarial review step.

Passo 2 — Invoque o revisor logo depois do `/work`

A janela do /work fechou a fatia. Antes do commit, peça a revisão explicitamente.

Aqui tem um detalhe que parece contradição mas não é: o subagente roda em e não vê a sua conversa. Então como ele sabe qual é "o diff que acabamos de fechar"? Quem resolve isso é o agente principal (o seu chat), não o subagente. O principal roda git diff HEAD pra capturar as mudanças não comitadas, lê o arquivo de plano, e entrega os dois ao subagente como material. O subagente recebe diff + critério já prontos; o que ele não recebe é o histórico de por que o código ficou daquele jeito.

O arquivo de plano é o que você gerou no Módulo 2 (a lição do /plan); ele fica na pasta plans/ do seu projeto. Se não lembrar o nome exato, rode ls plans/ ou peça "liste os arquivos em plans/" antes de colar o prompt, e troque o placeholder abaixo pelo nome real.

prompt · text

Use o subagente code-reviewer pra revisar a fatia que acabamos de fechar. Rode `git diff HEAD` pra pegar o diff não comitado e passe pro subagente junto com o critério de aceite do plano em `plans/<arquivo-do-plano>.md` (troque pelo nome do seu arquivo).

Verifique:
- Cada requisito do critério de aceite está implementado.
- Nada fora do escopo da fatia mudou.
- Os casos de borda que o critério lista têm tratamento.

Reporte só gaps de correção e requisito. Se não houver, diga "nenhum problema".

Porque o revisor roda como subagente, ele devolve as lacunas direto pro seu chat: você conserta e re-revisa sem copiar achado de uma janela pra outra.

Passo 3 — Trate o relatório como triagem, não como ordem

O revisor reporta. Você decide. Para cada item:

Gap de correção (bug, validação ausente, float em dinheiro) → conserta. Esse é o achado que vale o passo inteiro.
Requisito não cumprido → conserta ou registra que saiu de escopo de propósito.
Qualquer coisa que cheire a estilo / "poderia ser mais limpo" → ignora, mesmo que o revisor tenha escapado da cláusula e reportado. Você é o filtro final.

Se a resposta foi "nenhum problema", ótimo: segue pro commit. Um revisor que pode dizer "nenhum problema" é confiável; um que sempre acha algo virou gerador de retrabalho.

O Starter já traz esse revisor

O Starter Repo do Builder OS já vem com .claude/agents/code-reviewer.md configurado exatamente assim: read-only, model: opus, escopado a correção. Se você clonou o Starter, ele está lá; abra e compare com o que você acabou de escrever. O passo 1 desta lição é pra você entender cada campo, não pra reinventar o arquivo. E esse mesmo arquivo serve de molde quando você for compor seus próprios subagentes mais pra frente no curso.

Build Diary — o critério de aceite vira o que o revisor checa

No Módulo 2 você escreveu o plano da fatia com critério de aceite explícito, o que conta como "pronto". Lá aquilo parecia papelada. Aqui ele paga: o critério de aceite é exatamente o documento que o revisor de contexto limpo recebe pra checar contra. Sem critério escrito, o revisor não tem régua: cai no estilo, justamente o que você não quer. Com critério escrito, a pergunta dele é objetiva: "o diff entrega cada linha do critério?". Plano bom no M2 é o que torna a revisão do M3 possível.

Takeaways

O agente que escreveu o código carrega as justificativas dele na janela e está predisposto a defendê-lo. Um subagente em contexto limpo vê só o diff + o critério, sem essas justificativas.
Subagente = janela de contexto própria + system prompt próprio + ferramentas restritas. Pra revisão: tools: Read, Grep, Glob (read-only), model: opus.
Escope o revisor a correção e requisito não cumprido. Um revisor mandado "achar problema" inventa problema, e isso vira over-engineering.
Exija "nenhum problema" como resposta válida. Invoque logo depois do /work, antes do commit.
O Starter já traz esse code-reviewer.md pronto: o passo 1 é pra entender cada campo, e o arquivo vira molde quando você for compor seus próprios subagentes mais pra frente.

Você terminou quando

Quatro coisas:

.claude/agents/code-reviewer.md existe, com tools: Read, Grep, Glob, model: opus, e descrição em pt-BR (ou você confirmou o que já vem no Starter).
O system prompt escopa o revisor a correção e requisito não cumprido, e permite "nenhum problema".
Você invocou o revisor sobre o diff de uma fatia fechada, contra o critério de aceite do plano.
Você tratou o relatório como triagem: consertou os gaps de correção, ignorou o que era estilo.

Auto-checagem: você consegue responder?