CLAUDE.md vs AGENTS.md :quel agent lit quel fichier.

Ce qu’est chaque fichier

Ce sont deux fichiers Markdown simples qu’un agent charge dans son contexte au début d’une session. Vous y écrivez les commandes de build et de test, le style de code, l’organisation du projet et des règles comme « ne jamais modifier les fichiers générés ». Ce sont des instructions, pas des réglages imposés : l’agent les traite comme des consignes.

• CLAUDE.md est propre à Claude Code. Il peut se trouver à la racine du projet (./CLAUDE.md ou ./.claude/CLAUDE.md), dans ~/.claude/CLAUDE.md pour tous vos projets, et dans des sous-dossiers. Un CLAUDE.local.md contient des notes privées pour un projet.
• AGENTS.md est un format ouvert décrit sur agents.md, un README pour les agents. Codex, Cursor, l’agent de code de GitHub Copilot, Gemini CLI, Zed et beaucoup d’autres le lisent. Dans un monorepo, un AGENTS.md dans un sous-dossier s’applique à cette partie, et le fichier le plus proche l’emporte.

Le contenu est du même genre. Ce qui diffère, c’est quel outil prend le fichier en compte.

Ce que fait Claude Code d’AGENTS.md

La documentation de Claude Code décrit trois cas, pour la version 2.1.277 ou ultérieure :

• Seulement un AGENTS.md dans votre projet, pas de CLAUDE.md : Claude Code lit l’AGENTS.md.
• Les deux fichiers dans votre projet : Claude Code lit uniquement les fichiers CLAUDE.md.
• Un CLAUDE.md qui importe AGENTS.md avec @AGENTS.md : Claude lit le CLAUDE.md avec AGENTS.md inclus.

Ce deuxième cas est celui qui surprend. Si vous ajoutez un CLAUDE.md, même minuscule, à un dépôt qui a un AGENTS.md, Claude cesse de lire l’AGENTS.md à moins que le CLAUDE.md ne l’importe. Il en va de même pour un CLAUDE.local.md. Les anciennes versions de Claude Code ne lisaient que CLAUDE.md, c’est pourquoi l’import reste le choix sûr. La documentation décrit aussi un réglage Project instructions dans /config pour que Claude lise les deux fichiers ensemble.

Garder un seul jeu d’instructions

Choisissez un fichier comme source de vérité. Deux méthodes sont documentées :

1. Importer AGENTS.md depuis CLAUDE.md

   Créez un CLAUDE.md à côté d’AGENTS.md dont la première ligne est @AGENTS.md, puis ajoutez en dessous les instructions propres à Claude. Les imports utilisent la syntaxe @path, les chemins relatifs se résolvent à partir du fichier qui les contient, et les fichiers importés peuvent en importer d’autres jusqu’à quatre niveaux de profondeur.

2. Lier CLAUDE.md à AGENTS.md par un lien symbolique

   Lancez ln -s AGENTS.md CLAUDE.md si vous n’avez rien de propre à Claude à ajouter. La documentation prévient que les outils d’édition de Claude n’écrivent pas à travers un lien symbolique, et que sous Windows un lien symbolique validé peut être extrait comme un fichier texte d’une ligne ; l’import est donc le choix le plus sûr pour un dépôt partagé.

Évitez une troisième approche : un CLAUDE.md qui dit « lis AGENTS.md » en toutes lettres. Claude ne voit le fichier que s’il décide de l’ouvrir, alors qu’un import le charge à chaque fois.

Un AGENTS.md partagé

Mettez dans AGENTS.md ce dont tout agent a besoin :

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Restez bref et précis. La documentation de Claude Code conseille de rester sous 200 lignes environ par CLAUDE.md, car les fichiers plus longs coûtent du contexte et sont suivis moins fidèlement.

Erreurs courantes

• Deux fichiers qui divergent. Une copie est mise à jour, l’autre non. Utilisez l’import.
• Ajouter un CLAUDE.md et perdre l’AGENTS.md. Voir plus haut : importez-le.
• Mettre des secrets dans l’un ou l’autre fichier. Ils sont validés dans le dépôt et chargés dans chaque session.
• Des règles vagues. « Écris du code propre » ne sert à rien. « Lance npm test avant de dire que tu as fini » si.
• Des règles contradictoires entre le fichier d’un dossier parent et celui d’un sous-dossier.

Lire et relire ces fichiers

Ce sont des fichiers Markdown ordinaires : DotMD ouvre CLAUDE.md et AGENTS.md comme n’importe quel fichier .md, avec un plan et un historique de chaque modification, et montre ce qu’un agent y a changé. La lecture est gratuite. Voir aussi Claude Code et Codex avec DotMD.

Questions sur CLAUDE.md et AGENTS.md

Plus de questions