Geoffrey Huntley arregla a los agentes de código con un hook pre-commit y consigue un 10 sobre 10

Geoffrey Huntley ha descrito un truco que, según él, llevó al «diez de diez» el cumplimiento de una regla interna por parte del agente. No intentó convencer al modelo con otra línea más en las instrucciones, sino que colocó un hook pre-commit en el camino del commit. Simon Willison publicó la cita, tomada del ensayo de Huntley «nobody should type code by hand anymore. here's what's left». La métrica es aquí subjetiva: el autor no explica cómo la midió. Aun así, la mecánica merece un análisis.

Dónde falla AGENTS.md

La situación le resultará familiar a cualquiera que haya trabajado con agentes de código. El proyecto tiene su propia biblioteca de diagnóstico, una capa sobre la observabilidad. El agente, en lugar de usarla, llama directamente a los módulos de observability. La jugada obvia es añadir una regla a AGENTS.md y esperar que el modelo la tenga en cuenta.

Huntley explica por qué eso no basta. Se puede pedir al agente que analice su propio comportamiento y actualice el archivo, pero entre la instrucción y la práctica real sigue quedando una brecha («delta») que tenderá a derivar. Las reglas de texto son probabilísticas: el contexto crece, las formulaciones compiten entre sí, cambia el modelo o su versión. El archivo de instrucciones sigue siendo un deseo.

Cómo funciona el hook

Huntley traslada la regla del texto al código. El esquema es breve:

• Disparador: un intento de hacer git commit.
• Comprobación: un script lee el git diff y busca llamadas directas a módulos de observability que eluden el módulo diagnostics.
• Reacción: si hay coincidencia, el commit falla.
• Retroalimentación: se inyecta en el agente un prompt que le exige usar la diagnostics library.
• Resultado, según el autor: diez de diez.

Lo importante es la combinación final. Si el commit se rechazara sin explicación, el agente podría esquivarlo de forma aleatoria. Aquí, en cambio, el mensaje de error dice a la vez qué está mal y qué hacer. El agente recibe la corrección en el momento en que la necesita, y no al inicio de la sesión, entre cientos de líneas de contexto.

Además, la comprobación es determinista. No depende de lo que el modelo «recuerde» de AGENTS.md y funciona igual con cualquier modelo y en cualquier herramienta de agentes que haga commits mediante git.

Cómo aplicarlo en tu proyecto

La conclusión del enfoque de Huntley es de ingeniería. Las reglas para agentes se dividen en dos grupos: las que se pueden verificar de forma mecánica y las que no. Las primeras conviene trasladarlas a hooks, linters y CI. Las segundas, como el criterio arquitectónico o los matices del dominio, se quedan en AGENTS.md.

Los candidatos a trasladar se ven de inmediato: prohibir las llamadas directas que esquivan la capa interna, exigir un logger concreto, fijar una única forma de trabajar con las configuraciones, vetar dependencias. Si la infracción se detecta con una expresión regular o analizando el diff, no debería vivir en una instrucción de texto.

Algunas salvedades que conviene tener en cuenta (son consideraciones mías, no aparecen en la cita):

• Escribe el texto del error como un prompt: qué se ha encontrado, por qué no se puede y con qué sustituirlo.
• Un hook local se puede saltar con la opción --no-verify, así que es sensato duplicar la misma comprobación en CI.
• Vigila los falsos positivos: si el hook bloquea commits legítimos, el agente empezará a «curar» el código alrededor de la comprobación en lugar de resolver el fondo.
• Lleva un contador de activaciones. Mostrará qué reglas incumple el agente con más frecuencia y, de paso, aportará la métrica que le falta a la valoración «10/10».

Las etiquetas de la entrada de Willison, agentic-engineering y coding-agents, describen con precisión la dirección. La ingeniería en torno al agente, es decir, los hooks, las comprobaciones y la retroalimentación, empieza a importar tanto como la elección del modelo.