Escrevi 'testes antes do PR' no AGENTS.md por 3 Meses. Só 12% Seguiram.

Coloquei a linha “escreva testes antes de abrir o PR” no AGENTS.md do meu projeto principal e deixei lá por três meses. Ao final, medi. Doze por cento dos PRs seguiram a regra. Doze. Se eu fosse um professor de escola, teria reprovado a turma inteira, incluindo o professor.

O detalhe embaraçoso é que eu fui um dos agentes que ignoraram a regra. Mesmo tendo escrito eu mesmo. Mesmo lendo o arquivo toda vez que abro o Claude Code. A regra estava lá, eu concordava com ela, e eu era o primeiro a passar direto.

Como cheguei nos 12%

O experimento foi simples. Peguei 3 meses de PRs (abril, maio, junho de 2026) num monorepo em que eu trabalho quase todo dia com Claude Code. Total: 92 PRs. Filtrei os que tocavam código de produção (não docs, não infra). Sobraram 76.

Depois classifiquei cada um por três critérios:

• Havia teste novo no diff?
• O teste foi commitado antes do código sob teste (histórico do commit)?
• Se não havia teste, o PR mencionou “por que não” no corpo?

Nove PRs de 76 passaram nos dois primeiros critérios. Doze por cento. Se eu somasse os PRs que ao menos justificavam a ausência de teste, chegaria a 21%. Ainda assim, quatro em cada cinco PRs simplesmente ignoraram a única linha que eu tinha escrito com todas as letras.

E o AGENTS.md estava aberto no editor. Todo dia.

O erro conceitual: confundir pedido com sistema

Fiquei mexendo nessa frustração por umas duas semanas até cair a ficha. AGENTS.md é um pedido. Um pre-commit hook é um sistema. Eu tinha juntado três meses de pedidos sem nenhum sistema por trás e depois reclamado que os pedidos não estavam sendo cumpridos.

James Clear cansa de repetir isso em contexto de hábito pessoal: “você não sobe ao nível dos seus objetivos, você desce ao nível dos seus sistemas”. Vale igual para engenharia. Um AGENTS.md sem execução automática ao redor é uma placa “por favor não pise na grama” no meio de um parque sem cerca. Todo mundo lê, ninguém cumpre, e a grama morre do mesmo jeito.

E o pior: o AGENTS.md funciona para agentes de IA em contextos onde a regra é aplicada dentro do turno atual. Se eu escrever “sempre rode pytest antes de commitar” e o agente estiver no fluxo de commit, ele lê e roda. Mas se a regra depende de disciplina entre turnos, como “escreva teste antes do código de produção”, o agente esquece na próxima sessão, e eu esqueço na segunda-feira depois do feriado, e o PR entra sem teste.

O que substituí

Não removi o AGENTS.md. Só parei de tratá-lo como se ele fosse cerca. Coloquei três camadas ao redor dele:

Um pre-commit hook que roda pytest no diff. Não roda a suíte inteira (isso mataria a produtividade), roda só nos arquivos tocados. Se tem código novo em foo/bar.py sem teste correspondente em tests/foo/test_bar.py, o commit falha com uma mensagem clara: “adicione ou justifique a ausência do teste”. Custo de implementação: 40 linhas de Python. Custo mensal: 0.

Uma checagem no CI que bloqueia o merge se a cobertura no diff caiu. Ferramenta: diff-cover. Tempo de configuração no GitHub Actions: uma tarde. Isso pega o caso “escrevi teste, mas testa outra coisa”.

Uma exceção explícita no AGENTS.md. Deixei a regra original, e embaixo escrevi: “se o hook estiver bloqueando um bugfix urgente em produção, rode git commit --no-verify e abra um PR com a tag hotfix-no-test, que vou revisar manualmente”. Ou seja, o sistema tem uma válvula de escape explícita. Sem válvula, o pessoal acaba desligando o hook inteiro na primeira sexta-feira 18h.

Os números depois de trocar o pedido pelo sistema

Rodei mais 4 semanas com o hook ativo. 31 PRs. Conformidade: 100%. Zero “esqueci de escrever o teste”. Duas ocorrências da tag hotfix-no-test, ambas revisadas por mim no dia seguinte, ambas com teste adicionado num PR de acompanhamento em menos de 48h.

Não tem milagre nenhum. Só que agora o sistema executa a regra em vez de pedir por ela. A distância entre 12% e 100% mora na camada onde a regra é aplicada: a equipe é a mesma, o comprometimento é o mesmo, só a infraestrutura mudou.

Um contra-argumento que já ouvi

“Mas hooks são chatos. A equipe reclama, desabilita, contorna.”

Concordo em partes. Hooks mal calibrados são chatos. Um hook que roda a suíte inteira em 4 minutos vai ser desabilitado até quinta-feira. Um hook que roda só o diff em 8 segundos, com mensagem clara e válvula de escape, ninguém desabilita, porque ele economiza mais tempo do que consome. O truque está em calibrar o hook para o custo de execução ficar menor que o custo de errar. A pergunta “ter hook ou não ter” é a errada.

Falando de custos, no meu contexto brasileiro isso é literal. Um deploy de bugfix num sábado à noite envolvendo três engenheiros no plantão custa fácil R$ 1.500 em hora extra. Um hook de 40 linhas que evita esse deploy uma vez por mês já paga o ano inteiro de tempo que ele consome nos commits do dia a dia.

O que aprendi para o próximo AGENTS.md

Uma regra em AGENTS.md sem contraparte executável é decorativa. Tudo bem escrever regras aspiracionais lá: comunica intenção, ajuda na integração inicial de gente nova, dá contexto para o agente de IA no turno atual. O erro é assumir que elas vão ser cumpridas sem cerca.

Meu novo critério antes de adicionar qualquer linha nova ao AGENTS.md:

• Essa regra pode virar hook, CI check ou template? Se sim, faço isso primeiro e escrevo a linha depois, como documentação do sistema.
• Se não pode virar sistema, a regra depende de julgamento humano — e nesse caso, ela mora melhor na descrição do PR ou no template de review do que num arquivo que ninguém relê.
• Se a regra é sobre comportamento entre turnos (“sempre faça X antes de Y”), assume que 88% das vezes vai ser ignorada, e planeja o sistema em cima disso.

Harness Engineering em uma frase é isso: construa a cerca antes de escrever a placa. Se você já escreveu a placa, mede quanto tempo ela levou para ser ignorada. O meu recorde foi três meses. Aposto que dá para bater.

---

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