Écrire AGENTS.md et CLAUDE.md : ce que font 100 dépôts

À quoi servent AGENTS.md et CLAUDE.md ?

Un agent de codage commence chaque session sans rien savoir du projet. Le fichier de règles est l’endroit où vous écrivez une fois pour toutes ce que vous auriez sinon à réexpliquer à chaque session : les commandes de build et de test, les conventions de code, l’arborescence, tout ce qui est « à ne jamais faire ». Cet article explique comment écrire ce fichier : quel nom lui donner, quoi y mettre, quelle longueur viser.

AGENTS.md n’appartient à aucun outil en particulier. C’est un format ouvert, porté par l’Agentic AI Foundation, rattachée à la Linux Foundation ; d’après son propre site, plus de 60.000 projets open source l’utilisent. C’est un simple fichier Markdown, sans champ obligatoire. CLAUDE.md, lui, est le fichier que Claude Code lit au début de chaque session. C’est aussi du Markdown simple, avec quelques fonctions en plus : il peut importer d’autres fichiers (@chemin) et avoir des couches propres à l’utilisateur ou à l’organisation.

Nous construisons un outil qui lit ces fichiers tous les jours : quand diffox examine une pull request, il lit aussi le fichier de règles du dépôt (son fonctionnement fait l’objet d’un autre article). Les mesures qui suivent sont un sous-produit de ce travail.

Quel outil lit quel fichier ?

Nous avons établi le tableau ci-dessous le 13 octobre 2026, à partir de la documentation de chacun des cinq outils. Il peut changer avec les nouvelles versions ; le nom de chaque outil renvoie à sa source.

Source : la documentation de chaque outil, 13 octobre 2026. La ligne Claude Code vaut pour la version 2.1.277 et les suivantes.

Deux choses ressortent du tableau. D’abord, les cinq outils savent tous lire AGENTS.md : Gemini CLI avec un réglage, Claude Code seulement s’il n’a pas de CLAUDE.md à côté. Ensuite, chaque outil traite les sous-dossiers à sa façon : Codex concatène tout depuis la racine, Copilot prend le fichier le plus proche, et Claude Code ne charge le fichier d’un sous-dossier que lorsqu’un fichier de ce dossier est ouvert.

Le 18 juin 2026, Google a cessé de servir Gemini CLI aux utilisateurs gratuits et aux abonnés Google AI Pro et Ultra, et les a orientés vers Antigravity CLI ; avec une clé d’API payante ou une licence d’entreprise, vous pouvez continuer à utiliser Gemini CLI. Nous avons lu la documentation d’Antigravity sur les règles le 28 octobre 2026. Antigravity lit un fichier nommé AGENTS.md ou GEMINI.md sans aucun réglage. Il charge le fichier d’un sous-dossier dès que l’agent lit ou modifie un fichier de ce dossier. Il combine les fichiers qu’il trouve ; si des règles se contredisent, c’est celle du sous-dossier qui l’emporte. La limite est de 24 Ko par fichier. CLAUDE.md ne figure pas parmi les fichiers que cite la documentation ; si vos règles sont dans AGENTS.md, Antigravity les lit aussi.

AGENTS.md est plus répandu que CLAUDE.md

Pour voir quel fichier est le plus répandu, nous avons choisi les dépôts selon un seul critère : les 100 dépôts les plus étoilés de GitHub, au 13 octobre 2026. Une bonne partie de la liste n’est pas du logiciel qu’on compile (listes de ressources, livres, cours). Comme nous les avons choisis sans regarder s’ils avaient un fichier de règles, nous avons gardé la liste telle quelle.

Sur les 100 dépôts, 47 ont au moins un de ces deux fichiers à la racine. On trouve AGENTS.md dans 42 dépôts, CLAUDE.md dans 24 ; le nombre de dépôts qui n’ont qu’un CLAUDE.md est de 5. Les fichiers propres aux autres outils sont plus rares : celui de Copilot est dans 11 dépôts, le dossier de règles de Cursor dans 4, GEMINI.md dans 3. L’ancien fichier .cursorrules subsiste dans 1 dépôt ; .windsurfrules et .clinerules n’apparaissent nulle part.

En comptant aussi les fichiers des sous-dossiers et ceux des autres outils, le nombre de dépôts qui en ont au moins un passe à 55.

Si les deux fichiers sont là, Claude Code ne lit que CLAUDE.md

C’est le point le plus souvent mal compris. Pendant longtemps, Claude Code n’a pas lu AGENTS.md du tout ; beaucoup de sources l’écrivent encore aujourd’hui. Il le lit depuis la version 2.1.277, à une condition : qu’il n’y ait pas de CLAUDE.md (ni de CLAUDE.local.md) dans le dossier de travail ou dans ses dossiers parents. Quand les deux sont présents, le comportement par défaut est de ne lire que CLAUDE.md.

Concrètement : si un CLAUDE.md se trouve à côté, une règle que vous ajoutez à AGENTS.md n’atteint pas Claude Code. Codex, lui, ne lit par défaut qu’AGENTS.md. Vous devez donc garder les deux fichiers synchronisés à la main.

Le CLAUDE.local.md que vous ajoutez pour vos notes personnelles a le même effet : tant que ce fichier existe, Claude Code ne lit pas AGENTS.md. Pour qu’il lise les deux, réglez « Project instructions » sur claude-md-and-agents-md dans /config.

Dans 19 des 100 dépôts, les deux fichiers sont ensemble à la racine. Nous avons regardé un par un comment ces dépôts relient les deux.

Parmi eux, 8 font pointer CLAUDE.md directement vers AGENTS.md : 5 en écrivant @AGENTS.md dans CLAUDE.md, 3 par un lien symbolique. Chez n8n, AutoGPT, RustDesk et Clash Verge Rev, CLAUDE.md tient en une seule ligne. Dans 2 dépôts, CLAUDE.md renvoie à AGENTS.md par une simple phrase ; d’après la documentation de Claude Code, l’agent ne voit ce fichier que s’il décide de l’ouvrir. Dans 3 dépôts, le même texte est copié dans les deux fichiers, et dans 1 cas, les deux copies n’ont plus le même nombre de règles. Dans les 6 derniers, les deux fichiers contiennent des textes distincts : Claude Code et Codex y lisent des instructions différentes pour le même projet.

Deux façons de faire pointer CLAUDE.md vers AGENTS.md

Les données vont dans le même sens : gardez les règles dans un seul fichier et faites pointer l’autre vers lui. Mettez le texte principal dans AGENTS.md, puisque plus d’outils le lisent, et placez à côté ce CLAUDE.md :

@AGENTS.md

## Claude Code
Vos notes propres à Claude Code ici.

La ligne d’import charge AGENTS.md comme une partie de CLAUDE.md ; en dessous, vous n’écrivez que les notes propres à Claude Code. Si vous n’avez pas de telles notes, un lien symbolique fait aussi l’affaire : ln -s AGENTS.md CLAUDE.md.

Le lien symbolique a deux inconvénients. Quelqu’un qui clone le dépôt sous Windows peut voir, à la place du lien, un fichier texte d’une ligne. Et Claude Code refuse d’écrire à travers le lien : il modifie le fichier réel. Si quelqu’un dans l’équipe utilise Windows, la ligne d’import est plus sûre.

Ne garder qu’AGENTS.md est aussi une option désormais, puisque les versions récentes de Claude Code le lisent directement. Laisser le CLAUDE.md d’une ligne pour les anciennes versions ne coûte rien : Claude Code ne charge pas deux fois le même fichier.

Ce que les dépôts populaires mettent dans le fichier

Pour voir ce qu’on écrit dans ce fichier, nous avons regardé les titres des 47 fichiers lus. Quand un fichier consacre un titre à un sujet, nous avons compté qu’il traite ce sujet.

Le sujet le plus fréquent est celui des règles de commit et de pull request (29 fichiers). Viennent ensuite les commandes d’installation et d’exécution (26), le style de code (26), l’arborescence (21), les tests (16) et la sécurité (7). Indépendamment des titres, 36 des 47 fichiers contiennent une commande, dans un bloc de code ou en ligne. Ce comptage ne regarde que les mots des titres : la mesure est grossière, mais l’ordre est clair. L’agent veut d’abord savoir quoi lancer et comment, et comment livrer son changement.

Deux bons exemples, chez Kubernetes et AutoGPT

Les deux exemples font partie des fichiers lus pour ce comptage. L’AGENTS.md de Kubernetes fait 38 lignes. Chaque règle dit ce qu’il ne faut pas faire et ce qu’il faut faire à la place ; chaque commande est accompagnée de son usage :

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

L’AGENTS.md d’AutoGPT fait 92 lignes ; il décrit l’arborescence, la commande de test de chaque partie et des règles de pull request mesurables. Son CLAUDE.md, lui, se réduit à la ligne @AGENTS.md : le lien que nous recommandons plus haut.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

Les deux fichiers sont écrits en phrases qu’un agent comme un humain peut vérifier : « ne pas modifier à la main un fichier généré, lancer make update » ou « les changements hors périmètre restent sous un cinquième de la pull request ». Les extraits viennent du commit lu par le comptage ; « … » marque les lignes omises.

Un modèle d’AGENTS.md pour démarrer

Un squelette d’AGENTS.md court, tiré des titres que les dépôts populaires ouvrent le plus souvent et des deux exemples ci-dessus. Ce n’est qu’un exemple ; nous l’avons écrit en anglais, parce que les agents qui lisent ces fichiers et la plupart des équipes travaillent en anglais. Remplacez les commandes et les chemins par ceux de votre projet :

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

Si vous utilisez Claude Code, placez à côté le CLAUDE.md d’une ligne : @AGENTS.md. Chaque ligne du modèle est une commande ou une règle vérifiable ; dire ce que fait le projet, c’est le rôle du README.

Comment écrire une bonne règle

Sur ce qu’il faut écrire dans le fichier, le critère le plus utile est celui de la documentation de Claude Code : une instruction doit être assez concrète pour être vérifiée. « Utiliser une indentation de 2 espaces » plutôt que « bien formater le code » ; « lancer npm test avant le commit » plutôt que « tester ses changements ». Voici six points qui associent ce critère à ce que nous avons appris en écrivant notre propre fichier :

• Dites à l’agent quoi faire. Une phrase qui dit « fais ceci » ou « ne fais jamais cela » se vérifie ; une présentation du projet, non. Sur les 47 fichiers lus, 3 n’en contiennent aucune ; le fichier médian en compte 10.
• Écrivez la commande telle quelle. De « lancer les tests », l’agent ne peut pas deviner quelle commande vous voulez dire ; écrivez pnpm test --filter api, et c’est elle qu’il lance.
• Écrivez la raison à côté de la règle. Dans notre propre fichier, chaque règle est accompagnée de l’erreur qui l’a fait écrire. Une règle dont la raison n’est pas écrite est supprimée par le premier qu’elle dérange.
• N’écrivez pas ce que vos outils vérifient déjà. Ajouter au fichier une règle que le formateur ou le linter contrôle déjà gaspille des lignes ; plus le fichier s’allonge, moins les instructions sont suivies.
• Écrivez chaque règle à un seul endroit. Si la même règle figure dans deux fichiers, l’une des deux copies vieillit, et c’est celle du fichier le moins lu.
• Ajoutez quand une erreur se répète, supprimez quand la règle ne sert plus. Écrivez la règle quand l’agent fait la même erreur une deuxième fois. Dans Claude Code, /doctor prompt-audit liste les instructions périmées et contradictoires.

Le premier de ces points compte directement pour diffox. Quand il examine une pull request, diffox lit le fichier de règles à la racine du dépôt : d’abord AGENTS.md, sinon CLAUDE.md. Il suit aussi le lien symbolique et la ligne @AGENTS.md. Les phrases qui disent quoi faire sont transmises aux agents spécialisés comme règles de review. Une règle vérifiable sert donc aussi à la review.

La plupart des fichiers de règles font moins de 200 lignes

Pour la longueur, la documentation de trois outils donne trois limites différentes. Claude Code vise moins de 200 lignes par fichier, car un fichier long consomme plus de contexte et l’agent suit moins bien les instructions. Cursor recommande moins de 500 lignes par règle. Codex arrête d’ajouter des fichiers quand leur total atteint 32 Kio.

Sur les 47 fichiers lus, la médiane est de 92 lignes ; le plus court en fait 4, le plus long 1.017. Parmi eux, 14 dépassent 200 lignes et 2 dépassent 500 lignes. Le nombre de fichiers qui dépassent à eux seuls la limite de 32 Kio de Codex est de 1.

Dans un monorepo, un sous-dossier a son propre fichier de règles

Les grands dépôts ne font pas tenir leurs règles dans un seul fichier. Sur les 98 dépôts dont nous avons pu lire toute l’arborescence, 27 ont aussi un AGENTS.md ou un CLAUDE.md dans un autre dossier que la racine : 278 fichiers au total.

Le fichier d’un sous-dossier s’applique aux changements faits dans ce dossier : les règles du front-end vivent dans le dossier du front-end, celles du back-end dans le back-end. Le fichier racine reste court, et l’agent ne charge que les règles de l’endroit où il travaille.

Une de nos propres mesures, de septembre 2026, montre à quelle fréquence cela sert : dans 17 dépôts qui ont un fichier de règles dans un sous-dossier, 202 des 417 dernières pull requests fusionnées modifiaient au moins un fichier dans un tel dossier.

Attention toutefois : chaque outil traite les sous-dossiers à sa façon. Si vous écrivez le même sujet de deux façons à deux niveaux, la phrase qui s’applique dépend de l’outil. Ne laissez pas de phrases qui se contredisent.