Tous les articles

Le fichier CLAUDE.md : où le mettre, quoi y écrire, et quoi laisser dehors

CLAUDE.md est le fichier que Claude Code lit au début de chaque session. Mettez-y les bonnes choses et Claude suit les règles de votre projet ; mettez-y tout et il n'en suit plus aucune correctement.

Publié le 13 novembre 2026 · 8 min de lecture

Mis à jour le 13 novembre 2026. Chaque comportement décrit ici vient de la documentation de Claude Code d'Anthropic, consultée ce jour-là.

CLAUDE.md est un fichier Markdown d'instructions que Claude Code charge au début de chaque session. Placez-en un à la racine du dépôt pour les règles du projet, et un dans ~/.claude/CLAUDE.md pour vos préférences personnelles, valables partout. Gardez chacun sous 200 lignes environ, écrivez des consignes assez concrètes pour être vérifiées, et déplacez ce qui ne concerne qu'une partie du code dans .claude/rules/. La commande /init en génère une première version.

Où Claude Code cherche CLAUDE.md

  • Projet : ./CLAUDE.md ou ./.claude/CLAUDE.md. Partagé avec l'équipe via le dépôt : architecture, commandes, conventions.
  • Utilisateur : ~/.claude/CLAUDE.md. Vos préférences personnelles, appliquées à tous les projets de votre machine.
  • Local : ./CLAUDE.local.md. Des notes personnelles pour ce projet seulement ; à ajouter au .gitignore.
  • Politique gérée : /etc/claude-code/CLAUDE.md sous Linux, /Library/Application Support/ClaudeCode/CLAUDE.md sous macOS, C:\Program Files\ClaudeCode\CLAUDE.md sous Windows. Défini par une organisation pour tout le monde.

Les fichiers s'additionnent, ils ne s'écrasent pas. Au lancement, Claude Code charge le CLAUDE.md et le CLAUDE.local.md du dossier de travail et de chaque dossier au-dessus, de la racine vers le bas. Les CLAUDE.md des sous-dossiers se chargent plus tard, quand Claude lit ou modifie un fichier qui s'y trouve. Source : documentation de Claude Code.

Le créer avec /init

En session, /init analyse votre code et écrit un CLAUDE.md de départ avec les commandes de build, les instructions de test et les conventions qu'il trouve. Si le fichier existe déjà, il propose des améliorations. Prenez le résultat comme un brouillon : retirez ce qui se voit dans le code, ajoutez ce que Claude ne peut pas deviner.

Ce qu'il faut y mettre

  • Les commandes que Claude ne peut pas deviner : comment builder, tester, linter et lancer un seul test.
  • Les conventions qui s'écartent des habitudes : « indentation à 2 espaces », « les handlers d'API sont dans src/api/handlers/ ».
  • Ce qu'il ne faut jamais faire : « ne jamais modifier les fichiers générés de dist/ », « ne pas ajouter de dépendance sans demander ».
  • Où sont les choses : les quelques dossiers qui comptent et ce qu'ils contiennent.
  • Votre façon de travailler : format des messages de commit, quand demander avant d'agir.

Le conseil d'Anthropic : des consignes assez concrètes pour être vérifiées, comme « Lance npm test avant chaque commit » plutôt que « Teste tes changements ». Regroupez-les sous des titres et des puces. Si deux consignes se contredisent, Claude peut suivre l'une ou l'autre.

CLAUDE.md
# Projet : API de facturation

## Commandes
- Installer : `pnpm install`
- Tous les tests : `pnpm test` · un fichier : `pnpm test src/invoices/total.test.ts`
- Lint avant chaque commit : `pnpm lint`

## Conventions
- TypeScript strict, indentation à 2 espaces, exports nommés uniquement
- Handlers d'API dans `src/api/handlers/`, un fichier par route
- Les montants sont des entiers en centimes, jamais des décimaux

## Jamais
- Modifier les fichiers de `src/generated/` (lancer `pnpm codegen` à la place)
- Ajouter une dépendance sans demander

## Détails
- Règles de base de données : @docs/database.md

Ce qu'il faut laisser dehors

  • Tout ce qui est long. Anthropic recommande de rester sous 200 lignes par fichier : au-delà, le fichier prend plus de contexte et il est moins bien suivi.
  • Les règles d'une partie du code. Mettez-les dans .claude/rules/ avec un champ paths, pour qu'elles ne se chargent que quand Claude touche les fichiers concernés.
  • Les secrets. Clés d'API et mots de passe n'ont rien à faire dans un fichier chargé dans chaque conversation, et souvent versionné.
  • Un journal de décisions. « Pourquoi on est passés à Postgres », « ce que le client a dit en mars » : ça grossit sans fin et ce n'est pas une consigne. Ça va dans une mémoire que Claude consulte quand il en a besoin, pas dans le contexte à chaque fois.

Imports, règles et AGENTS.md

Imports. Une ligne comme @docs/database.md ajoute un autre fichier au contexte. Les chemins sont relatifs au fichier qui contient l'import, et les imports peuvent s'emboîter sur quatre niveaux. Ils rangent un long fichier mais ne le rendent pas moins coûteux : les fichiers importés se chargent aussi au lancement.

.claude/rules/. Un fichier Markdown par sujet (testing.md, api-design.md). Une règle avec un champ paths dans son en-tête ne se charge que quand Claude touche les fichiers correspondants ; les règles personnelles pour tous les projets vont dans ~/.claude/rules/.

AGENTS.md. Si votre dépôt a déjà un AGENTS.md pour d'autres agents de code, les versions récentes de Claude Code le lisent quand il n'y a pas de CLAUDE.md dans le dossier de travail ou au-dessus. Si les deux existent, Claude lit CLAUDE.md ; importez-y AGENTS.md pour garder une seule source. Quels autres outils le lisent, et où : le guide AGENTS.md.

CLAUDE.md, auto memory et une vraie mémoire

Claude Code tient aussi une auto memory : des notes qu'il écrit lui-même à partir de vos corrections, dans ~/.claude/projects/<projet>/memory/, avec un index MEMORY.md dont les 200 premières lignes ou 25 Ko sont chargés à chaque session. Les deux restent sur votre machine, et les deux sont liés à Claude Code.

Le CLAUDE.md à la racine du projet survit à /compact : Claude le relit sur le disque. Une consigne donnée seulement dans la conversation, non. La règle est donc simple : les consignes vont dans CLAUDE.md ; le savoir qui grossit (décisions et leurs raisons, contexte client, ce que vous avez essayé) a sa place dans un serveur de mémoire que Claude consulte quand il en a besoin, et que vos autres IA peuvent lire aussi.

Pryzm pour ordinateur en est un : une appli gratuite qui garde cette mémoire dans un fichier SQLite sur votre ordinateur et connecte Claude Code, Claude Desktop, Cursor et VS Code en un clic. Une ligne dans ~/.claude/CLAUDE.md, comme « consulte Pryzm pour les décisions passées avant de commencer, et enregistre-y les nouvelles », suffit pour que Claude s'en serve. Plus de détails dans mémoire de Claude Code.

Questions fréquentes

Où placer CLAUDE.md ?

À la racine du dépôt (./CLAUDE.md ou ./.claude/CLAUDE.md) pour les règles du projet partagées avec l'équipe, et dans ~/.claude/CLAUDE.md pour vos préférences personnelles sur tous les projets. CLAUDE.local.md contient des notes personnelles pour un projet.

Quelle longueur pour CLAUDE.md ?

Anthropic recommande moins de 200 lignes par fichier. Déplacez les règles qui ne concernent qu'une partie du code dans .claude/rules/ avec un champ paths, pour qu'elles ne se chargent qu'au besoin.

Claude Code lit-il AGENTS.md ?

Oui, dans les versions récentes, quand il n'y a pas de CLAUDE.md dans le dossier de travail ou au-dessus. Si les deux existent, il lit CLAUDE.md ; vous pouvez y importer AGENTS.md.

CLAUDE.md survit-il à /compact ?

Celui à la racine du projet, oui : Claude le relit sur le disque après la compaction. Les consignes données seulement dans la conversation peuvent se perdre.