CLAUDE.md et AGENTS.md : les meilleures pratiques
Comment écrire un CLAUDE.md efficace, sa structure idéale, sa longueur, et les différences avec AGENTS.md d'OpenAI. Guide pratique 2026 avec exemples.
Un CLAUDE.md efficace tient sur moins de 200 lignes et ne contient que ce que l’agent ne peut pas deviner seul : commandes de build, conventions, architecture et règles métier. AGENTS.md remplit le même rôle, mais comme format ouvert lu par une vingtaine d’outils (OpenAI Codex, Cursor, Copilot), là où CLAUDE.md est propre à Claude Code.
La question est devenue centrale en 2026 : ces fichiers de configuration déterminent la qualité du travail produit par un agent de codage. Selon la documentation officielle d’Anthropic, un CLAUDE.md trop long « consomme plus de contexte et réduit l’adhérence » de Claude aux instructions. De son côté, AGENTS.md est désormais utilisé par plus de 60 000 projets open source. Voici comment écrire ces fichiers correctement, ce qu’il faut y mettre, et comment gérer les deux écosystèmes sans dupliquer votre travail.
Qu’est-ce qu’un fichier CLAUDE.md
Un CLAUDE.md est un fichier Markdown placé à la racine d’un projet, que Claude Code lit au début de chaque session pour charger des instructions permanentes. Chaque session démarre avec une fenêtre de contexte vierge : le CLAUDE.md est le mécanisme qui transporte la connaissance du projet d’une session à l’autre.
Concrètement, au lieu de répéter « utilise des tabulations de 2 espaces » ou « les handlers d’API sont dans src/api/handlers/ » à chaque conversation, vous écrivez ces règles une fois. C’est une application directe du context engineering au développement : structurer le contexte une bonne fois plutôt que de le ressaisir.
Point important souligné par Anthropic : le CLAUDE.md n’est pas une configuration appliquée de force. Son contenu est injecté comme un message dans le contexte, pas dans le system prompt. Claude le lit et tente de le suivre, sans garantie stricte, surtout si les instructions sont vagues ou contradictoires. Pour bloquer une action quoi qu’il arrive, il faut un hook, pas une ligne dans le CLAUDE.md.
Qu’est-ce qu’AGENTS.md et qui le supporte
AGENTS.md est un format ouvert « pour guider les agents de codage », né d’une collaboration entre OpenAI Codex, Amp, Jules (Google), Cursor et Factory. Il est aujourd’hui supervisé par l’Agentic AI Foundation, sous l’égide de la Linux Foundation.
Sa force est l’interopérabilité : un seul fichier lu par une vingtaine d’outils. La liste inclut OpenAI Codex, Google Jules et Gemini, Cursor, GitHub Copilot (support natif ajouté en août 2025), Windsurf, Zed, Aider, Devin, JetBrains Junie et VS Code. Là où CLAUDE.md est spécifique à un éditeur, AGENTS.md vise le standard transversal.
Le format reste volontairement minimal : du Markdown standard, aucun champ obligatoire, et un support des fichiers imbriqués dans les monorepos (le AGENTS.md le plus proche d’un fichier l’emporte). Les sections les plus courantes recommandées sont les suivantes :
- Vue d’ensemble du projet
- Commandes de build et de test
- Règles de style de code
- Instructions de test
- Considérations de sécurité
- Conventions de commit et de pull request
CLAUDE.md est propre a Claude Code, AGENTS.md est lu par 20+ outils et utilise dans 60 000+ projets open source.
CLAUDE.md vs AGENTS.md : le comparatif
Les deux fichiers servent le même objectif — donner du contexte permanent à un agent — mais ne ciblent pas le même écosystème. Le tableau ci-dessous résume les différences à connaître avant de choisir.
| Critère | CLAUDE.md | AGENTS.md |
|---|---|---|
| Lu par | Claude Code uniquement | Codex, Cursor, Copilot, Gemini, Windsurf, Zed… (20+ outils) |
| Créé par | Anthropic | Collaboration OpenAI, Google, Cursor, Amp, Factory |
| Gouvernance | Anthropic | Agentic AI Foundation (Linux Foundation) |
| Adoption | Écosystème Claude Code | 60 000+ projets open source |
| Format | Markdown, langage naturel | Markdown, aucun champ obligatoire |
| Longueur conseillée | < 200 lignes | 10-20 lignes de règles réelles au départ |
| Fichiers imbriqués | Oui (sous-dossiers) | Oui (le plus proche l’emporte) |
| Interopérabilité | Faible (propre à Claude) | Élevée (standard multi-outils) |
Le point crucial à retenir : Claude Code ne lit pas AGENTS.md. Si votre dépôt contient déjà un AGENTS.md pour Codex ou Cursor, Claude l’ignorera, sauf si vous le lui indiquez explicitement. Je détaille la marche à suivre plus bas.
Un bon CLAUDE.md ne contient que ce que l’agent ne peut pas inferer de votre code.
Comment écrire un CLAUDE.md efficace
Un bon CLAUDE.md ne contient que ce que l’agent ne peut pas inférer de votre code. C’est le principe directeur que j’applique sur tous mes projets. Tout le reste — règles de programmation génériques, bonnes pratiques universelles — encombre le contexte sans rien apporter.
Ce qu’il faut mettre
Ajoutez ce qu’un nouveau coéquipier aurait besoin de savoir pour être productif, et que l’IA ne devine pas seule :
- Les commandes de build et de test précises (
npm test,make lint). - Les conventions de nommage et le style de code propres au projet.
- L’architecture : où vivent les fichiers, comment les modules s’articulent.
- La stack technique et les versions spécifiques si l’environnement est atypique.
- Les règles métier et les choix d’architecture qui s’écartent des pratiques courantes.
- Les règles « toujours faire X » : lancer les tests avant un commit, ne jamais pousser sur main.
Une heuristique simple proposée par Anthropic : ajoutez une entrée au CLAUDE.md dès que Claude fait deux fois la même erreur, ou dès que vous retapez la même correction qu’à la session précédente.
Ce qu’il faut éviter
Trois catégories de contenu nuisent à l’efficacité du fichier :
- Les instructions vagues : « formate bien le code » ne se vérifie pas. Préférez « utilise une indentation de 2 espaces ».
- Les règles génériques que l’IA connaît déjà : inutile d’expliquer ce qu’est une fonction pure ou de rappeler les bonnes pratiques REST.
- Les données variables qui changent en cours de projet : l’IA les traitera comme des consignes valides même quand elles seront obsolètes.
Soignez la structure et la spécificité
Claude scanne la structure d’un fichier comme un lecteur humain : des titres Markdown et des listes à puces sont mieux suivis que des paragraphes denses. La spécificité fait la différence — comparez :
| Instruction faible | Instruction efficace |
|---|---|
| « Formate le code proprement » | « Utilise une indentation de 2 espaces » |
| « Teste tes changements » | « Lance npm test avant chaque commit » |
| « Garde les fichiers organisés » | « Les handlers d’API vivent dans src/api/handlers/ » |
Enfin, traquez les contradictions. Si deux règles se contredisent, Claude en choisira une au hasard. Relisez périodiquement votre CLAUDE.md et les fichiers imbriqués pour retirer les instructions obsolètes ou conflictuelles.
Claude concatene les fichiers de la racine du systeme jusqu’a votre dossier de travail, du plus general au plus specifique.
Où placer le fichier et comment il se charge
L’emplacement du CLAUDE.md détermine sa portée. Claude charge tous les fichiers trouvés en remontant l’arborescence depuis votre dossier de travail, et les concatène dans le contexte, du plus général au plus spécifique.
| Portée | Emplacement | Usage |
|---|---|---|
| Organisation | /etc/claude-code/CLAUDE.md (Linux) | Standards d’entreprise, sécurité, conformité |
| Utilisateur | ~/.claude/CLAUDE.md | Vos préférences sur tous vos projets |
| Projet (partagé) | ./CLAUDE.md ou ./.claude/CLAUDE.md | Règles d’équipe versionnées dans Git |
| Local (privé) | ./CLAUDE.local.md | Préférences perso non versionnées (à mettre en .gitignore) |
Pour les gros projets, deux mécanismes évitent de gonfler le fichier principal. Les CLAUDE.md imbriqués dans les sous-dossiers se chargent à la demande, quand Claude lit un fichier de ce dossier. Le répertoire .claude/rules/ permet de découper les règles par thème (testing.md, security.md) et de les scoper à des chemins précis via un champ paths en frontmatter — elles ne se chargent alors que sur les fichiers correspondants.
La commande /init génère automatiquement un premier CLAUDE.md : Claude analyse le projet et crée un fichier avec les commandes et conventions détectées. C’est le point de départ le plus rapide, y compris pour ceux qui ne codent pas. Pour comprendre la mise en place complète de l’outil, notre guide Claude Code pour débutant détaille l’installation et les premiers pas.
Gérer les deux fichiers sans dupliquer
La meilleure pratique quand on utilise plusieurs agents est de faire d’AGENTS.md le fichier principal, et de le faire importer par CLAUDE.md. C’est le pattern recommandé par la documentation d’Anthropic elle-même, et il évite de maintenir deux jeux de règles séparés.
Concrètement, créez un CLAUDE.md minimal qui pointe vers AGENTS.md, puis ajoutez en dessous les instructions propres à Claude :
@AGENTS.md
## Claude Code
Utilise le plan mode pour les changements sous src/billing/.Claude charge le fichier importé au démarrage, puis ajoute le reste. Si vous n’avez pas d’instruction spécifique à Claude, un simple lien symbolique suffit :
ln -s AGENTS.md CLAUDE.mdSous Windows, le lien symbolique exige des privilèges administrateur : utilisez plutôt l’import @AGENTS.md. Dernière option : lancer /init dans un dépôt contenant déjà un AGENTS.md. Claude le lit et intègre les parties pertinentes dans le CLAUDE.md généré — il sait aussi lire .cursorrules, .windsurfrules et d’autres configs d’outils concurrents.
Mon avis : commencez petit, enrichissez par itération
Après avoir configuré ces fichiers sur plusieurs projets, ma recommandation est claire : ne tentez pas d’écrire un CLAUDE.md parfait dès le départ. Commencez avec 10 à 20 lignes de règles réelles, et laissez l’usage révéler ce qui mérite d’y figurer.
Le réflexe à prendre : chaque fois qu’une revue de code attrape une erreur que l’agent aurait dû connaître, ou qu’une correction revient, ajoutez-la au fichier. C’est ainsi que le CLAUDE.md devient utile sans devenir une décharge d’instructions ignorées. Pour aller plus loin sur la personnalisation de l’outil, le guide complet des Claude Code Skills explique quand sortir une instruction du CLAUDE.md vers un skill dédié.
Le verdict sur le débat CLAUDE.md vs AGENTS.md : ce n’est pas un choix exclusif. Si vous travaillez avec un seul outil, le fichier natif suffit. Si vous mélangez Claude Code, Codex et Cursor, adoptez AGENTS.md comme source de vérité et importez-le depuis CLAUDE.md. Vous maintenez un fichier, tous vos agents le lisent.
Sources : documentation officielle Claude Code, agents.md, Journal du Net.
Questions fréquentes
Quelle est la différence entre CLAUDE.md et AGENTS.md ?
CLAUDE.md est le fichier d'instructions lu par Claude Code (Anthropic). AGENTS.md est un format ouvert lu par une vingtaine d'outils : OpenAI Codex, Cursor, GitHub Copilot, Gemini, Windsurf, Zed, etc. Les deux sont des fichiers Markdown qui donnent du contexte permanent à un agent de codage. La grande différence : Claude Code ne lit PAS AGENTS.md automatiquement. Si votre projet utilise les deux écosystèmes, créez un CLAUDE.md qui importe AGENTS.md avec la ligne @AGENTS.md, pour ne maintenir qu'un seul fichier de règles.
Quelle est la longueur idéale d'un fichier CLAUDE.md ?
La documentation officielle d'Anthropic recommande de rester sous 200 lignes par fichier CLAUDE.md. Au-delà, le fichier consomme trop de contexte et l'adhérence de Claude aux instructions diminue. Je recommande de démarrer avec 10 à 20 lignes de règles réelles, puis d'enrichir au fil des sessions quand une correction revient. Si le fichier grossit, déplacez les règles spécifiques vers .claude/rules/ avec un champ paths, pour qu'elles ne se chargent que sur les fichiers concernés.
Que faut-il mettre dans un CLAUDE.md ?
Mettez uniquement ce que l'agent ne peut pas deviner seul : commandes de build et de test, conventions de nommage, architecture du projet, stack technique, règles métier et règles de type « toujours faire X ». Évitez les règles de programmation génériques que l'IA connaît déjà, les instructions vagues et les données variables qui changent en cours de projet. Une bonne règle : si vous tapez la même correction dans le chat à chaque session, ajoutez-la au CLAUDE.md.
Claude Code lit-il automatiquement le fichier AGENTS.md ?
Non. Claude Code lit CLAUDE.md, pas AGENTS.md. Pour qu'il prenne en compte un AGENTS.md existant, deux options : créer un CLAUDE.md contenant @AGENTS.md (import), ou créer un lien symbolique avec ln -s AGENTS.md CLAUDE.md. La commande /init, lancée dans un dépôt qui contient déjà un AGENTS.md, lit ce fichier et intègre les parties pertinentes dans le CLAUDE.md généré.
Faut-il savoir coder pour écrire un CLAUDE.md ?
Non. Un CLAUDE.md se rédige entièrement en langage naturel, en français si vous le souhaitez, avec du Markdown simple pour la structure. Pas de syntaxe spéciale ni de balises complexes. Le plus rapide pour démarrer sans coder : lancer la commande /init, qui analyse votre projet et génère un premier CLAUDE.md avec les commandes et conventions détectées. Vous l'affinez ensuite avec les règles que l'IA ne pouvait pas deviner.
Quelle est la différence entre CLAUDE.md et un skill ?
CLAUDE.md charge ses instructions à chaque session et consomme du contexte en permanence : il sert aux conventions toujours actives (stack, indentation, architecture). Un skill ne se charge que lorsqu'il est invoqué ou pertinent : il sert aux workflows ponctuels et multi-étapes (déploiement, revue de code, génération de tests). Règle pratique : si une instruction est une procédure en plusieurs étapes ou ne concerne qu'une partie du code, sortez-la du CLAUDE.md vers un skill ou une règle path-scoped.
Où placer le fichier CLAUDE.md dans un projet ?
À la racine du projet (./CLAUDE.md ou ./.claude/CLAUDE.md) pour les règles partagées avec l'équipe via Git. Pour vos préférences personnelles sur tous vos projets : ~/.claude/CLAUDE.md. Pour des préférences locales non versionnées : ./CLAUDE.local.md (à ajouter au .gitignore). Claude charge tous les fichiers de la racine du système jusqu'à votre dossier de travail, en concaténant les instructions, des plus générales aux plus spécifiques.