Presque tout ce qui s'écrit sur la documentation logicielle pour agents IA relève du conseil. Zhijun Gao et Jing Chen sont plutôt allés le mesurer. Leur article d'août 2026 (arXiv 2608.20195) instrumente 557 sessions de codage agentique, 94 813 événements, 3 033 interactions documentaires, et un corpus distinct de 33 097 pull requests agentiques, puis pose une question simple : quels documents un agent de codage ouvre-t-il, à quel moment, et qu'arrive-t-il ensuite. La réponse redistribue le travail. Les documents que les agents lisent le plus sont ceux écrits pour des agents, et le matériel de référence sur lequel les équipes investissent le plus d'effort reste presque intouché.
Ce que les agents ouvrent réellement.
Le chiffre principal est une hiérarchie, pas un total. Les artefacts destinés aux agents, c'est-à-dire les fichiers d'instructions et les notes que les agents rédigent pour eux-mêmes, représentent 60,5 % de toutes les interactions documentaires. Détaillons : les fichiers d'instructions (AGENTS.md, CLAUDE.md, SKILL.md, fichiers de règles d'éditeur) comptent pour 35,4 %, et les notes de travail des agents (plans, journaux de raisonnement, brouillons de révision rédigés par l'agent lors d'un tour précédent) pour 25,1 %. Les neuf genres documentaires classiques totalisent ensemble 10,6 %. À l'intérieur de ce total, les références API reçoivent 1,3 % et les documents de dépannage 0,4 %.
Si votre budget de documentation est fini, et il l'est, ce ratio est une instruction de réallocation. La plupart des équipes traitent le fichier d'instructions comme un préambule à la vraie documentation et dépensent en conséquence. Les mesures disent que la dépense est à l'envers : la moitié d'un budget documentaire destinée aux agents tient dans un seul fichier, et il mérite le soin que vous alliez consacrer à la navigation.
Si un fournisseur vous a soumissionné un portail de documentation dans le cadre d'un déploiement d'IA, voici le chiffre sur lequel l'interroger. Quelle part de cette dépense vise quelque chose que votre agent ouvre 1,3 % du temps, et en quoi consiste réellement la moitié destinée aux agents ? Une bonne réponse nomme le fichier d'instructions. Une mauvaise parle d'architecture de l'information.
Lire et travailler sont deux boucles distinctes.
Le constat qui se cache sous la hiérarchie est plus étrange et plus utile. La lecture d'un document ne mène presque jamais directement à une modification de code. La probabilité qu'une modification de code suive immédiatement une lecture documentaire est de 0,002, soit trois événements sur 1 328 lectures. Ce à quoi les lectures mènent, c'est à d'autres lectures (0,270) et à du raisonnement (0,245). Les auteurs décrivent ce comportement comme deux lobes faiblement couplés : une boucle de consultation qui tourne sur elle-même, et une boucle de modification du code qui fonctionne largement indépendamment d'elle.
- 0,270 une lecture mène à une autre lecture
- 0,245 une lecture mène à du raisonnement
- 7,5 % des interactions documentaires sont déclenchées par un échec
- 5,4 % des épisodes d'échec ont d'abord ouvert un document
Deux choses en découlent. L'une corrige une hypothèse répandue : écrire une meilleure documentation de dépannage ne rendra probablement pas votre agent meilleur pour se rétablir, parce que l'agent, la plupart du temps, ne va pas la chercher. L'autre touche à la forme. Les agents lisent par séries et, dans ces données, n'ont jamais suivi de renvoi. Zéro événement attesté. Un document qui dit « voir le guide d'authentification pour plus de détails » est un document qui s'arrête là. Tout ce qui est porteur doit se trouver sur la page où l'agent atterrit.
Nous étions arrivés à la même conclusion du côté du retrieval dans la note sur la mémoire des agents : les surfaces autonomes et récupérables de façon déterministe battent tout ce qui suppose de la navigation. Les graphes de liens gardent leur utilité pour les humains, pour la déduplication, et pour signaler ce qui n'a pas encore été écrit. Ils ne sont simplement pas un mécanisme de livraison.
La prose n'est pas une spec.
Le chiffre le plus inconfortable de l'article est un zéro. Sur l'ensemble des sessions instrumentées, aucun agent n'a été observé en train de vérifier du code par rapport à la documentation. La consultation était même associée à moins de tests immédiats, pas plus : un lift de 0,23, soit environ le quart du taux attendu par hasard. Un fichier d'instructions est respecté au moment de la génération, sur le coup, ou il ne l'est pas du tout. Rien ne revient auditer le résultat par rapport à la phrase.
Les auteurs offrent ici une hypothèse plutôt qu'un résultat, et la distinction mérite d'être faite : si vous voulez qu'une règle soit validée, rendez l'artefact exécutable, c'est-à-dire un doctest, un exemple exécutable, un contrat de schéma. Quelque chose qui réussit ou qui échoue. Ils sont prudents à ce sujet, et la section 6.2 de l'article est une liste honnête de conseils que leurs données ne soutiennent pas, y compris, précisément, les affirmations selon lesquelles la documentation devrait être exploitable ou vérifiable. Leur observation de validation zéro est ce qu'elle est : une absence mesurée, pas une preuve qu'une documentation exécutable fonctionne mieux. Personne n'a encore mesuré ça.
Nous fonctionnons sur le même instinct pour une raison antérieure à l'article. La règle voulant qu'aucun texte de notre groupe parent ne contienne de tiret cadratin n'est pas une ligne dans un guide de style. C'est un hook qui bloque l'écriture. La règle voulant qu'une migration de base de données soit appliquée par un humain avant la fusion n'est pas un paragraphe, c'est une barrière sur le pipeline. Chaque règle que nous avons écrite sous forme de phrase, en espérant qu'elle tienne, a fini par être brisée, discrètement, par un agent bien intentionné qui faisait de son mieux.
# comme phrase, dans CLAUDE.md : respectée au moment de la génération, ou pas du tout
Pas de tirets cadratins. Utilisez deux-points, virgule, parenthèses ou deux phrases.
# comme vérification, dans .git/hooks/pre-commit : elle bloque l'écriture
grep -nP '\x{2014}' "$FILE" && exit 1Écrire la règle, c'est la communiquer. La câbler dans une vérification, c'est l'appliquer. Cette étude ne nous a pas appris ça, mais c'est la première chose que nous ayons vue qui explique le mécanisme : il n'y a aucune étape d'audit dans la boucle pour que la prose soit auditée.
Les notes que votre agent laisse derrière lui.
Le quart de tout le trafic documentaire qui va aux notes de travail des agents est le constat pour lequel personne n'a de processus. Les agents s'écrivent des plans, des journaux et des notes de révision à eux-mêmes, et ces fichiers restent. La lecture qu'en fait l'article est convaincante : une fenêtre de contexte limitée fait de la documentation une forme de mémoire de travail plutôt que de référence. L'agent note les choses parce qu'il va les oublier, exactement comme une personne avec un calepin dans une longue réunion.
La conséquence est une surface de maintenance arrivée sans catégorie. Les outils d'hygiène du dépôt ne savent pas ce qu'est un plan d'agent périmé. Les listes de vérification de revue de code n'ont pas de ligne pour ça. Ce n'est pas du code source, pas de la documentation, pas de la configuration, et ça s'accumule. Toute flotte qui fait tourner des agents à quelque échelle que ce soit a ça, la nôtre y compris : registres de phase, notes de session, plans commités aux côtés du travail qu'ils décrivaient. Personne ne les a audités.
Aucune des réponses proposées ici n'est coûteuse. Il s'agit surtout d'une réallocation de l'effort que vous dépensez déjà :
- Dépensez le budget de documentation sur le fichier d'instructions.
Il porte à lui seul 35,4 % du trafic. L'exactitude, la précision et l'actualité de ce seul fichier valent mieux qu'un site de référence bien organisé que votre agent ouvre 1,3 % du temps. Révisez-le comme vous révisez du code.
à faire · traiter CLAUDE.md / AGENTS.md comme un artefact révisé - Faites en sorte que chaque page porte sa propre charge utile.
Aucun renvoi n'a été suivi dans leurs traces, pas une seule fois. Si une contrainte compte sur une page, écrivez-la sur cette page plutôt que de créer un lien vers où elle vit. La redondance entre documents est un coût qui vaut la peine d'être payé ici.
à faire · intégrer le détail porteur directement, ne pas y créer de lien - Si une règle doit tenir, rendez-la exécutable.
Un hook, une règle de lint, un schéma, un test. Gardez la phrase pour les humains qui ont besoin du raisonnement, et placez l'application ailleurs, quelque part où ça peut échouer. Traitez ceci comme une posture, pas comme un résultat prouvé : l'étude a mesuré l'absence de validation, elle n'a pas mesuré le correctif.
à faire · convertir vos trois règles les plus critiques en vérifications - Donnez aux notes de travail des agents un foyer et une catégorie de révision.
Décidez où vivent les plans et les journaux, s'ils sont commités, et qui les élague. Le quart du trafic documentaire de votre agent va à des fichiers que rien dans votre processus ne possède actuellement.
à faire · ajouter les notes d'agent à la liste de vérification d'hygiène du dépôt - Gardez la prose de référence, et écrivez-la pour des humains.
Le constat, c'est que les agents lisent à peine les références API. Ça ne veut pas dire que les références ne valent rien. Vos développeurs, vos fournisseurs, et la personne qui arrivera le trimestre prochain en ont encore besoin. Arrêtez seulement de justifier cette dépense comme un investissement de préparation pour les agents.
à faire · budgéter séparément la documentation humaine et la documentation agent
Ce que ceci n'autorise pas.
L'étude est observationnelle et ses limites sont énoncées franchement par les auteurs, ce qui est la principale raison de faire confiance aux parties qui tiennent. Deux jeux de données publics, chacun dominé par une seule famille d'agents, donc ceci n'est pas un sondage sur le comportement de tous les agents. L'heuristique de stade qu'ils utilisent est persistante, si bien que la part des interactions qu'ils attribuent au débogage est gonflée par construction, et ils n'avancent que l'affirmation négative que l'usage de la documentation ne se limite pas à l'orientation. Les traces d'appels d'outils sont aveugles à toute lecture ou comparaison se produisant à l'intérieur du raisonnement du modèle, ce qui signifie que chaque zéro de cette note est un zéro d'action observable, pas de pensée. Les agents qui atteignent des fichiers par le shell sont sous-comptés. Et c'est une mesure du comportement, pas des résultats : ça vous dit ce que font les agents, pas ce qu'ils feraient mieux avec autre chose.
La seule extrapolation à surveiller est celle que nous avons signalée au début. Les deux jeux de données concernent des agents de codage travaillant dans des dépôts, où un fichier d'instructions est un concept natif. Qu'un agent de support client ou un agent de recherche montre la même préférence de 27 contre 1 reste non testé. La tendance est assez plausible pour en tenir compte dans vos plans, et assez mince pour que vous deviez la vérifier dans vos propres journaux avant d'y parier un budget.
Si vous mettez en place des agents IA sur votre propre base de code ou votre espace de travail et que vous voulez un second regard sur le fichier d'instructions, l'hygiène des notes, et lesquelles de vos règles devraient être un hook plutôt qu'une phrase, le formulaire de contact est le chemin le plus rapide. Nous vous renverrons une lecture écrite de votre dispositif, gratuitement.