Quelle longueur pour un fichier CLAUDE.md ?

La recommandation d’Anthropic est de viser moins de 200 lignes par fichier. Le fichier est chargé dans le contexte au début de chaque session : plus il est long, plus il coûte de tokens et, en pratique, moins l’agent le suit de façon fiable.

Quelle différence entre CLAUDE.md et AGENTS.md ?

Ils jouent le même rôle. CLAUDE.md est le fichier que lit Claude Code ; AGENTS.md est un format ouvert lu par Codex, Gemini CLI (une fois configuré), Cursor, Copilot, opencode, Aider, goose et bien d’autres. Les versions récentes de Claude Code lisent aussi AGENTS.md quand il n’y a pas de CLAUDE.md.

Puis-je utiliser un seul fichier d’instructions pour Claude Code, Codex et Gemini CLI ?

Oui. Gardez les règles communes dans AGENTS.md, placez à côté un CLAUDE.md contenant la ligne @AGENTS.md (plus d’éventuelles notes propres à Claude), et réglez context.fileName dans les réglages de Gemini CLI pour inclure AGENTS.md.

Faut-il commiter CLAUDE.md dans git ?

Le CLAUDE.md du projet, oui : c’est un savoir d’équipe partagé. Les préférences personnelles vont dans ~/.claude/CLAUDE.md ou dans CLAUDE.local.md, que vous ajoutez à .gitignore.

CLAUDE.md garantit-il que l’agent suit une règle ?

Non. C’est du contexte, pas de l’application stricte. L’agent suit généralement les règles claires et précises, mais si une action ne doit jamais avoir lieu, bloquez-la avec un hook ou un réglage de permissions plutôt qu’avec une phrase dans CLAUDE.md.

Bonnes pratiques CLAUDE.md (et AGENTS.md, GEMINI.md)

Le meilleur CLAUDE.md est court (bien sous 200 lignes), précis et vérifiable : les commandes pour compiler et tester, les conventions que l’agent ne peut pas deviner à partir du code, et les erreurs qu’il a déjà commises une fois. Tout le reste, comme une visite de l’arborescence, de longues procédures ou des conseils généraux du type « écris du code propre », a sa place ailleurs ou n’en a aucune.

Ce guide présente ce que sont CLAUDE.md, AGENTS.md et GEMINI.md, où chaque agent les cherche, quoi écrire et quoi laisser de côté, comment fonctionnent les imports, et comment garder un seul fichier que tous les agents du projet lisent.

Ce que sont ces fichiers

Les agents de code démarrent chaque session sans aucune mémoire de votre projet. Un fichier d’instructions est la note que vous leur laissez : un simple fichier Markdown que la CLI lit au lancement et ajoute à la fenêtre de contexte du modèle avant votre premier message.

Fichier	Lu par	Remarques
`CLAUDE.md`	Claude Code	Gère les imports `@path` et les règles limitées à des chemins
`AGENTS.md`	Codex, Cursor, Copilot, opencode, Aider, goose, Amp, Gemini CLI (si configuré) et d’autres	Un format ouvert, souvent appelé « un README pour agents »
`GEMINI.md`	Gemini CLI	Gère les imports `@file.md` ; le nom du fichier est configurable

AGENTS.md est né d’une collaboration entre OpenAI Codex, Amp, Google Jules, Cursor et Factory, et est désormais piloté par l’Agentic AI Foundation, sous l’égide de la Linux Foundation. C’est ce qui se rapproche le plus d’un standard commun. Claude Code a gardé son propre nom, mais les versions récentes (v2.1.277 et suivantes) lisent AGENTS.md nativement quand il n’y a ni CLAUDE.md ni CLAUDE.local.md dans le répertoire de travail ou au-dessus.

Où vivent les fichiers

Les trois agents suivent la même idée : un fichier global pour vous, un fichier de projet pour l’équipe, et des fichiers optionnels plus profonds dans l’arborescence pour une partie du code.

Claude Code

Portée	Emplacement	Partagé ?
Politique gérée	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	Défini par un administrateur pour tous
Utilisateur	`~/.claude/CLAUDE.md`	Vous seul, tous les projets
Projet	`./CLAUDE.md` ou `./.claude/CLAUDE.md`	Commité, toute l’équipe
Local	`./CLAUDE.local.md`	Vous seul ; ajoutez-le à `.gitignore`
Imbriqué	`src/payments/CLAUDE.md` et ainsi de suite	Chargé quand Claude lit ou modifie des fichiers à cet endroit

Les fichiers du répertoire de travail et des répertoires parents se chargent au lancement et sont concaténés, pas remplacés. Les fichiers imbriqués dans les sous-répertoires se chargent à la demande, la première fois que Claude touche des fichiers de ce dossier. Lancez /context pour voir quels fichiers de mémoire sont réellement chargés, et /memory pour en ouvrir un en édition.

Codex

Codex lit un ~/.codex/AGENTS.md global (ou AGENTS.override.md), puis descend de la racine git jusqu’au répertoire courant en prenant un fichier par dossier : AGENTS.override.md s’il existe, sinon AGENTS.md. Les fichiers plus profonds viennent plus tard dans le texte combiné, et l’emportent donc quand deux règles se contredisent. Le total est plafonné par project_doc_max_bytes, 32 KiB par défaut, et la chaîne est construite une fois par session. Plus de détails sur la CLI elle-même sur la page Codex.

Gemini CLI

Gemini CLI charge ~/.gemini/GEMINI.md, puis les fichiers des répertoires de votre espace de travail et de leurs parents, et récupère d’autres fichiers quand ses outils visitent d’autres dossiers. Le tout est concaténé et envoyé avec chaque prompt. /memory show affiche le texte combiné et /memory reload le relit après modification.

Quoi y mettre

Écrivez pour un nouveau coéquipier compétent qui n’a jamais vu le dépôt et ne posera pas de questions. Chaque ligne doit être quelque chose que l’agent peut appliquer et que vous pouvez vérifier.

Les commandes. Comment installer, compiler, lancer un test, lancer tous les tests, linter et vérifier les types. C’est la section la plus utile ; sans elle, l’agent devine.
Les conventions que le code ne montre pas. « Utilise pnpm, pas npm. » « Les nouvelles routes d’API passent par withAuth(). » « Les dates sont stockées en UTC. »
Les limites. « Ne modifie jamais les fichiers sous generated/. » « Ne touche pas au dossier des migrations sans demander. »
Comment terminer une tâche. « Lance pnpm test et pnpm typecheck avant de dire que tu as fini. » « Les messages de commit suivent Conventional Commits. »
Les pièges connus. L’erreur que l’agent a faite deux fois la semaine dernière, formulée comme une règle.

Une bonne règle est concrète. « Utilise une indentation de 2 espaces » fonctionne ; « formate correctement le code » non. « Lance npm test avant de commiter » fonctionne ; « assure-toi que tout marche » non.

Un exemple compact

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

Cela fait une vingtaine de lignes, et couvre l’essentiel de ce dont un agent a besoin dès le premier jour.

Quoi laisser de côté

À omettre	Pourquoi	À mettre plutôt ici
Une visite fichier par fichier du dépôt	L’agent peut lister les dossiers lui-même, et la visite devient obsolète	Rien, ou un outil de carte du code
De longues procédures pas à pas (release, migrations)	Chargées à chaque tour même si inutilisées	Un skill ou un document vers lequel le fichier pointe
Des règles pour un seul dossier	Coûtent du contexte partout	Un CLAUDE.md / AGENTS.md imbriqué, ou `.claude/rules/` avec `paths:`
Des conseils génériques (« écris du code propre »)	Aucun effet sur le comportement	Supprimez-les
Secrets, tokens, URL internes	Le fichier est commité et envoyé au modèle	Variables d’environnement
Ce qui ne doit jamais arriver	Les instructions sont du contexte, pas de l’application stricte	Un hook ou une règle de permission

Rester court

Chaque ligne de CLAUDE.md est envoyée au début de chaque session et reste dans le contexte pendant toute la conversation. La documentation d’Anthropic suggère de rester sous 200 lignes par fichier, et note que des fichiers plus longs réduisent la fiabilité avec laquelle Claude les suit. Le schéma est connu : plus il y a de règles, plus chacune se dilue.

Quelques habitudes aident :

N’ajoutez une règle que lorsque vous en avez besoin. L’agent a fait deux fois la même erreur, une revue a relevé quelque chose, ou vous retapez sans cesse la même correction. C’est le signal.
Élaguez en ajoutant. Si une règle n’a pas compté depuis un mois, supprimez-la.
Préférez les pointeurs au copier-coller. « Le processus de release est dans docs/release.md » coûte une ligne ; coller le processus en coûte cinquante.
Utilisez des commentaires HTML pour les notes aux humains. Claude Code retire les commentaires  de niveau bloc avant d’envoyer le fichier.

Si le coût en tokens vous préoccupe, le guide de l’usage de tokens de Claude Code détaille ce qui remplit encore le contexte.

Imports et règles limitées à des chemins

Claude Code permet à un CLAUDE.md d’inclure d’autres fichiers avec @path :

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Les chemins sont relatifs au fichier qui contient l’import, les imports peuvent s’imbriquer sur quatre niveaux, et un @ dans des extraits de code ou des blocs de code est ignoré. La première fois qu’un projet importe des fichiers extérieurs au dépôt, Claude Code vous demande de les approuver.

Un piège : les imports organisent le texte, mais n’économisent pas de tokens. Un fichier importé est chargé en entier au lancement, comme le fichier parent. Pour les règles qui ne comptent que dans une partie de l’arborescence, utilisez .claude/rules/*.md avec un glob paths: dans le frontmatter, afin qu’elles ne se chargent que lorsque Claude travaille sur des fichiers correspondants :

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

Gemini CLI gère la même syntaxe d’import @file.md dans GEMINI.md.

Un seul fichier pour tous les agents

Si votre équipe utilise plus d’une CLI, maintenir trois fichiers avec les mêmes règles est le meilleur moyen de les voir diverger. La configuration habituelle :

Mettez les règles communes dans AGENTS.md. Codex, Cursor, Copilot, opencode et la plupart des autres le lisent directement.

Créez un CLAUDE.md qui l’importe et ajoute ce qui est propre à Claude :

@AGENTS.md

## Claude Code only
- Use the project's /review skill before opening a PR.

Dans Gemini CLI, ajoutez AGENTS.md aux noms de fichiers recherchés, dans .gemini/settings.json :
```
{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }
```

Un lien symbolique (ln -s AGENTS.md CLAUDE.md) fonctionne aussi sur macOS et Linux, mais l’approche par import est plus claire et ne dépend pas de la façon dont Windows gère les liens. Claude Code a aussi un réglage « Project instructions » dans /config si vous voulez qu’il lise CLAUDE.md et AGENTS.md ensemble.

Écrire la première version

Inutile de partir d’une page blanche. Dans Claude Code, /init lit le dépôt et rédige un brouillon de CLAUDE.md. Traitez ce brouillon comme une matière première : gardez les commandes, supprimez la visite des dossiers, et retirez tout ce que vous ne diriez pas à un nouveau coéquipier le matin de son arrivée.

Laissez ensuite le fichier grandir à partir du travail réel. Chaque fois que vous corrigez l’agent, demandez-vous si la correction vaudrait aussi la semaine prochaine. Si oui, c’est une règle candidate.

Avec AgentVera

AgentVera lance Claude Code, Codex, Gemini CLI et d’autres CLI côte à côte dans de vrais terminaux. Chaque agent lit toujours son propre CLAUDE.md, AGENTS.md ou GEMINI.md exactement comme décrit plus haut ; AgentVera ne remplace pas ces fichiers. Quelques fonctions travaillent à leurs côtés :

Suggestions de règles à partir de vos corrections. Quand vous renvoyez le travail d’un agent depuis la boîte de revue avec une note, ou que Verify trouve un critère non satisfait, un petit modèle Claude transforme la correction en une règle courte. Elle apparaît sous Rule suggestions ; Add to instructions l’ajoute au CLAUDE.md et à l’AGENTS.md du projet (ceux qui existent), et les règles déjà présentes dans les fichiers sont ignorées. Si aucun des deux fichiers n’existe, il crée AGENTS.md et un CLAUDE.md qui l’importe avec @AGENTS.md.
Des rôles par agent plutôt qu’un fichier commun surchargé. Le champ « Role and instructions » de la boîte de dialogue de l’agent est donné à cet agent seul (Claude le reçoit ajouté à son prompt système, Codex comme instructions de développeur). Les rôles propres à un agent restent hors du fichier commun. Cursor, Gemini CLI et Amp n’utilisent pas ce champ et s’appuient plutôt sur l’AGENTS.md du projet ou sur des fichiers de règles.
Une carte du code, pour éviter la visite des dossiers. La carte du projet est construite en local et proposée aux agents comme outils MCP (map_related, map_outline, map_usages et d’autres), et les nouveaux agents reçoivent un court résumé des modules, des points d’entrée et de la commande de test. C’est la partie que les gens collent souvent à la main dans CLAUDE.md.
Mémoire du projet. AgentVera Brain lit vos documents suivis par Git, dont CLAUDE.md et AGENTS.md, ainsi que les commits, les PR et les conversations passées, et suit quelles décisions sont à jour ou périmées. Un pack de contexte optionnel (désactivé par défaut) peut être ajouté aux instructions des nouveaux agents.
Des procédures sous forme de skills. La galerie de skills gère les dossiers SKILL.md pour Claude Code et Codex, là où les longues procédures ont leur place.
Des règles qui doivent toujours s’exécuter. CLAUDE.md est un conseil ; pour les vérifications qui doivent avoir lieu à chaque fois, utilisez les hooks Claude Code, et déléguez les tâches annexes ciblées à des sous-agents.

Check-list

Moins de 200 lignes ; idéalement moins de 100.
Les commandes de build, test, lint et vérification des types sont listées et correctes.
Chaque règle est assez précise pour être vérifiée.
Pas de visite de dossiers, pas de secrets, pas de conseils génériques.
Les règles propres à un dossier sont dans des fichiers imbriqués ou des règles limitées à des chemins.
Les longues procédures sont dans des skills ou des documents, liés par une seule ligne.
Les limites strictes sont appliquées avec des hooks ou des permissions, pas de la prose.
Les règles communes vivent dans AGENTS.md ; CLAUDE.md l’importe.
Les préférences personnelles sont dans ~/.claude/CLAUDE.md ou CLAUDE.local.md.

Pour conclure

Un fichier d’instructions est le moyen le moins cher de faire se comporter un agent comme s’il avait déjà travaillé sur votre projet. Gardez-le court, gardez-le concret, et laissez-le grandir uniquement à partir d’erreurs que vous avez réellement vues. Mettez les règles communes dans AGENTS.md pour que chaque CLI lise la même chose, déplacez les procédures dans des skills, et faites respecter l’essentiel avec des hooks plutôt que des phrases.