Jeffrey Huntley conserta agentes de código com um hook de pre-commit e chega a 10 de 10

Jeffrey Huntley descreveu uma técnica que, segundo ele, levou o cumprimento de uma regra interna pelo agente a “dez de dez”. Em vez de tentar convencer o modelo com mais uma linha nas instruções, ele colocou um hook de pre-commit no caminho do commit. A citação, retirada do ensaio “nobody should type code by hand anymore. here's what's left”, foi publicada por Simon Willison. A métrica é subjetiva: o autor não apresenta a metodologia de medição. Mesmo assim, a mecânica merece uma análise.

Onde o AGENTS.md falha

A situação é familiar para quem já trabalhou com agentes de código. O projeto tem uma biblioteca própria de diagnóstico, um wrapper sobre a observabilidade. O agente, em vez de usá-la, chama os módulos de observability diretamente. O movimento óbvio é acrescentar uma regra ao AGENTS.md e torcer para que o modelo a leve em conta.

Huntley explica por que isso não basta. É possível pedir ao agente que analise o próprio comportamento e atualize o arquivo, mas ainda assim continua existindo uma lacuna (“delta”) entre a instrução e a prática real, e ela vai derivar com o tempo. Regras em texto são probabilísticas: o contexto cresce, as formulações competem entre si, o modelo ou a versão muda. O arquivo de instruções continua sendo apenas um desejo.

Como o hook funciona

Huntley tira a regra do texto e a leva para o código. O esquema é curto:

• Gatilho: uma tentativa de fazer git commit.
• Verificação: um script lê o git diff e procura chamadas diretas a módulos de observability que contornam o módulo diagnostics.
• Reação: se houver correspondência, o commit falha.
• Feedback: um prompt é injetado no agente exigindo o uso da diagnostics library.
• Resultado, segundo a avaliação do autor: dez de dez.

O que importa é a combinação final. Um commit recusado sem explicação poderia ser contornado pelo agente de forma aleatória. Aqui, a mensagem de erro diz ao mesmo tempo o que está errado e o que fazer. O agente recebe a correção no momento em que precisa dela, e não no início da sessão, perdida entre centenas de linhas de contexto.

Além disso, a verificação é determinística. Ela não depende do que o modelo “lembra” do AGENTS.md e funciona da mesma forma em qualquer modelo e em qualquer ferramenta de agente que faça commits via git.

Como aplicar no seu projeto

A conclusão que se tira da abordagem de Huntley é de engenharia. As regras para agentes se dividem em dois grupos: as que podem ser verificadas mecanicamente e as que não podem. As primeiras valem ser movidas para hooks, linters e CI. As segundas, como gosto arquitetural ou nuances do domínio, ficam no AGENTS.md.

Os candidatos à migração são evidentes: proibição de chamadas diretas que contornam o wrapper interno, logger obrigatório, uma forma única de lidar com configs, dependências proibidas. Se a violação pode ser encontrada por expressão regular ou pela análise do diff, ela não deveria viver em uma instrução de texto.

Algumas ressalvas a levar em conta (são considerações minhas, não constam da citação):

• Escreva o texto do erro como um prompt: o que foi encontrado, por que não pode e o que usar no lugar.
• Um hook local pode ser contornado com a flag --no-verify, então é sensato duplicar a mesma verificação no CI.
• Fique atento a falsos positivos: se o hook bloquear commits legítimos, o agente passará a “tratar” o código em volta da verificação, e não o problema de fato.
• Mantenha um contador de acionamentos. Ele mostrará quais regras o agente mais viola e, de quebra, fornecerá a métrica que falta à avaliação “10/10”.

As tags da entrada de Willison, agentic-engineering e coding-agents, descrevem bem a direção. A engenharia em torno do agente, ou seja, hooks, verificações e feedback, começa a pesar tanto quanto a escolha do modelo.