CLAUDE.md : le fichier d’instructions de Claude Code

Pour apprendre à configurer et piloter Claude Code sur un vrai projet, la formation Claude Code de Dyma consacre au fichier CLAUDE.md un chapitre entier, « La mémoire : CLAUDE.md et auto-mémoire ». Ce guide explique où placer le fichier CLAUDE.md, quoi y mettre, comment le garder court et comment il cohabite avec AGENTS.md et la mémoire automatique. Tout a été vérifié le 2 novembre 2026 sur la documentation officielle d’Anthropic (Claude Code 2.1.316). Il fait partie de notre série sur les modules de Claude Code, avec les skills, les hooks et MCP.

Qu’est-ce que le fichier CLAUDE.md ?

Chaque session de Claude Code commence sans souvenir des précédentes. Le fichier CLAUDE.md comble ce vide : Claude Code le charge au démarrage et l’ajoute à la conversation, juste après ses propres instructions. Vous y décrivez votre projet comme à un nouveau collègue : comment lancer les tests, quelles conventions suivre, quels dossiers sont trompeurs.

La documentation insiste sur un point : Claude traite ce fichier comme du contexte, pas comme une configuration imposée. Plus une consigne est précise, plus elle est suivie ; mais rien ne garantit qu’elle le soit à chaque fois. Pour une règle sans exception, comme interdire une commande, il faut un hook.

Où placer CLAUDE.md ?

Plusieurs fichiers CLAUDE.md peuvent coexister. Ils ne s’écrasent pas : Claude Code les met bout à bout, du plus général au plus précis.

Claude Code remonte aussi les dossiers parents : lancé dans monorepo/api/, il lit le CLAUDE.md de monorepo/ puis celui de api/. Les fichiers des sous-dossiers, eux, ne sont chargés qu’à la demande, quand Claude lit ou modifie un fichier de ce sous-dossier. Si deux fichiers se contredisent, la documentation prévient que Claude peut choisir l’une des deux consignes arbitrairement : relisez l’ensemble.

Créer un CLAUDE.md avec /init

1. Lancez /init à la racine du projet : Claude explore le code et propose un premier fichier.
2. Relisez la proposition et retirez tout ce que Claude devinerait seul en lisant le code.
3. Ajoutez ce qui manque : commandes exactes, décisions absentes du dépôt, pièges connus.
4. Committez le fichier pour que toute l’équipe en profite.
5. Complétez-le au fil de l’eau, chaque fois que vous corrigez Claude deux fois sur le même point.

Si un CLAUDE.md existe déjà, /init propose des améliorations sans l’écraser. Il reprend aussi les règles écrites pour d’autres outils, comme .cursorrules ou .github/copilot-instructions.md. La commande /memory liste les fichiers d’instructions de vos différents niveaux et ouvre celui que vous voulez modifier ; /context montre ceux qui ont été chargés au démarrage.

Que mettre dans CLAUDE.md ?

La règle officielle tient en une phrase : n’y mettez que ce que Claude ne peut pas déduire du code. Un exemple sur le modèle de celui de la documentation :

# Commandes
- Installer : pnpm install
- Lancer un fichier de test : pnpm vitest run chemin/du/fichier.test.ts
- Vérifier les types : pnpm tsc --noEmit

# Conventions
- Utiliser les helpers d'erreur de src/lib/errors.ts, jamais de chaîne levée brute
- src/legacy/ est encore en service, mais ne pas copier ses façons de faire

# Pièges
- Les tests d'intégration demandent DATABASE_URL, voir .env.example

Écrivez des consignes vérifiables. La documentation donne ces exemples :

Les bons moments pour ajouter une ligne : Claude répète la même erreur, une revue de code relève ce qu’il aurait dû savoir, vous retapez la même correction, ou un nouvel arrivant aurait besoin de la même explication. Une procédure en plusieurs étapes ou propre à une partie du code a sa place ailleurs, dans un skill ou une règle ciblée.

Garder CLAUDE.md court

La documentation recommande moins de 200 lignes par fichier : un fichier plus long consomme du contexte à chaque requête et ses consignes sont moins bien suivies. Ajouter « IMPORTANT » devant une ligne ignorée n’y change probablement rien, selon le guide des bonnes pratiques d’Anthropic. Deux outils aident à alléger.

Les imports. Une ligne comme @docs/git-instructions.md insère un autre fichier, sur quatre niveaux d’imbrication au plus. Le chemin est relatif au fichier qui importe. Attention : un import range le fichier, il ne réduit pas ce qu’il coûte en contexte.

Les règles ciblées. Les fichiers Markdown du dossier .claude/rules/ se chargent comme CLAUDE.md. Avec un champ paths, ils ne se chargent que lorsque Claude touche un fichier correspondant, ce qui, cette fois, économise du contexte :

---
paths:
  - "src/api/**/*.ts"
---

# Règles de l'API

- Chaque endpoint valide ses entrées
- Utiliser le format d'erreur standard

Pour faire le ménage, /doctor propose de retirer ce qui se déduit du code.

CLAUDE.md, AGENTS.md et les autres outils

AGENTS.md est le fichier d’instructions que lisent d’autres agents de code. Depuis la version 2.1.277, Claude Code le lit aussi, selon cette règle officielle :

Pour partager un seul fichier entre plusieurs outils, la documentation propose un CLAUDE.md qui commence par @AGENTS.md, suivi des consignes propres à Claude. Le réglage « Project instructions » de /config permet aussi de charger les deux fichiers.

CLAUDE.md ou mémoire automatique ?

Claude Code tient aussi ses propres notes, la mémoire automatique, activée par défaut. Les deux se chargent à chaque session, mais ne servent pas à la même chose :

Quand vous demandez à Claude de « retenir » quelque chose, il l’écrit dans sa mémoire automatique. Pour l’inscrire dans CLAUDE.md, dites-le explicitement : « ajoute ceci au CLAUDE.md ».

Aller plus loin

CLAUDE.md dit à Claude comment travailler ; les autres modules lui donnent des savoir-faire et des garde-fous. Les skills empaquettent une procédure qu’il charge seulement quand il en a besoin, les hooks imposent ce qui doit toujours se produire, et MCP le relie à vos outils. Si vous débutez, commencez par notre tutoriel Claude Code.

La formation Claude Code met tout cela en pratique sur un projet complet. Pour construire vos propres applications et agents avec les modèles d’IA, voyez la formation IA pour développeurs ; pour Claude au quotidien, la formation Claude.

Questions fréquentes