Votre AGENTS.md a été écrit pour un modèle moins performant : audit de la dette de prompts
Les anciennes règles de AGENTS.md survivent aux défauts du modèle qu’elles ont corrigés. Apprenez à repérer les dettes de prompts, à affiner les compétences en fonction des routeurs, à définir les permissions et à déterminer ce qui est terminé avant de commencer.
Chaque ligne d’un fichier AGENTS.md a généralement été ajoutée pour corriger une défaillance réelle. Les modèles s’améliorent, la défaillance disparaît, mais la règle reste en place. C’est ce qu’on appelle la dette de prompt : une solution de fortune à une faiblesse d’un modèle qui devient une politique permanente. La solution consiste à confier au fichier une tâche plus ciblée, couvrant les invariants, les contraintes cachées et les limites de permissions, ainsi qu’une définition de ce qui est considéré comme terminé.
Chaque fois qu’un agent de codage échoue de manière mémorable, quelqu’un ajoute une règle. Il modifie trop de choses, alors le fichier indique de ne toucher qu’au strict nécessaire. Il omet la vérification, ce qui oblige à exécuter l’ensemble du jeu de tests à chaque fois. Il change une dépendance sans demande, ce qui fait que les modifications de dépendances nécessitent désormais une approbation. Il erre dans le répertoire, c’est pourquoi le fichier précise quels documents lire en premier.
Chaque règle avait du sens au moment où elle a été écrite. Puis le modèle a changé.
OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done
La nouvelle génération de modèles, avec GPT-6 Astra comme exemple, suit les instructions de manière nettement meilleure que les modèles de codage précédents, ce qui modifie les aspects économiques liés à l’élaboration des prompts. Un modèle faible peut ignorer une règle trop générale, tandis qu’un modèle puissant peut la respecter à la lettre. Ainsi, une instruction conçue pour compenser les défauts d’un modèle plus ancien peut devenir source de problèmes avec un modèle plus récent. Si vous mettez à jour le modèle sans auditer ses instructions, vous conservez les anciennes faiblesses en tant que politique permanente au sein du nouveau système. Le modèle s’est amélioré, mais la manière d’utiliser les prompts est restée inchangée.
Chaque échec laisse un fossile
Le code accumule une dette technique lorsque une solution temporaire locale se transforme en contrainte structurelle. Les instructions destinées aux agents génèrent également une dette de la même manière.
Disons qu’un modèle de codage plus ancien oubliait constamment de vérifier ses modifications, alors quelqu’un a ajouté :
Always run the entire test suite after every change.
À l’époque, cela a peut-être amélioré la fiabilité. Un an plus tard, le modèle identifie déjà les tests affectés et vérifie son propre travail, pourtant l’instruction reste en place. Aujourd’hui, une simple correction de texte de un mot peut déclencher vingt minutes de tests d’intégration. Rien n’est cassé, et l’agent suit fidèlement le dépôt. Le problème, c’est qu’un ancien correctif comportemental a été élevé au rang de politique d’ingénierie permanente.
C’est ce qu’on appelle une dette rapide : une règle résout un problème réel, le problème disparaît, mais la règle continue d’exister.
Les compétences coûtent quelque chose avant d’être utilisées
Les compétences semblent bon marché, car leur contenu complet n’est chargé que lorsque c’est nécessaire. Le format Agent Skills prévoit une divulgation progressive : le nom et la description d’une compétence s’affichent d’abord, tandis que le fichier complet n’est chargé que lorsque une tâche correspond.
Cependant, avant que le modèle ne puisse choisir une compétence, il doit d’abord reconnaître les options disponibles, ce qui fait que les noms et les descriptions se disputent déjà son attention.
Imaginez un répertoire contenant des compétences distinctes couvrant les migrations de bases de données, PostgreSQL, la conception de schémas, la persistance en arrière-plan, l’optimisation des requêtes et la récupération. Chacune d’elles comporte une description générale mentionnant à la fois SQL, les migrations, les schémas, les requêtes, les modèles et le stockage. Même une petite modification d’une requête semble désormais pertinente pour la moitié des compétences disponibles, ce qui oblige l’agent à classer ces informations avant de pouvoir coder.
Le meilleur modèle reste celui de la divulgation progressive, recommandé également dans la documentation des compétences d’OpenAI : des instructions détaillées se trouvent dans des fichiers d’accompagnement qui ne sont affichés que lorsque tâche l’exige.
database/
├── router.md
└── references/
├── migrations.md
├── performance.md
└── recovery.md
Le fichier de base ne nécessite que l’essentiel pour diriger la tâche. Un changement de schéma mène à migrations.md, une requête lente à performance.md, une restauration ou une perte de données à recovery.md. Les détails ne sont pas perdus ; ils apparaissent lorsque la tâche donne à l’agent une raison de les lire, ce qui permet d’utiliser le contexte de manière plus efficace que de se fier à des suppositions pour obtenir des connaissances opérationnelles.
AGENTS.md doit contenir ce que le code ne peut pas expliquer
Les instructions au niveau du répertoire se comportent différemment car elles accompagnent l’agent dans presque toutes les tâches. Des fichiers comme AGENTS.md sont chargés dans une session en tant que contexte permanent, comme le décrivent les documents de mémoire de Claude Code, ce qui en fait un fardeau lorsqu’ils sont erronés, obsolètes ou inutilement généraux.
Un test utile : un ingénieur compétent qui examine ce répertoire pourrait-il le résoudre de manière sûre et économique ? Si oui, cette règle n’a peut-être pas sa place dans AGENTS.md. Sinon, elle y devrait probablement figurer.
Comparez deux instructions. La première correspond à des connaissances spécifiques au répertoire que le modèle ne peut pas déduire en toute sécurité, c’est pourquoi elle reste telle quelle :
KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.
Le deuxième décrit un flux de travail qui pourrait convenir à une refonte architecturale, mais qui est excessif pour corriger une simple faute de frappe, il devrait donc être supprimé ou déplacé :
MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies
Les instructions persistantes devraient principalement couvrir trois éléments : des invariants qui doivent rester vrais, des contraintes cachées que la base de code ne met pas en évidence, ainsi que des limites d’autonomie indiquant où l’agent peut agir et où c’est à un humain de décider. C’est une tâche bien plus simple que d’apprendre à un modèle comment pratiquer l’ingénierie logicielle.
De meilleurs modèles rendent les autorisations plus importantes
Un suivi plus strict des instructions entraîne une défaillance plus subtile. L’agent peut respecter vos limites avec tant de précision qu’il s’arrête au moment même où vous vouliez qu’il continue.
Supposons qu’il mette en œuvre un changement et qu’un test local affecté par ce changement échoue. Il signale que auth_spec.ts ne fonctionne pas et demande s’il doit le corriger. Le modèle sait comment réparer le test, mais il ne sait pas si cette réparation relève de ses compétences autorisées. Dans ce cas, accorder une autorisation est plus utile que toute autre procédure :
Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.
Ces lignes indiquent à l’agent trois éléments qu’il ne peut pas toujours déduire : l’environnement est sûr, les actions correctives relèvent du champ d’application, et il peut continuer. Des limites définies de cette manière guident mieux les décisions que des interdictions générales comme « ne jamais élargir le champ d’application ».
Une façon de partager les responsabilités en pratique :
Nécessite l’approbation humaine :
- Supprimer des données de production.
- Changer la politique d’authentification.
- Violer un contrat d’API publique.
- Introduire une migration présentant un risque opérationnel.
L’agent peut généralement continuer avec :
- Corriger un test que sa propre modification a endommagé.
- Mettre à jour des types locaux voisins.
- Formater les fichiers qu’il a modifiés.
- Réexécuter les tests locaux concernés.
C’est la conséquence qui distingue les deux listes : les actions voisines ne méritent pas toutes le même niveau d’approbation.
Définir ce qui est terminé avant de décrire le processus
Les instructions plus anciennes décrivent souvent le parcours :
Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.
Cela peut être utile lorsque le flux de travail est vraiment fragile, mais un agent compétent tire généralement plus de bénéfices d’une extrémité bien définie. Comparez la demande brute.
Implement the avatar endpoint.
avec une version qui ajoute une ligne d’arrivée :
Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.
Le second ne précise jamais quel fichier ouvrir en premier. Il indique à quoi ressemble le résultat final. Cette distinction s’accentue à mesure que les modèles acquièrent suffisamment de jugement pour choisir eux-mêmes leur parcours au sein d’une base de code. Les humains définissent la destination et les limites dangereuses, tandis que l’agent calcule le trajet.
Gardez une hiérarchie des instructions bien pensée
Une structure ordonnée comporte trois niveaux distincts. Le premier est le fichier du répertoire :
AGENTS.md
↓
Repository invariants
Safety boundaries
Global permissions
Le deuxième comprend des compétences :
Skills
↓
Specialized workflows
Loaded only when relevantTask prompt
↓
Immediate objective
Local constraints
Definition of done
Le troisième élément est la prompt de tâche elle-même. Les problèmes apparaissent lorsque les différentes couches se mélangent : un flux de travail de tâche ponctuel intégré dans AGENTS.md, une règle de sécurité globale cachée à l’intérieur d’une compétence que le modèle pourrait ne jamais charger, une compétence qui devient une véritable encyclopédie, ou encore une prompt de tâche qui répète des connaissances déjà présentes dans le répertoire du modèle. À mesure que les modèles gagnent en capacités, cette duplication devient de plus en plus coûteuse.
Vérification des dettes liées aux prompts lors des mises à jour du modèle
Une mise à jour du modèle doit déclencher une vérification des instructions. Ce n’est pas parce que chaque ancienne instruction est fausse, mais parce que les hypothèses qui la sous-tendaient ont pu changer. Une vérification utile comprend quatre étapes.
Faire l’inventaire des compensations historiques
Rassembler tout ce qui influence le comportement de l’agent :
AGENTS.md- descriptions des compétences
- contenu des compétences
- prompts au niveau du système dans le répertoire
- Instructions répétées dans les modèles de tâches
Pour chaque règle, déterminez pourquoi elle existe et quel échec a poussé quelqu’un à l’ajouter en premier.
Distinguer les invariants réels des habitudes
Demandez-vous si un ingénieur compétent peut déduire cette règle de manière sûre et économique à partir du dépôt. S’il le peut, testez si elle est applicable. Sinon, conservez-la. Les règles concernant les risques liés à la production, les artefacts générés, le comportement de l’infrastructure cachée et les contraintes opérationnelles peu évidentes méritent une attention particulière.
Transformer les compétences complexes en outils d’aide
Si une compétence concerne plusieurs flux de travail, réduisez son point d’entrée. Ne chargez les instructions de migration que pour les migrations, et les procédures de récupération uniquement lorsque la récupération est pertinente. Les connaissances spécialisées restent intactes, sans être imposées à chaque tâche voisine.
Rélisez chaque interdiction pour en comprendre le risque sous-jacent
Les règles du type « NE JAMAIS toucher à X », « DEMANDER TOUJOURS avant de faire Y » ou « MODIFIER SEULEMENT Z » peuvent encore être pertinentes, mais chacune doit être évaluée en fonction des conséquences qu’elle est censée éviter. Parfois, une meilleure règle stipule que X peut être modifié librement en développement local, mais qu’une question doit être posée au préalable en environnement de production, ou que les régressions causées par les propres modifications de l’agent peuvent être corrigées, tandis que toute modification plus importante nécessite une validation.
Le but n’est pas l’autonomie maximale. Il s’agit d’orienter l’attention humaine là où les conséquences l’exigent.
Qu’est-ce qui doit survivre à chaque mise à jour
Même avec des modèles de très haute qualité, certaines instructions restent nécessaires. Un déploiement peut exiger un paramètre obsolète non documenté. Les fichiers générés peuvent sembler modifiables, bien que les modifications soient effacées. Un environnement local peut ressembler à l’environnement de production en utilisant des éléments temporaires. Une migration peut devoir fonctionner avec deux versions en cours d’exécution d’une application. Ces éléments ont une grande valeur, car la seule intelligence ne permet pas de les identifier de manière fiable.
Le critère à utiliser est la valeur informationnelle. Si l’instruction permet de capturer quelque chose que le modèle ne peut pas découvrir de manière sûre, conservez-la. Si elle ne décrit que la manière dont un modèle plus ancien devait effectuer une tâche d’ingénierie ordinaire, reconsidérez-la. Avoir de nombreuses instructions n’est pas ce qui crée une dette liée aux prompts ; la dette réside plutôt dans celles dont la raison d’existence a disparu.
La méthode traditionnelle pour coder des agents consistait à détailler de plus en plus les étapes du processus. À mesure que les modèles s’améliorent, une conception plus simple s’avère plus efficace : il suffit de conserver les invariants, de définir les permissions et d’expliquer ce que signifie l’achèvement d’une tâche. Laissez le reste à l’agent, et lorsque un nouveau modèle est mis en service, vérifiez les règles avant d’écrire du code supplémentaire.