Un développeur a entrepris d'améliorer le fichier de directives pour agents d'IA (AGENTS.md) de son projet en utilisant l'IA elle-même, mais en mesurant chaque modification par rapport à des tâches de codage réelles et non sur la seule intuition. L'expérience, menée sur le code du logiciel Stet, a consisté à faire itérer un modèle d'IA (décrit comme Codex avec une version de GPT) huit fois, en évaluant chaque version candidate d'AGENTS.md sur un échantillon d'entraînement de cinq tâches, puis sur un ensemble de validation distinct de dix tâches.

Des résultats contrastés Les résultats montrent que la version la plus prometteuse sur l'échantillon d'entraînement – qui corrigeait une tâche manquée par la référence et améliorait certains indicateurs de qualité de code – a régressé sur l'ensemble de validation. Le nombre de jetons (tokens) utilisés et d'appels d'outils a augmenté, tandis que la correction du code (correctness) et la discipline de périmètre (scope discipline) ont baissé. Le développeur qualifie cette observation de « directionnelle, non statistiquement significative » en raison de la petite taille de l'échantillon (n=10), mais il souligne qu'elle illustre un phénomène problématique : des instructions qui semblent bonnes peuvent dégrader les performances sur des tâches non vues.

Le processus a révélé que les règles intuitives ne sont pas nécessairement efficaces. La première tentative, consistant en une règle générale de « routeur », semblait raisonnable mais a conduit l'agent à interpréter une consigne de « petit périmètre » comme une permission d'ignorer des obligations explicites. Une itération ultérieure, qui ajoutait un « registre des obligations » (identification des comportements nommés, contraintes de compatibilité, documentation, tests), a produit le premier signal utile : une amélioration de la revue de code (+0,75), de la correction (+0,60) et de la simplicité (+0,64). Cependant, l'empreinte (footprint) du code s'est légèrement dégradée.

Le piège de l'optimisation intuitive L'expérience a également testé une règle « philosophiquement correcte » : préférer les mécanismes existants avant d'en ajouter de nouveaux. L'évaluation a montré qu'elle était empiriquement néfaste, dégradant la simplicité, la cohérence, la robustesse et d'autres indicateurs. L'auteur insiste sur ce point pour démontrer que la mesure est indispensable : des instructions plausibles ne sont pas nécessairement de bonnes interventions.

Après une série d'échecs, la meilleure version de l'expérience a resserré la règle de l'obligation : identifier l'obligation, le propriétaire du changement, puis le chemin de validation avant d'éditer. Sur l'échantillon d'entraînement, elle a récupéré tous les tests et amélioré plusieurs indicateurs, mais la discipline de périmètre et l'adhésion aux instructions ont baissé. L'analyse a montré que l'agent dépensait plus de ressources (plus de jetons) pour des résultats mitigés.

Le phénomène d'inversion d'AGENTS.md Le développeur nomme ce constat « inversion d'AGENTS.md » : un changement d'instruction peut aider la plupart des tâches tout en nuisant à un sous-ensemble mesurable. La moyenne peut s'améliorer alors que certains types de tâches régressent. Ce phénomène est particulièrement dangereux sur des bases de code partagées, car les tâches qu'un individu effectue peuvent s'améliorer, tandis que celles de ses collègues peuvent se dégrader sans que personne ne s'en aperçoive.

La conclusion de l'expérience est que les instructions des agents (AGENTS.md, CLAUDE.md ou autres) ne doivent pas être traitées comme de simples documents, mais comme des éléments paramétrables du système de codage. Le développeur insiste sur la nécessité d'une évaluation systématique : il ne suffit pas d'ajouter une règle qui « semble correcte », il faut mesurer son effet réel. Il avertit que les tests unitaires seuls sont insuffisants pour ce type de changement, car ils peuvent rester verts tandis que d'autres aspects du comportement de l'agent se dégradent.