This website uses cookies

Read our Privacy policy and Terms of use for more information.

Le problème : la dette d'instructions

Une instruction, c'est une règle dans un AGENTS.md, un fichier de config d'agent, un skill partagé. Elle est écrite pour un état du monde précis : version du modèle, capacités du harness, structure de la codebase.

Quand cet état change, l'instruction reste en place. Sa valeur décroît. Son coût, lui, ne décroît pas.

Le coût est double :

  • Tokens : elle est relue à chaque session d'agent, pendant toute la vie de la session.

  • Adhérence : plus le fichier d'instructions grossit, moins le modèle suit. Ajouter une règle à chaque erreur de l'agent fait boule de neige. Le fichier gonfle, l'adhérence baisse, on ajoute encore. Jusqu'à transformer un guide de décision en base de connaissances.

Le mécanisme de fond : une règle s'écrit après une erreur parce qu'elle était nécessaire ce jour-là. Quand le modèle ne fait plus cette erreur, la règle n'est plus un garde-fou, c'est du bruit qui paie de la place à chaque session. Et personne ne la retire. Une fois écrite, elle est invisible.

C'est la dette que le refactoring ne rembourse pas. Ton code a une CI qui attrape les régressions. Tes instructions d'IA n'ont rien. Elles pourrissent en silence.

Et dans une équipe, c'est pire. Chaque dev copie l'AGENTS.md du voisin, ajoute sa règle perso, ne retire jamais rien. La dette d'instructions se démultiplie par le nombre de repos et de devs qui pratiquent l'IA.

Les chiffres de 2026

Le sujet n'est plus anecdotique. Les données sont récentes et convergent.

Une étude sur 100 repos populaires contenant un fichier AGENTS.md ou CLAUDE.md (SCAM 2026) a identifié 6 "smells" récurrents :

  • 62% des fichiers ont de la lint leakage

  • 42% du context bloat

  • 35% de la skill leakage

Anthropic a retiré plus de 80% du system prompt de Claude Code pour ses modèles Claude 5 avec zéro perte mesurable sur ses évaluations internes. Même l'éditeur du produit a constaté qu'il sur-contraignait : "we found that we were overconstraining Claude Code, both through our system prompt and in our CLAUDE.md files and skills."

Le contre-point existe, et il renforce la thèse. Une ablation sur 2 agents et 288 runs (arXiv 2607.27250) montre que le fichier de contexte ne bouge pas la correctness de manière mesurable. Un autre papier (arXiv 2607.09691) montre que les résumés en langage naturel ne répondent qu'à 4/45 questions comportementales, contre 27/45 pour la source. Traduction : ce qui aide n'est pas la documentation générique, c'est l'instruction précise et à jour. Le reste est du poids.

Le rôle du lead dev : la CI des instructions

Si les instructions d'IA sont du code produit, elles ont besoin de la même infra que le code : une CI. Quatre couches, qui tournent sans que les devs aient à y penser.

Couche 1 : à l'écriture, la règle est datée.

Chaque règle qui entre dans un fichier d'instructions chargé à chaque session porte sa date et sa raison. Pas "fait ceci", mais "fait ceci depuis le 15/06, compensait la faiblesse X du modèle". Une règle datée se re-questionne. Une règle orpheline s'oublie. Ça se fait dans le code review : la PR qui touche AGENTS.md exige la ligne "pourquoi".

Couche 2 : nightly, la fraîcheur est mesurée, pas sentie.

Un script tourne chaque nuit sur les repos. Il remonte les fichiers d'instructions jamais re-validés, les règles dont la date approche de la demi-vie. Pas de sentiment, pas de "je verrai". Une métrique. Comme une alerte de dépendance obsolète, mais pour les instructions.

Couche 3 : mensuel, la consolidation offline.

Une fois par mois, tri offline : les instructions mortes s'archivent, les règles douteuses passent en test de soustraction. C'est le moment où l'accumulation se trie, séparément de la production. Le lead pose le rendez-vous, comme une revue de dette technique.

Couche 4 : à la correction, la propagation est obligatoire.

La couche la plus importante, et celle qu'on oublie toujours. Une règle fausse ne se corrige pas à un endroit. Elle se grep partout, dans tous les repos qui l'ont copiée. En équipe, c'est une consigne de chantier : "si tu touches une règle, grep-la dans les 12 repos qui l'ont copiée".

❝

Cas vécu. Une info erronée était propagée dans les fichiers d'instructions d'une stack, découverte des mois plus tard par une pièce officielle qui la contredisait. Corriger un seul endroit n'aurait rien résolu : les copies continuaient de mentir, et la plus lue était la pire. Une correction n'existe que si elle atteint toutes les copies. C'est une propagation, pas une édition.

L'outil qui manque : le test de soustraction

Le réflexe inverse de l'ajout. Pour savoir si une règle d'agent apporte encore de la valeur, ne pas raisonner sur son utilité passée. La retirer et mesurer la différence.

  1. Désactiver le composant, ou tous, pour avoir la baseline modèle nu + harness.

  2. Refaire une tâche représentative.

  3. Si la qualité tient, le composant ne regagne pas sa place. Si elle chute, il la regagne avec une preuve à jour au lieu d'une présomption.

Le besoin ressenti de garder un composant est souvent une confiance déplacée dans sa propre configuration. On s'appuie sur ses skills comme une béquille parce qu'on ne croit pas que le modèle et le harness se sont améliorés. Ils s'améliorent en continu. Ce qui compensait la faiblesse d'hier peut être natif aujourd'hui.

En équipe, le test de soustraction se passe sur un repo pilote : retire la règle douteuse, fais tourner la suite d'évaluation que vous avez déjà, compare. Si la qualité tient, elle ne regagne pas sa place. Et la consigne devient : toute nouvelle règle entre avec une preuve, pas avec une anecdote.

Ce que ça donne

En une passe d'audit sur mes propres fichiers d'agent, j'ai attrapé 4 règles obsolètes. Des règles qui dataient, qui n'avaient aucun contre-argument, et qui auraient continué à payer des tokens sans cette cadence.

La dette d'instructions ne se rembourse pas en un soir. Elle se prévient par la cadence : écrire daté, mesurer la fraîcheur, consolider offline, propager les corrections. Une CI pour tes agents. Pas un chantier, un rythme.

Et c'est un des rares chantiers où le lead dev peut agir seul : pas besoin d'attendre la plateforme d'IA de la boîte, pas besoin d'un budget. Une règle de code review, un script de veille, un rendez-vous mensuel.

Liens sélectionnés

  1. Audit your Agent files (Addy Osmani, 27/08/2026). Un guide pratique pour auditer ce dont ton agent a encore besoin, avec le test de soustraction et la recommandation de désactiver l'auto-memory.

  2. Configuration Smells in AGENTS.md Files (dos Santos et al., SCAM 2026). L'étude des 100 repos : 62% lint leakage, 42% context bloat, 35% skill leakage. Les 6 smells avec leur co-occurrence. La source primaire des chiffres.

  3. The new rules of context engineering for Claude 5 (Thariq Shihipar, Anthropic, 24/07/2026). Le retrait de plus de 80% du system prompt de Claude Code sans perte, et les 6 bascules "Then/Now" (rules → judgement, CLAUDE.md → auto-memory).

  4. Do Context Files Help Coding Agents? (Prakhar Khatri, 28/07/2026). Le contre-point : sur 288 runs, le contexte ne bouge pas la correctness de façon mesurable. À lire pour ne pas sur-vendre les context files.

  5. What Context Does a Coding Agent Actually Need to Act? (Brian Sam-Bodden, 19/06/2026). Les résumés naturels répondent à 4/45 questions que la source répond à 27/45. La nuance entre documentation et instruction exécutable.

Outil de la semaine

Le test de soustraction, en 15 minutes. Ce n'est pas un outil, c'est un geste : désactiver une règle ou un skill suspect, refaire une tâche représentative, comparer le résultat. Si la qualité tient, le composant ne regagne pas sa place. Zéro installation, zéro coût, juste la discipline de tester par soustraction au lieu de raisonner sur l'utilité passée. Sur mon système perso, j'ai tué 3 skills comme ça, et il est plus léger à chaque session.

❝

Quelle est la règle la plus vieille dans les fichiers d'instructions de ta stack, et tu sais encore pourquoi elle est là ?

Réponds-moi, ça m'aide à calibrer les prochains numéros. Et si tu ne sais pas pourquoi elle est là, tu viens de trouver ton premier test de soustraction.

Reply

Avatar

or to participate