AGENTS.md como política única de code review — 47 PRs depois, sistema virou juiz único

Há três meses publiquei aqui um post medindo o fracasso do meu AGENTS.md: escrevi “escreva testes antes do PR” e só 12% dos PRs seguiram (o post do 12% explica a medição). A conclusão daquele post foi simples: AGENTS.md sozinho fica no nível do pedido, sem chegar a virar sistema. Adicionei hook de pre-commit e a conformidade daquela regra subiu para 100%.

Isso resolveu uma regra. Sobraram outras dezenas espalhadas em Slack, em comentários de PR e na minha cabeça. Toda code review virava um debate meio subjetivo: “essa nomenclatura combina com o padrão do projeto?” “essa camada de abstração é exagero?” “esse any cabe aqui ou não?”. Sem lugar único onde a resposta estivesse escrita, cada revisor puxava para o próprio gosto.

Nas últimas 4 semanas eu virei o parafuso na direção oposta: reformulei o AGENTS.md inteiro como política única de code review, plugado a hooks, CodeRabbit e revisão humana. Medi 47 PRs em 30 dias. O sistema virou juiz único do merge. E a mudança mais interessante nem foi a taxa de conformidade.

O que mudou entre “AGENTS.md como pedido” e “AGENTS.md como política única”

No post anterior, o AGENTS.md era uma lista de desejos. Regras soltas, na segunda pessoa (“por favor escreva testes”), sem referência de código, sem quem executa. Nesta versão o arquivo tem estrutura fixa:

• Padrões a multiplicar (com caminho apontando para código de referência real dentro do repositório, do tipo que já rodou em produção)
• Padrões a reduzir (com “por que” concreto e “onde aparece” concreto)
• Critério de aprovação (checklist objetivo que hook, CodeRabbit e humano usam o mesmo texto)
• Rótulos de comentário (Conventional Comments: issue:, suggestion:, nitpick:, question:, praise:, sem inventar rótulos novos por PR)

O ponto que puxou tudo: o .coderabbit.yaml agora começa com Consulte a seção Code Direction do AGENTS.md. O hook de pre-commit referencia o mesmo arquivo no output de erro. E na revisão humana eu literalmente colo o link do AGENTS.md#padroes-a-reduzir no comentário em vez de reescrever a regra do zero.

Antes o AGENTS.md era um dos vários lugares onde uma regra podia ficar. Agora ele é o único. Hook, IA e humano só executam o que está lá. Se uma regra não cabe no AGENTS.md, ela não existe.

47 PRs em 30 dias: o que a medição mostrou

Peguei os 47 PRs que passaram pelo novo fluxo entre 2026-07-10 e 2026-08-08. Todos código de produção, nenhum era docs-only ou dependabot.

Camada 1 (hook + CI): 47/47 passaram sem exceção manual. Os 3 casos que precisaram bypass usaram a tag hotfix-no-test explicitamente prevista no AGENTS.md: a válvula de escape virou parte oficial do sistema, prevista de propósito.

Camada 2 (CodeRabbit lendo o AGENTS.md): dos 47 PRs, 31 receberam pelo menos um comentário automatizado. Média de 2.4 comentários por PR. Antes do redesenho, o CodeRabbit costumava sugerir any → unknown, sugestão de nomenclatura genérica, “considere extrair função”… o padrão universal de linter de IA. Agora ele cita explicitamente AGENTS.md § Padrões a reduzir em 78% dos comentários, e a taxa de “comentário útil, vou aplicar” que eu marco subiu de estimados 30% para medidos 61%.

Camada 3 (eu, revisão humana): dos 47 PRs, eu abri em média 1.2 comentário substantivo por PR. Antes ficava em torno de 3-4. A diferença veio inteira das camadas 1 e 2 já terem resolvido o que era mecânico ou padrão conhecido. Minha revisão sobrou para o que só humano faz: alinhamento de direção, questionar se a funcionalidade é a certa, comparar com decisões arquiteturais antigas.

Tempo médio até merge caiu de ~26h para 9h. E não foi porque a IA passou a aprovar coisa (ela nunca aprova nada aqui). Caiu porque ninguém mais discute regra. A regra já está escrita, o hook já rodou, o CodeRabbit já apontou. O que sobra é decisão de design, e essa costuma ser rápida quando a pessoa proponente já sabe qual é a régua.

O momento em que o AGENTS.md virou “juiz único” na prática

Teve um PR específico que fechou a virada mental para mim. Um contribuidor abriu um refactor grande, movendo lógica de um controller para um service. O CodeRabbit apontou 4 pontos citando AGENTS.md § Padrões a multiplicar. Eu ia entrar com 2 comentários próprios, mas parei antes: os 2 pontos que eu ia levantar já estavam escritos no AGENTS.md. Se eu fosse comentar no PR, eu ia estar reescrevendo o próprio arquivo.

O que eu fiz foi colar Ver AGENTS.md#padroes-a-reduzir bullet 3 como comentário único. O contribuidor voltou 20 minutos depois, ajustou, e o PR foi mergeado. Nenhum debate. Nenhum “mas na minha opinião…”. A regra falou pelos dois lados.

É esse comportamento que eu chamo de “juiz único”: o arquivo virou a fonte de decisão que ninguém contesta no meio da review. Contestar dentro do PR seria contestar o arquivo em outro momento, com um PR próprio de mudança no AGENTS.md. E aí a discussão fica onde ela pertence: separada da pressa de mergear a funcionalidade de hoje.

Onde o sistema falhou (ou quase falhou)

Não vou vender que 47 PRs foram perfeitos. Três falhas concretas nesses 30 dias:

1. Uma regra nova entrou por Slack e não no AGENTS.md. Um colega do time mandou “de agora em diante vamos usar zod em vez de yup em validações”. Combinamos, começamos a usar. Duas semanas depois um PR novo apareceu com yup, o CodeRabbit não sinalizou (não estava no AGENTS.md), eu comentei manualmente, o contribuidor ficou irritado por ser pego numa regra não escrita. Culpa minha por não ter feito PR de atualização no AGENTS.md no dia da decisão do Slack. Ajustei o processo: regra sem PR de AGENTS.md não existe. Se a regra é importante o bastante para bloquear PR alheio, é importante o bastante para virar diff no AGENTS.md primeiro.

2. CodeRabbit citou o AGENTS.md em contexto errado. Uma vez ele aplicou uma regra de “prefira early return” num arquivo de teste, onde a estrutura arrow-heavy fazia mais sentido. Resolvi criando exceções explícitas no AGENTS.md: Aplica-se a: código de produção. Não se aplica a: arquivos em tests/**. Custou 5 minutos, poupou 3 PRs de discussão futura.

3. Um hook falhou silenciosamente por 4 dias. O bug era meu no shell script; o sistema em si estava ok. Mas mostrou que quando você delega a “juiz único” para uma pipeline automatizada, precisa de alarme quando o juiz sai de campo. Adicionei um teste sintético que roda 1x por dia contra um commit conhecidamente ruim; se passar, algo quebrou no hook.

Vale a pena para você?

Se você mantém um repositório onde 2+ pessoas fazem review, e você já tem hook de format/lint funcionando, o próximo movimento marginal é esse: colar CodeRabbit (ou similar) no AGENTS.md como fonte única de padrões, e disciplinar você mesmo a nunca mais mandar comentário de review que já está escrito no arquivo.

O ganho principal não passa por “IA revisa por mim” (a IA continua errando). O ganho é que o custo mental de review humana cai quando você para de re-explicar as mesmas regras a cada PR. E o custo psicológico da pessoa cujo PR está sendo revisado cai junto: a regra fala pela voz do arquivo, com a personalidade do revisor tirada do meio.

Que era o problema real, no fim. Code review sem AGENTS.md como juiz único vira debate de gosto, e debate de gosto entre engenheiros custa muito mais que qualquer suíte de IA.

Notes

O redesenho do AGENTS.md como política única (estrutura completa, template com Padrões a multiplicar / reduzir, integração com CodeRabbit e hooks) está detalhado no capítulo 6 do livro Revisão de Código com Harness Engineering, com os arquivos .coderabbit.yaml e hook scripts que uso na produção.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews