AGENTS.md vs CLAUDE.md : expliqué

Problème : Tu ouvres un dépôt qui a à la fois un AGENTS.md et un CLAUDE.md. Ils se ressemblent. Ils disent des choses similaires. Tu ne sais pas lequel Claude Code lit, lequel les autres outils lisent, ni pourquoi deux fichiers existent.

Solution rapide : Claude Code lit CLAUDE.md. Tous les autres outils IA majeurs lisent AGENTS.md. Si tu n'utilises que Claude Code, tu n'as besoin que de CLAUDE.md. Si ton équipe utilise plusieurs outils, un seul symlink fait lire le même fichier aux deux :

ln -s CLAUDE.md AGENTS.md

Une seule source de vérité. Pas de duplication.

Ce qu'est vraiment AGENTS.md

AGENTS.md est un standard inter-outils publié par la Linux Foundation et l'Agent Interoperability Initiative Foundation (AAIF). L'objectif est un seul fichier de contexte que n'importe quel outil de code IA peut lire quand il ouvre ton dépôt.

En avril 2026, 18+ outils le supportent. OpenAI Codex, Gemini CLI, Devin, Cursor, Windsurf, Continue, Amp, Warp, et Goose lisent tous AGENTS.md. Il est actif dans plus de 60 000 projets GitHub.

La spec AAIF définit un schéma pour le fichier : des champs comme allowed_tools, disallowed_tools, agent_instructions, output_format, et environment. Chaque outil lit les champs qu'il comprend et ignore ceux qu'il ne comprend pas.

Claude Code ignore entièrement ces champs de schéma. Il a son propre système de permissions dans settings.json. Quand il récupère le contenu d'AGENTS.md (via import), il lit les instructions en prose et ignore les champs structurés.

Ce qu'est vraiment CLAUDE.md

CLAUDE.md est le fichier de contexte natif de Claude Code. Chaque session commence par le charger avant le premier token de conversation.

Le fichier n'est pas de la documentation pour que Claude lise. Ce sont les paramètres opérationnels pour la façon dont Claude fonctionne. Mets tes workflows, ta logique de routage, tes règles qualité, et tes patterns de délégation ici. Les docs projet, les notes de stack, et les spécificités technologiques appartiennent à des skills qui se chargent à la demande.

Taille cible : 200-500 lignes pour un setup solo. 50-100 lignes pour un fichier d'équipe partagé où chaque contributeur doit comprendre ce qu'il contient.

La hiérarchie de priorité à 6 niveaux

Claude Code ne charge pas qu'un seul fichier. Il charge une pile de fichiers et les résout dans l'ordre. L'intérieur gagne sur l'extérieur :

Le niveau 1 définit les valeurs par défaut globales. Le niveau 2 définit les règles du dépôt. Le niveau 3 contient les trucs spécifiques à la machine qui ne doivent jamais quitter ton laptop.

Le piège de CLAUDE.local.md : Claude Code n'ajoute pas ce fichier à .gitignore pour toi. Tu dois le faire toi-même. Si tu oublies, git le suit et il remonte avec ton prochain commit. Bons candidats pour le fichier : endpoints API locaux, préférences de débogage personnelles, URLs de sandbox. Aucun de ceux-là n'appartient à l'arbre partagé.

@imports et le pont vers AGENTS.md

Dans n'importe quel fichier CLAUDE.md, tu peux inclure un autre fichier avec @path/to/file.md. Le contenu importé est injecté là où se trouve la ligne @.

C'est comme ça que Claude Code 2.1.59+ te laisse faire le pont avec AGENTS.md :

# CLAUDE.md
@AGENTS.md
<!-- Claude reads AGENTS.md content here, but CLAUDE.md rules below take priority -->

## Claude-specific rules
- Use TodoWrite to track multi-step tasks
- Never use --dangerously-skip-permissions outside containers

Le contenu d'AGENTS.md importé se charge. Mais le niveau 6 (imports) est la couche la plus faible dans la hiérarchie. Si une règle dans AGENTS.md entre en conflit avec une règle écrite directement dans CLAUDE.md, la règle directe gagne. Toujours.

Ça signifie que le contenu d'AGENTS.md est toujours consultatif quand il est amené via import. Il informe le comportement de Claude. Il ne surcharge pas ce que tu as écrit dans le fichier racine.

L'astuce du symlink

Le setup multi-outils le plus propre évite complètement la complexité des imports. Lance ça une fois à la racine du dépôt :

ln -s CLAUDE.md AGENTS.md

Maintenant AGENTS.md est un symlink pointant vers CLAUDE.md. Claude Code lit CLAUDE.md. Cursor, Windsurf, Gemini CLI, et chaque autre outil compatible AGENTS.md lit AGENTS.md. Ils touchent tous les mêmes octets.

Pas de duplication. Pas de problème de synchronisation. Un seul fichier à maintenir.

Le seul compromis : Claude Code ignore les champs de schéma AGENTS.md, et les outils compatibles AGENTS.md ignorent les instructions spécifiques à Claude Code (comme les flags TodoWrite ou --dangerously-skip-permissions). En pratique c'est bien. Les instructions en prose fonctionnent pour les deux. Les champs de schéma sont juste ignorés.

Mémoire automatique et MEMORY.md

Claude Code 2.1.59+ peut écrire dans un fichier MEMORY.md à la racine de ton projet tout seul. Ce fichier se situe au niveau 5, la même priorité que ton CLAUDE.md au niveau du dépôt.

Le fichier a des limites strictes : 200 lignes et 25 Ko. Pour les fichiers de sujets à la demande (comme memory/auth.md ou memory/payments.md), le plafond est de 120 lignes chacun. MEMORY.md lui-même sert d'index pointant vers ces fichiers de sujets.

Ce qu'il faut surveiller : les entrées mémoire qui se contredisent créent une ambiguïté silencieuse. Claude ne lève pas d'erreur. Il a juste deux instructions conflictuelles et les résout discrètement, ce qui peut ne pas aller dans le sens attendu. Audite MEMORY.md périodiquement. Supprime les entrées de plus de 30 jours qui ne sont pas revenues.

Les 7 façons dont CLAUDE.md se plante

La plupart des équipes écrivent un CLAUDE.md une fois et ne le revisitent jamais. Voici les modes d'échec qui s'accumulent avec le temps :

Saturation de priorité : Trop de labels ALWAYS, NEVER et CRITICAL. Quand chaque règle crie, aucune ne passe. Claude traite les fichiers surchargés en répartissant l'attention également sur toutes les règles. Garde les contraintes strictes à 5-7 maximum.

L'emballage "peut ou non être pertinent" : Quand Claude Code injecte le contexte de session, il l'enveloppe parfois dans cette formule. Cet emballage signale que le contenu a été chargé mais est traité comme fond, pas comme instructions. Les fichiers avec cet emballage ne sont pas suivis de près.

Dilution par profondeur d'import : Les instructions dans un fichier importé sont plus faibles que les instructions écrites directement. Une chaîne comme CLAUDE.md → @a.md → @b.md est très diluée au moment d'arriver à b.md. Garde les règles importantes dans le fichier racine.

Replay de trauma : MEMORY.md accumule chaque correction que tu as jamais faite. Après 50 sessions, Claude essaie d'éviter 50 erreurs passées différentes en même temps. Les performances se dégradent. Des audits périodiques règlent ça.

Accumulation de biais : Les confirmations positives écrites dans la mémoire ("l'utilisateur préfère X") peuvent se calcifier en règles qui ne correspondent plus à tes préférences actuelles. Ce que tu préférais il y a six mois n'est peut-être pas ce que tu préfères aujourd'hui.

Suivi des instructions vs application : CLAUDE.md est chargé comme contexte, pas appliqué comme un linter. Une règle qui dit "n'utilise jamais de tirets cadratins" peut quand même être violée. Si une règle compte, couple-la avec des outils réels (une règle de lint, un hook, un formateur) plutôt que de te fier au contexte seul.

Perte post-/compact : Lancer /compact résume la conversation. Les instructions qui étaient dans le chat mais pas dans CLAUDE.md ne survivent pas à la compaction. Écris les règles durables dans le fichier. Ne les garde pas seulement dans la session.

Ce qui va dans chaque fichier

Boris Cherny d'Anthropic formule la cible directement : CLAUDE.md devrait contenir les comportements qui doivent persister à travers chaque session.

Mets dans CLAUDE.md : workflows opérationnels, logique de routage, standards qualité, protocoles de coordination, contraintes strictes (5-7 max), patterns de délégation.

Mets dans les skills (chargés à la demande) : patterns technologiques, conventions de framework, contexte spécifique au projet, docs d'architecture, conventions d'équipe.

Ne mets pas dans CLAUDE.md : documentation d'architecture (lis depuis le code), historique git récent (utilise git log), état actuel des PR, instructions boilerplate que tout modèle suit déjà par défaut.

Le conseil sur le nombre de lignes que tu trouveras ailleurs dit de rester sous 60 lignes. C'est faux. Soixante lignes de trivia projet dont tu n'as besoin que la moitié du temps gaspillent plus de contexte effectif que 300 lignes de règles opérationnelles universelles qui s'appliquent à chaque requête. La pertinence est la métrique, pas la longueur.

Choisir ton setup

Trois patterns couvrent la plupart des cas d'usage :

Si tu n'utilises que Claude Code, écris un seul CLAUDE.md et ignore AGENTS.md complètement. Il n'existe pas pour toi.

Si ton équipe utilise plusieurs outils mais que Claude Code est le principal, utilise le symlink. Un fichier, les deux noms, pas de surcharge de maintenance. Écris dans le style qui fonctionne pour Claude Code ; les autres outils prennent ce qu'ils peuvent de la prose.

Si tu as besoin que Claude Code reste synchronisé avec un AGENTS.md à l'échelle du dépôt maintenu par d'autres outils, utilise le pont d'import @AGENTS.md dans ton CLAUDE.md. Rappelle-toi que le contenu importé est consultatif. Mets tes surcharges spécifiques à Claude en dessous de la ligne d'import.

Deux fichiers, une règle claire : Claude lit CLAUDE.md, tout le monde d'autre lit AGENTS.md, et un symlink est le moyen le plus rapide de les rendre identiques.

Questions fréquentes

C'est quoi AGENTS.md ?

AGENTS.md est un standard ouvert publié par la Linux Foundation et l'Agent Interoperability Initiative Foundation. Il définit un fichier de contexte unique que n'importe quel outil de code IA peut lire quand il ouvre ton dépôt. Plus de 18 outils le supportent, dont Cursor, Windsurf, Gemini CLI, Devin, et OpenAI Codex. Il est utilisé dans plus de 60 000 projets open-source.

Claude Code lit-il AGENTS.md ?

Claude Code ne lit pas AGENTS.md nativement. Il lit CLAUDE.md à la place. Tu peux tirer le contenu d'AGENTS.md dans Claude Code avec une ligne d'import @AGENTS.md dans ton fichier CLAUDE.md, ou pointer les deux noms de fichiers vers le même fichier via un symlink. Aucune des deux approches ne change quel fichier Claude Code traite comme autoritatif.

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

AGENTS.md est un standard inter-outils que n'importe quel assistant de code IA peut lire. CLAUDE.md est le fichier natif de Claude Code, chargé automatiquement au début de chaque session. AGENTS.md utilise un schéma structuré avec des champs comme allowed_tools et output_format. CLAUDE.md utilise des instructions en prose et supporte les fonctionnalités spécifiques à Claude Code comme les @imports, CLAUDE.local.md, et la mémoire automatique.

Que faut-il mettre dans CLAUDE.md ?

Mets les règles opérationnelles qui s'appliquent à chaque session : workflows, logique de routage, standards qualité, contraintes strictes, et patterns de délégation. Garde les contraintes strictes à 5-7 maximum. Ne mets pas la documentation d'architecture, l'historique git récent, ou les instructions boilerplate que tout modèle suit déjà par défaut. Les spécificités technologiques et le contexte du projet appartiennent aux skills qui se chargent à la demande, pas dans le fichier racine.

À quoi sert CLAUDE.local.md ?

CLAUDE.local.md contient les paramètres spécifiques à la machine qui ne doivent pas être commités dans le contrôle de version. Les bons candidats incluent les endpoints API locaux, les préférences de débogage personnelles, et les URLs de sandbox. Claude Code ne l'ajoute pas à .gitignore automatiquement, donc tu dois le faire toi-même. Si tu oublies, le fichier remonte avec ton prochain commit et expose la configuration locale à tous les contributeurs.

Comment utiliser CLAUDE.md et AGENTS.md ensemble ?

L'approche la plus propre est un symlink à la racine de ton dépôt : ln -s CLAUDE.md AGENTS.md. Claude Code lit CLAUDE.md, et chaque autre outil lit AGENTS.md. Ils touchent tous les mêmes octets sans duplication. Si tu as besoin que Claude Code reste en aval d'un AGENTS.md partagé maintenu par l'équipe, utilise l'import @AGENTS.md dans ton CLAUDE.md et écris toutes tes surcharges spécifiques à Claude en dessous de la ligne d'import.