Ne générez pas automatiquement `AGENTS.md` avec `/init` — cela augmente au contraire les coûts de 20 %

Argument principal

• Si l’on génère automatiquement le fichier de contexte (AGENTS.md) pour les agents de codage IA avec la commande /init, les performances de l’agent baissent au contraire et les coûts augmentent de plus de 20 %
• Le cœur du problème est de fournir en doublon des informations que l’agent peut découvrir par lui-même
• AGENTS.md ne devrait contenir que les informations que l’agent ne peut pas déduire en lisant le code

Résultats de recherche : AGENTS.md aide-t-il ou nuit-il ?

• Lulla et al. (ICSE JAWs 2026) : expérience appariée sur 124 PR GitHub en ne changeant que la présence ou l’absence de AGENTS.md
  • Avec AGENTS.md, le temps d’exécution diminue de 28,64 % et les tokens de sortie de 16,58 %
  • Le fichier utilisé dans cette étude était réellement maintenu par des développeurs et contenait des connaissances propres au projet
• Étude de l’ETH Zurich : 4 agents testés sur SWE-bench, entre autres, en distinguant les fichiers générés automatiquement par LLM et les fichiers rédigés par des développeurs
  • Contexte généré automatiquement par LLM : baisse du taux de réussite de 2 à 3 % et hausse des coûts de plus de 20 %
    • Dans un environnement où toute la documentation existante, y compris le README, était supprimée, le fichier généré par LLM améliorait au contraire les performances de 2,7 %
  • Fichiers rédigés directement par des développeurs : amélioration du taux de réussite d’environ 4 %, avec une hausse des coûts pouvant aller jusqu’à 19 %
• Conclusion : ce n’est pas le contenu auto-généré en soi qui pose problème, mais la redondance
  • Donner deux fois la même information n’ajoute que du bruit, et seules les connaissances impossibles à découvrir rédigées par les développeurs apportent une aide réelle

Pourquoi l’auto-génération est nuisible

• Un AGENTS.md généré automatiquement contient le plus souvent des informations que l’agent découvre déjà lui-même
  • Vue d’ensemble de la base de code (présente dans 100 % des sorties de Sonnet 4.5 et 99 % des sorties de GPT-5.2)
  • Structure des répertoires, stack technique, description des modules
• Redonner des informations déjà connues consomme uniquement des tokens sans apporter de valeur
• Effet d’ancrage : si l’on mentionne des patterns legacy, l’agent reste fixé dessus même si de meilleures alternatives existent
  • Cela rejoint l’étude "Lost in the Middle" (Liu et al., 2024) — un contexte long disperse l’attention et dégrade les performances

Ce qu’il faut mettre dans AGENTS.md vs ce qu’il ne faut pas y mettre

• À inclure (informations impossibles à découvrir par l’agent)
  • Désignation d’outil : "utiliser uv pour la gestion des paquets"
  • Règles contre-intuitives : "les tests doivent impérativement être exécutés avec --no-cache, sinon les fixtures produisent des faux positifs"
  • Contraintes système : "le module auth utilise un middleware personnalisé ; ne pas le refactorer en Express standard"
  • Quand un outil est mentionné dans la documentation, l’agent l’utilise 1,6 à 2,5 fois par tâche ; s’il n’est pas documenté, cela chute à moins de 0,05 fois
• À ne pas inclure (ce que l’agent peut découvrir seul)
  • Structure des répertoires, layout monorepo
  • Vue d’ensemble de la stack technique, patterns d’architecture standard

Limites structurelles d’un fichier statique

• Même bien rédigé, AGENTS.md a une faiblesse fondamentale — le fichier est statique, alors que les tâches sont dynamiques
• Les instructions d’un fichier unique ne peuvent pas se ramifier selon le type de tâche
  • Même pour une simple modification de documentation, l’instruction "exécuter l’ensemble des tests avant le commit" s’applique, ce qui gaspille des tokens et du temps
  • Un refactoring CSS charge des avertissements sur les migrations de base de données, et un correctif de sécurité s’accompagne d’indices d’optimisation des performances
• Framework ACE (ICLR 2026) : au lieu d’un fichier statique, l’approche Agentic Context Engineering fait évoluer dynamiquement le contexte via un pipeline generator/reflector/curator, avec des performances 12,3 % supérieures à celles de l’approche statique

Une meilleure structure, qui n’existe pas encore

• À propos de AGENTS.md, plusieurs personnes sont arrivées indépendamment à la même conclusion
  • La bonne structure n’est pas un fichier unique, mais une couche de routage + un contexte ciblé chargé à la demande
• Layer 1 - fichier de protocole : non pas une vue d’ensemble de la base de code ni un guide de style, mais un document de routage
  • Il définit les personas disponibles et les conditions d’appel, les skills et les types de tâches pris en charge, ainsi que les connexions MCP et leur usage
  • Il ne contient que le minimum de faits sur le dépôt que l’agent ne peut pas découvrir, et rien d’autre
• Layer 2 - fichiers de persona/skills : chargés sélectivement selon le type de tâche
  • Un agent UX et un agent backend chargent des contextes différents, sans charger le contexte de l’autre
• Layer 3 - sous-agent de maintenance : agent dédié au maintien de l’exactitude du fichier de protocole
  • La documentation se dégrade — l’étude de l’ETH Zurich a déjà observé une baisse de performance avec des fichiers fraîchement générés
  • Si un AGENTS.md laissé à l’abandon pendant 6 mois décrit des dépendances déjà remplacées ou une structure de répertoires modifiée, le problème devient bien plus grave
• Aucun grand agent de codage actuel ne fournit de hooks de cycle de vie permettant d’implémenter facilement cette architecture — on peut l’approcher avec des sous-agents et un contexte scoped, mais il reste encore un vide outillage à combler

Optimisation automatique

• Arize AI utilise une boucle d’optimisation automatique au lieu d’écrire manuellement les consignes de CLAUDE.md
  • Exécuter l’agent sur des tâches d’entraînement → évaluer le résultat → générer avec un LLM un feedback sur les causes d’échec → améliorer les consignes par méta-prompting → répéter
  • Amélioration de la précision de +5,19 % dans les tests cross-repo et de +10,87 % dans les tests in-repo
• Fait inconfortable révélé par l’optimiseur : ce qui aide un humain à comprendre une base de code n’est pas ce dont un LLM a besoin pour s’y repérer
  • Une information comme "ce service utilise le pattern repository" paraît évidemment utile à un développeur, mais peut n’être que du bruit pour le modèle
  • À l’inverse, ce dont le modèle a réellement besoin (distinction entre certains chemins d’import, conventions de nommage de fichiers peu intuitives, etc.) est souvent tellement intériorisé par les développeurs qu’ils ne pensent même pas à l’écrire
• Rédiger AGENTS.md manuellement suppose que les développeurs savent ce dont l’agent a besoin
  • Les preuves empiriques suggèrent probablement le contraire
  • L’optimiseur met au jour l’écart entre "ce qu’on pense important" et "ce qui change réellement les résultats"
• Cela ne signifie pas qu’il faut renoncer à en écrire — 5 % est significatif, mais pas transformateur. Cela signifie qu’il faut garder son intuition souple et tester en conditions réelles

Le bon état d’esprit face à AGENTS.md

• Considérer AGENTS.md comme la trace d’un processus qui n’a pas encore été corrigé
• Chaque ligne ajoutée est le signe qu’il existe dans la base de code une ambiguïté suffisante pour désorienter un agent IA ; il est donc très probable qu’un nouveau contributeur humain s’y perde aussi
• La bonne réponse n’est pas d’agrandir le fichier de contexte, mais de corriger la cause racine
  • L’agent place un utilitaire dans le mauvais répertoire → la structure des répertoires elle-même est confuse, il faut donc la réorganiser
  • L’agent continue d’utiliser une dépendance obsolète → la structure des imports rend trop facile l’usage de la mauvaise option, il faut donc la corriger
  • L’agent oublie la vérification de types → il ne faut pas dépendre d’une instruction, mais la faire appliquer automatiquement dans le pipeline de build
• AGENTS.md est un outil de diagnostic, pas une configuration permanente — on ajoute une ligne, on cherche pourquoi l’agent répète cette erreur, on corrige la cause racine, puis on supprime cette ligne
• Technique à essayer : commencer avec un AGENTS.md presque vide et n’y mettre qu’une seule instruction, du type "si tu découvres quelque chose de surprenant ou de confus dans ce projet, laisse un commentaire". La plupart des ajouts proposés par l’agent ne sont pas faits pour être conservés en permanence, mais servent de marqueurs des zones floues de la base de code

Recommandations pratiques

• Cesser d’exécuter /init — sauf si le dépôt n’a absolument aucune documentation, le résultat auto-généré fera doublon avec la documentation existante
• Avant d’ajouter une ligne à AGENTS.md, se demander : "l’agent peut-il le savoir en lisant le code ?" Si oui, ne pas l’écrire
• Quand un agent échoue de manière répétée, corriger d’abord la base de code elle-même avant d’agrandir le fichier de contexte
  • Améliorer la structure du code, ajouter des règles de linter, étendre la couverture de tests — et ne toucher à AGENTS.md que si cela ne suffit toujours pas
• Si vous exploitez des agents à grande échelle dans un pipeline CI/CD ou de revue automatique, gardez à l’esprit qu’un surcoût de 15 à 20 % se cumule avec effet composé sur des milliers d’exécutions
• L’instinct consistant à onboarder un agent comme une nouvelle recrue (visite du bureau, organigramme, explication de l’architecture) est naturel, mais un agent de codage n’est pas un junior — il peut déjà grep toute la base de code avant même que vous ayez fini de taper le prompt. Ce dont l’agent a besoin, ce n’est pas d’une carte, mais de l’emplacement des mines