Geoffrey Huntley répare ses agents de code avec un hook pre-commit et obtient 10 sur 10

Geoffrey Huntley a décrit une astuce qui, selon lui, a porté à « dix sur dix » le respect par l'agent d'une règle interne. Plutôt que de tenter de convaincre le modèle avec une ligne de plus dans les instructions, il a placé un hook pre-commit sur le chemin du commit. Simon Willison a publié une citation tirée de son essai « nobody should type code by hand anymore. here's what's left ». La métrique est ici subjective : l'auteur ne donne pas de méthode de mesure. Le mécanisme, lui, mérite qu'on s'y arrête.

Là où AGENTS.md atteint ses limites

Tous ceux qui ont travaillé avec des agents de code connaissent la situation. Le projet dispose de sa propre bibliothèque de diagnostic, une surcouche d'observabilité. L'agent, lui, appelle directement les modules d'observability au lieu de l'utiliser. Le réflexe est d'ajouter une règle dans AGENTS.md en espérant que le modèle en tienne compte.

Huntley explique pourquoi cela ne suffit pas. On peut demander à l'agent d'analyser son propre comportement et de mettre à jour le fichier, mais un écart (« delta ») subsiste entre l'instruction et la pratique réelle, et il dérive avec le temps. Les règles textuelles sont probabilistes : le contexte s'allonge, les formulations se font concurrence, le modèle ou sa version change. Le fichier d'instructions reste un vœu pieux.

Comment fonctionne le hook

Huntley fait passer la règle du texte au code. Le schéma est court :

• Déclencheur : une tentative de git commit.
• Vérification : un script lit le git diff et cherche les appels directs aux modules d'observability qui contournent le module diagnostics.
• Réaction : en cas de correspondance, le commit échoue.
• Retour : un prompt est injecté dans l'agent pour lui demander d'utiliser la diagnostics library.
• Résultat selon l'auteur : dix sur dix.

Le dernier maillon est déterminant. Face à un refus de commit sans explication, l'agent pourrait le contourner de façon aléatoire. Ici, le message d'erreur indique à la fois ce qui ne va pas et ce qu'il faut faire. L'agent reçoit la correction au moment où il en a besoin, et non en début de session, noyée parmi des centaines de lignes de contexte.

La vérification, elle, est déterministe. Elle ne dépend pas de ce que le modèle « retient » d'AGENTS.md, et fonctionne de la même manière avec n'importe quel modèle et n'importe quel outil d'agent qui passe par git pour ses commits.

Comment l'appliquer chez soi

La leçon de l'approche de Huntley est d'ordre ingénierie. Les règles destinées aux agents se répartissent en deux groupes : celles qui se vérifient mécaniquement et celles qui ne le peuvent pas. Les premières méritent d'être déplacées vers des hooks, des linters et la CI. Les secondes, comme le goût architectural ou les subtilités du domaine métier, restent dans AGENTS.md.

Les candidats au transfert sautent aux yeux : interdiction des appels directs qui contournent la surcouche interne, logger obligatoire, méthode unique de gestion des configurations, dépendances interdites. Si une expression régulière ou une analyse du diff permet de repérer la violation, elle n'a pas sa place dans une instruction textuelle.

Quelques réserves à garder en tête (ce sont mes propres remarques, elles ne figurent pas dans la citation) :

• Rédigez le message d'erreur comme un prompt : ce qui a été trouvé, pourquoi c'est interdit, par quoi le remplacer.
• Un hook local peut être contourné avec le drapeau --no-verify ; il est donc raisonnable de dupliquer la même vérification dans la CI.
• Surveillez les faux positifs : si le hook bloque des commits légitimes, l'agent se mettra à « soigner » le code autour de la vérification plutôt que le fond.
• Tenez un compteur de déclenchements. Il montrera quelles règles l'agent enfreint le plus souvent, et fournira au passage la métrique qui manque à l'évaluation « 10/10 ».

Les tags de l'entrée chez Willison, agentic-engineering et coding-agents, décrivent bien la direction. L'ingénierie autour de l'agent, c'est-à-dire les hooks, les vérifications et le retour d'information, commence à compter autant que le choix du modèle.