Como eu confiro o trabalho de um agente

Quando um agente termina uma tarefa, ele entrega um resumo do que fez e dos testes que rodou. Eu uso esse relatório para me orientar, mas não como confirmação. A confirmação vem do diff e de verificações executadas de novo.

Esse cuidado importa porque o erro de um agente raramente vem marcado como erro. O código pode parecer certo, passar nos casos mais óbvios e ainda deixar um detalhe importante para trás.

O erro que parece correto#

Alguns problemas são pequenos o bastante para escapar de uma leitura rápida: um teste cobre o caminho principal e ignora a borda, uma cor literal entra no lugar de um token ou uma string de interface existe apenas em português.

O agente pode ter rodado a suíte correta e ainda não ter criado o teste que expõe o problema. Por isso eu preciso olhar tanto para o resultado quanto para o que ficou fora dele.

Conferir sem herdar o raciocínio#

Eu começo pelo diff, leio cada linha e rodo os gates em uma sessão limpa: pnpm typecheck, pnpm lint, pnpm test e pnpm build. Quando um relatório cita um número ou uma auditoria, eu tento reproduzir o resultado.

Esse já era o papel do segundo terminal. Depois transformei a mesma ideia em três verificadores, cada um responsável por uma classe de erro. Todos começam pelo diff e nenhum altera o código que está revisando.

O papel de cada verificador#

Os três ficam em .claude/agents/ e são read-only:

• code-reviewer roda typecheck, lint, testes e build no Turbopack. Também lê o diff inteiro, confere o escopo e procura violações das convenções de Next 16 e do design system.
• i18n-consistency-checker compara as chaves de messages/pt.json e messages/en.json, verifica se os posts existem nos dois idiomas e procura links internos que não respeitam o locale.
• a11y-checker revisa alt, label-in-name e contraste WCAG 2.1 AA. Em vez de olhar só para a nota do Lighthouse, abre cada auditoria relevante.

Por que separar#

Uma revisão genérica precisa dividir atenção entre correção, escopo, i18n, acessibilidade e estilo. Quando cada verificador recebe uma responsabilidade menor, os critérios ficam mais claros e o relatório fica mais fácil de conferir.

O code-reviewer não precisa calcular contraste. O a11y-checker não precisa decidir se um arquivo pertence ao ticket. Eles podem até encontrar o mesmo problema, mas chegam nele por caminhos diferentes.

Como as instruções ficam em arquivos, eu não preciso lembrar de cada item toda vez que abro uma revisão.

O custo do fluxo#

Três agentes lendo o mesmo diff gastam mais tokens e mais tempo do que um commit direto. Eu aceito esse custo nas mudanças em que um erro pequeno pode passar pelos checks comuns.

Em uma revisão recente, dois defeitos passaram pelo build e pelo Lighthouse. Um comentário em bloco de código tinha contraste de 3.74:1, abaixo dos 4.5:1 exigidos pelo AA. Outro problema quebrava label-in-name porque o texto visível não fazia parte do nome acessível.

A nota agregada continuava verde. Os problemas apareceram quando o a11y-checker abriu os resultados individuais. É para esse tipo de detalhe que mantenho as três revisões antes de considerar a mudança pronta.