CLAUDE.md est un fichier markdown qui donne à Claude Code des instructions permanentes sur votre projet, chargées automatiquement au début de chaque session. Il évite de réexpliquer les mêmes conventions, commandes ou choix d’architecture à chaque conversation.
Qu’est-ce que le fichier CLAUDE.md ?
Le fichier CLAUDE.md est un simple fichier texte au format markdown que vous écrivez vous-même, contrairement à la mémoire automatique que Claude génère seul. Chaque session de Claude Code commence avec une fenêtre de contexte vierge, et CLAUDE.md sert justement à transporter les informations essentielles d’une session à l’autre.
On y place ce qu’on répéterait sinon à chaque conversation : commandes de build et de test, conventions de code, décisions d’architecture, règles de type « toujours faire ceci ». Une procédure ponctuelle ou un sujet qui ne concerne qu’une partie du code a plutôt sa place dans une skill ou une règle scopée à un chemin précis.
Où placer un fichier CLAUDE.md ?
Un fichier CLAUDE.md peut se trouver à quatre niveaux différents, du plus large au plus spécifique. Ces niveaux se cumulent dans le contexte plutôt que de s’écraser les uns les autres.
- Politique managée : déployée par une équipe IT sur toute une organisation, non modifiable par l’utilisateur.
- Instructions utilisateur (
~/.claude/CLAUDE.md) : vos préférences personnelles, valables sur tous vos projets. - Instructions projet (
./CLAUDE.mdou./.claude/CLAUDE.md) : partagées avec l’équipe via le contrôle de version. - Instructions locales (
./CLAUDE.local.md) : vos préférences propres à ce projet, à ajouter au.gitignore.
Claude Code remonte l’arborescence des dossiers depuis votre répertoire de travail pour charger tous les fichiers CLAUDE.md rencontrés en chemin. Les fichiers situés dans des sous-dossiers, eux, ne se chargent que lorsque Claude lit un fichier dans ce sous-dossier.
Comment générer un CLAUDE.md automatiquement avec /init ?
La commande /init génère automatiquement un CLAUDE.md en analysant votre code source pour repérer les commandes de build, les instructions de test et les conventions du projet. Si un CLAUDE.md existe déjà, /init propose des améliorations plutôt que d’écraser le fichier.
Ce fichier généré reste un point de départ. Complétez-le ensuite avec des instructions que Claude ne pourrait pas deviner seul en lisant votre code.
Quelle est la différence entre CLAUDE.md et la mémoire automatique ?
CLAUDE.md contient des instructions que vous rédigez vous-même, tandis que la mémoire automatique (auto memory) rassemble des notes que Claude écrit seul à partir de vos corrections. Les deux systèmes se chargent à chaque session, mais leur usage diffère nettement.
La mémoire automatique stocke ses notes dans un dossier propre à chaque projet, avec un fichier d’index MEMORY.md et des fichiers thématiques annexes. Seules les 200 premières lignes (ou 25 Ko) de MEMORY.md se chargent au démarrage, le reste étant consulté par Claude à la demande.
Pour ajouter une instruction à la mémoire automatique, il suffit de le demander en langage naturel, par exemple « retiens qu’on utilise toujours pnpm et non npm ». Pour l’inscrire plutôt dans CLAUDE.md, précisez-le explicitement ou éditez le fichier vous-même.
Comment écrire des instructions efficaces dans CLAUDE.md ?
Des instructions efficaces dans CLAUDE.md sont concises, concrètes et vérifiables, car le fichier est délivré comme un message de contexte et non comme une règle imposée de force. Visez moins de 200 lignes par fichier : au-delà, la consommation de contexte augmente et l’adhérence aux règles diminue.
Préférez « utiliser une indentation de 2 espaces » à « bien formater le code », ou « lancer npm test avant de commit » à « tester ses changements ». Si deux règles se contredisent, Claude peut trancher arbitrairement, d’où l’intérêt de relire régulièrement le fichier.
Pour un gros projet, la répartition en fichiers thématiques sous .claude/rules/ garde chaque instruction courte et ne charge les règles spécifiques que lorsque Claude travaille sur les fichiers concernés.
Comment référencer d’autres fichiers avec la syntaxe @ ?
La syntaxe @chemin/du/fichier importe automatiquement le contenu d’un fichier dans CLAUDE.md, jusqu’à quatre niveaux d’imbrication. C’est pratique pour référencer un README, un schéma de base de données ou un guide de workflow sans dupliquer son contenu.
Claude Code lit uniquement CLAUDE.md, pas AGENTS.md. Si votre dépôt utilise déjà un fichier AGENTS.md pour d’autres outils IA, importez-le en première ligne avec @AGENTS.md, puis ajoutez vos instructions spécifiques à Claude en dessous.
Comment consulter et modifier sa mémoire avec /memory ?
La commande /memory liste tous les fichiers CLAUDE.md, CLAUDE.local.md et règles chargés dans la session en cours, et permet d’activer ou désactiver la mémoire automatique. Sélectionner un fichier l’ouvre directement dans votre éditeur.
Si une instruction semble avoir disparu après un /compact, le CLAUDE.md à la racine du projet est relu automatiquement depuis le disque. En revanche, les CLAUDE.md de sous-dossiers ne se rechargent qu’au prochain accès à ce sous-dossier, ce qui explique le plus souvent une instruction manquante.
Ce qu’il faut retenir sur CLAUDE.md
CLAUDE.md reste l’outil central pour donner un contexte stable à Claude Code, à condition de le garder court, structuré et sans contradiction. La mémoire automatique vient compléter ce système en capturant les corrections répétées sans effort de votre part.
Pour la documentation complète, avec le détail des règles scopées et de la gestion en entreprise, consultez la documentation officielle sur la mémoire de Claude Code.
Questions fréquentes
C’est un fichier markdown que vous écrivez pour donner à Claude Code des instructions persistantes sur un projet, chargées automatiquement au début de chaque session.
Il peut être placé à quatre niveaux : politique managée pour toute une organisation, ~/.claude/CLAUDE.md pour vos préférences personnelles, ./CLAUDE.md pour le projet partagé en équipe, et ./CLAUDE.local.md pour vos préférences locales non versionnées.
CLAUDE.md contient des instructions que vous rédigez vous-même, tandis que la mémoire automatique regroupe des notes que Claude écrit seul à partir de vos corrections et préférences observées.
La commande /init analyse votre codebase et génère un CLAUDE.md avec les commandes de build, les instructions de test et les conventions détectées. Si le fichier existe déjà, /init propose des améliorations plutôt que de l’écraser.
