AGENTS.md ou CLAUDE.md ? Quels contiennent réellement ces 592 dépôts de premier plan ?

Le guide de cycle de vie de développement nativement basé sur l’IA d’Anthropic réorganise les six étapes de la livraison de logiciels autour d’agents de codage. L’étape 3 exige la création d’un artefact concret : CLAUDE.md, un fichier de connaissances au niveau du répertoire qui est mis à jour chaque fois qu’un agent commet la même erreur. Une enquête menée sur les répertoires publics les plus populaires a permis de déterminer dans quelle mesure ces conseils sont mis en pratique, et la réponse est surprenante. CLAUDE.md l’emporte en nombre de fichiers mais perd en contenu.

Les chiffres clés

Le 8 septembre 2026, une étude a porté sur les 592 répertoires les plus populaires, sélectionnés parmi six langages (TypeScript, Python, Go, Rust, Java et JavaScript, après suppression des doublons). Elle a cherché CLAUDE.md ainsi que plusieurs fichiers associés.

• 165 répertoires (27,9 %) contiennent un CLAUDE.md.
• 94 de ces 165 (57,0 %) ne contiennent absolument aucune connaissance relative au répertoire. Il s’agit de redirections.

Sur ces 165, 94 (57,0 %) ne possèdent aucune connaissance relative aux dépôts. Il s’agit de redirections.

209 dépôts, soit 35,3 %, contiennent un fichier AGENTS.md, et 93,8 % d’entre eux présentent du contenu réel.

Lorsque les deux fichiers existent (132 dépôts), 89 font référence à AGENTS.md depuis CLAUDE.md. Seulement 10 font référence dans l’autre sens.

Seulement 5,9 % disposent d’un fichier .claude/settings.json, endroit où sont configurés les hooks du stade 3 du playbook.

Les fichiers CLAUDE.md substantiels ont une taille médiane de 3 934 octets, et le plus grand atteint 66 176 octets.

En excluant les redirections, seuls 12,0 % des meilleurs dépôts possèdent un CLAUDE.md contenant du contenu. Un AGENTS.md substantiel apparaît dans 33,1 % d’entre eux.

Pour ceux qui adoptent ce guide dès maintenant, les conclusions sont mitigées. Les agents ont effectivement besoin d’un fichier de connaissances fiable et géré en version, mais le guide indique le mauvais fichier. Dans ces dépôts, CLAUDE.md est devenu un intermédiaire de compatibilité placé devant AGENTS.md, un fichier neutre par rapport aux fournisseurs lu par tous les principaux agents de codage. Les projets qui ont déjà résolu ce problème ont enregistré leurs connaissances une seule fois dans AGENTS.md et y ont laissé un lien en une ligne.

Comment le comptage a été effectué

Le cadre d’échantillonnage était une capture du classement public de GitHub, les 100 meilleurs dépôts en fonction du nombre d’étoiles dans chacune des six langues, qui ont été réduits à 592 dépôts uniques après suppression des doublons. Un ensemble fixe de chemins a été demandé depuis raw.githubusercontent.com à l’adresse HEAD, sans clé API, sans authentification et sans scraping. La question portait uniquement sur l’existence d’un fichier et son contenu. Ensuite, tous les fichiers CLAUDE.md et AGENTS.md ont été téléchargés — 374 fichiers répartis sur 242 dépôts — et lus manuellement.

C’est lors de cette lecture que les résultats ont montré des failles. Le CLAUDE.md médian s’est avéré avoir seulement deux lignes, ce qui signifie que 27,9 % en soi ne dit presque rien.

Contenu de ces fichiers

Aucune des formes courantes ne représente une connaissance réelle :

• Un lien symbolique Git. Le fichier fait neuf octets, il s’agit simplement du texte AGENTS.md sans caractère de retour à la ligne final, car Git stocke un lien symbolique sous forme d’un bloc contenant sa cible. openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF et nushell en sont des exemples.
• Une seule ligne d’import, @AGENTS.md, longue de onze octets, que Claude Code traite lors du chargement. n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff et pdf.js fonctionnent de cette manière.
• Une phrase en prose. Dans lazygit, cela correspond à une instruction indiquant de lire d’abord AGENTS.md puis de le suivre. La CLI de Google Workspace exprime la même chose de manière plus détaillée.

Quelques cas limites sont importants pour quiconque crée un classificateur. Docusaurus présente un titre suivi de l’importation et rien d’autre. Jest, quant à lui, fait référence à .github/copilot-instructions.md. Ansible se compose de trois lignes d’importation sans texte explicatif. Zed renvoie vers un fichier nommé .rules.

Après avoir exclu tous les fichiers dont le contenu se résume à une redirection, 71 des 592 dépôts disposent d’un CLAUDE.md contenant des informations sur le dépôt, soit 12,0 %. Ces 71 fichiers sont réels, certains étant de grande taille : médiane à 3 934 octets, 90e percentile à 19 506 octets, maximum à 66 176 octets. Des projets tels que bun, pytorch, swc, gstack et 3x-ui maintiennent de véritables guides opérationnels couvrant les commandes de compilation, les cartes des dépôts, la philosophie de test et les règles applicables aux dossiers.

Où réside réellement cette connaissance

Dans AGENTS.md, et de loin. Son taux de contenu substantiel est de 93,8 %, soit 196 fichiers sur 209, contre 43,0 % pour CLAUDE.md. C’est cette asymétrie qui est révélatrice. Un dépôt qui crée un AGENTS.md le remplit presque toujours de contenu. Un dépôt qui crée un CLAUDE.md construit le plus souvent un lien vers un autre endroit.

Les 132 dépôts qui contiennent les deux fichiers clarifient cette orientation :

• Dans 89 d’entre eux, CLAUDE.md sert de pointeur et AGENTS.md contient le contenu.
• Dans 10, les rôles sont inversés : AGENTS.md fait office de redirection et CLAUDE.md est le vrai fichier. Pytorch, bun, milvus, anki et litellm font partie de ceux-ci.
• 31 dépôts conservent du contenu substantiel dans les deux fichiers, ce qui signifie que les mêmes connaissances institutionnelles sont maintenues deux fois.
• 2 dépôts contiennent des pointeurs dans les deux fichiers, ce qui indique l’existence d’un troisième fichier quelque part.

Les redirections se dirigent donc approximativement dans un rapport de neuf à un vers le fichier neutre par rapport aux fournisseurs. Un résultat unidirectionnel est souvent un artefact de mesure, c’est pourquoi le cas inverse a été recherché délibérément. Il existe bien, mais seulement en minorité.

Adoption par langue

L’écart entre les langages est suffisamment important pour pouvoir en tenir compte dans la planification. CLAUDE.md en premier, AGENTS.md en second :

• TypeScript : 46,5 % et 53,5 %.
• Rust : 33,3 % et 43,4 %.
• Go : 32,3 % et 37,4 %.
• Python : 25,5 % et 31,6 %.
• JavaScript : 19,0 % et 23,0 %.
• Java : 10,3 % et 22,7 %.

AGENTS.md est prédominant dans toutes les langues. Java présente l’écart le plus marqué, avec des dépôts ayant AGENTS.md deux fois plus souvent que CLAUDE.md, tandis que les projets TypeScript ont quatre fois plus de chances d’avoir CLAUDE.md que ceux en Java. Sur les six langues considérées, 43,2 % des dépôts de premier plan disposent d’un fichier d’instructions pour les agents, que ce soit AGENTS.md, CLAUDE.md, .cursorrules ou le fichier d’instructions de Copilot. Celui de Copilot est présent dans 9,3 % des cas. La convention .cursorrules a presque disparu de ce groupe avec seulement 0,5 % d’usage, ce qui rappelle bien à quel point rapidement une habitude propre à un fournisseur peut disparaître.

Le reste de l’stack Stage-3

Les équipes chargées des plateformes doivent lire attentivement cette partie. Le guide ne se contente pas de demander un fichier de connaissances : il combine des fichiers de connaissances, des compétences et des hooks, et ce sont les hooks qui constituent la couche de contrôle permettant d’empêcher des actions dangereuses pendant les builds.

Seuls 35 des 592 dépôts (5,9 %) possèdent un fichier .claude/settings.json, et seulement 32 (5,4 %) le possèdent en même temps qu’un CLAUDE.md. C’est le document de documentation, qui n’est qu’un fichier que n’importe qui peut écrire, que les gens ont adopté. La couche de contrôle, celle qui modifie réellement ce qu’un agent peut faire, n’existe que dans environ un dépôt sur dix-huit. Un playbook dont la sécurité dépend de hooks décrit quelque chose que presque personne n’a encore créé.

Limites des données

• L’échantillon comprend des dépôts publics classés par nombre d’étoiles. Un playbook de ce type est déployé dans des dépôts d’entreprises privées, qui ne sont pas accessibles. L’adoption y pourrait être plus élevée et plus structurée.

Un fichier ne constitue pas une preuve concrète. Un CLAUDE.md complet montre simplement que quelqu’un l’a écrit, mais il ne prouve ni que quelqu’un le met à jour, ni que les performances de l’agent se sont améliorées. Des études publiées remettent en question l’utilité réelle de ces fichiers pour les agents de codage, et cette mesure ne dit rien à ce sujet.

Le fichier settings.json ne représente qu’un indicateur approximatif des hooks, et non un recensement complet. Tous les hooks définis ailleurs restent invisibles, ce qui fait que 5,9 % représente une valeur minimale.

Le choix entre la frontière basée sur les pointeurs et celle basée sur le contenu relève de l’appréciation. La limite a été fixée à 120 caractères de prose restante après suppression des titres, des importations et des phrases de redirection. Les quatorze fichiers les plus proches de cette limite ont été examinés manuellement, et le fichier le plus proche relevant du contenu réel, lazydocker, contient 172 caractères de vraies flags de construction. Changer ce seuil modifie ce chiffre. Une seconde vérification de 25 répertoires par rapport aux fichiers réels a montré que les erreurs se produisent dans une seule direction : le classificateur classe parfois une redirection comme du contenu réel lorsque celle-ci est formulée comme une instruction adressée à l’agent plutôt que comme une indication de l’emplacement de la documentation, comme c’est le cas pour zeroclaw. Ainsi, 57,0 % représente un minimum, et la part réelle basée sur les pointeurs est légèrement plus élevée.

Il y a aussi une mésaventure à reconnaître. La première analyse indiquait que 27,9 % des principaux dépôts avaient adopté CLAUDE.md, et cette information aurait été publiée. C’est la médiane à deux lignes qui l’a empêchée.

Réponses pratiques

Quel fichier doit contenir le contenu ? Les éléments disponibles penchent en faveur de AGENTS.md, avec CLAUDE.md réduit à un simple lien. La plupart des dépôts utilisant deux fichiers (89 sur 132) font précisément cela. Une seule copie des connaissances reste, et les agents qui ne cherchent jamais un nom de fichier spécifique à Claude peuvent toujours la lire.

Le Claude Code lit-il directement AGENTS.md ? Non, contrairement à CLAUDE.md qui suit une convention de nommage spécifique, et c’est cette différence qui explique l’existence du schéma de pointeur. Deux méthodes fonctionnent en pratique : un lien symbolique git nommé CLAUDE.md qui fait référence à AGENTS.md, ou l’import @AGENTS.md. Le projet new-api met même en garde dans son propre CLAUDE.md sur le fait que cet import ne charge pas toujours de manière fiable, et conseille aux agents d’ouvrir le fichier eux-mêmes.

Un taux d’adoption de 27,9 % est-il bon ou mauvais ? Il est supérieur aux attentes pour une convention si récente, mais inférieur à ce que suggère le playbook. Deux autres chiffres donnent plus d’informations : 12,0 % des répertoires possèdent des fichiers CLAUDE.md contenant du contenu réel, et seuls 5,4 % les accompagnent de hooks de contrôle.

Pourquoi 31 dépôts conserveraient-ils les deux fichiers de manière substantielle ? Aucune mesure n’a jamais été effectuée sur les écarts entre ces copies, ce qui constitue clairement l’objet d’une étude future. Les connaissances institutionnelles redondantes deviennent un fardeau dès lors que les copies diffèrent, et les outils ne donnent aucun avertissement.

D’autres peuvent-ils reproduire cela ? Oui. L’échantillon provient d’un classement public des étoiles, la méthode consiste en des requêtes HTTP non authentifiées vers raw.githubusercontent.com, et le classificateur tient dans environ 40 lignes de code.

Vérification finale pour quiconque gère un dépôt équipé d’un agent de codage : la dernière fois qu’une commande de compilation a changé, le fichier de connaissances de l’agent a-t-il été mis à jour dans le même commit, ou la commande obsolète est-elle réapparue trois sessions plus tard ?