CLAUDE.md expliqué : apprends ton projet à Claude Code une fois pour toutes

Chaque nouvelle session de Claude Code démarre avec la tête vide. Tu lui dis d’utiliser pnpm, pas npm. Tu lui dis où se trouvent les tests. Tu lui dis de ne pas toucher au dossier généré. Demain, tu lui redis tout ça.

C’est un simple fichier texte en Markdown. Claude Code le lit au début de chaque session, donc tout ce qu’il contient est connu avant ton premier prompt. Ce guide montre où placer le fichier, comment en écrire un que Claude suit, et ce qu’il vaut mieux laisser dehors.

Ce qu’est CLAUDE.md, et ce qu’il n’est pas

Chaque session de Claude Code commence avec une fenêtre de contexte vierge. Deux mécanismes transmettent les connaissances d’une session à la suivante :

Les deux sont chargés comme contexte. Ce mot compte : Claude lit CLAUDE.md et essaie de le suivre, mais ce n’est pas un réglage appliqué de force. Une ligne vague ou contradictoire peut être ignorée. On y revient dans la section de dépannage, car cela décide de la façon d’écrire le fichier.

Où placer le fichier

Il y a quatre emplacements, et ils s’empilent. Claude les charge du plus large au plus précis, donc ce qui est le plus proche de ton projet est lu en dernier.

Les deux que tu utiliseras sont le fichier projet et le fichier utilisateur.

• Fichier projet. Place CLAUDE.md à la racine de ton projet, ou dans un dossier .claude à la racine. Commite-le, pour que tous ceux qui travaillent sur le projet reçoivent les mêmes instructions. Écris ce qui est vrai pour n’importe qui : commandes de build, conventions, organisation du projet.
• Fichier utilisateur. ~/.claude/CLAUDE.md te suit dans tous les projets. Sers-t’en pour tes habitudes personnelles, par exemple la façon dont tu aimes que les explications soient formulées.
• Fichier local. CLAUDE.local.md sert aux notes qui sont à toi et propres à un projet, comme l’URL d’un bac à sable. Ajoute-le à ton .gitignore pour qu’il ne soit pas commité.

Claude regarde aussi dans le dossier d’où tu l’as lancé et dans tous les dossiers au-dessus. Si tu démarres dans foo/bar/, il charge foo/bar/CLAUDE.md et foo/CLAUDE.md. Les fichiers des dossiers en dessous de toi se chargent plus tard, à la demande, la première fois que Claude lit ou modifie un fichier de ce sous-dossier.

Commence par /init

Tu n’as pas besoin d’écrire la première version à la main. Dans une session, lance :

> /initAnalyse de ton code en cours...CLAUDE.md créé avec les commandes de build, les instructions de test et les conventions trouvées.

Claude Code lit ton projet et écrit un CLAUDE.md avec les commandes de build et de test et les conventions qu’il découvre. Si un CLAUDE.md existe déjà, /init propose des améliorations au lieu de l’écraser. Considère le résultat comme un premier brouillon. Ton travail est d’ajouter ce que Claude n’aurait pas pu découvrir seul.

Pour confirmer que le fichier est chargé, lance /context dans une session et regarde sous Memory files.

Ce qui a sa place dans le fichier

Avant d’écrire une ligne, un bon test tient en deux questions :

Si les deux réponses sont oui, laisse la ligne de côté. Il reste alors l’information qui n’a jamais été dans le code, ou qui coûte un vrai temps à redécouvrir :

Ajoute une ligne quand Claude fait deux fois la même erreur, quand une relecture de code attrape quelque chose qu’il aurait dû savoir, ou quand tu tapes la même correction que la session précédente. C’est le signe que l’information a sa place dans le fichier.

Un exemple à copier

Voici un court fichier de projet. Remarque que chaque ligne est vérifiable, et que très peu décrivent l’architecture.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

Cela fait 15 lignes, et chacune mérite sa place.

Comment écrire des lignes que Claude suit

Comme CLAUDE.md est du contexte et non de la configuration, la façon de formuler une ligne décide si elle sera suivie. Écris des instructions assez concrètes pour être vérifiées.

Garde ensuite le fichier en forme :

• Court. Vise moins de 200 lignes par fichier. Les fichiers plus longs consomment plus de contexte et Claude les suit moins fidèlement.
• Organisé. Regroupe les lignes liées sous des titres et des puces Markdown. Claude suit mieux une structure que des paragraphes denses.
• Cohérent. Si deux lignes se contredisent, Claude peut en choisir une au hasard. Relis tes fichiers de temps en temps, y compris ceux des sous-dossiers, et supprime tout ce qui est périmé.

Pour que Claude passe tes fichiers d’instructions au crible à la recherche de lignes périmées ou en conflit, lance /doctor prompt-audit. Il signale ses constats et propose des modifications, sans rien changer tant que tu ne le demandes pas. Il faut Claude Code 2.1.283 ou plus récent.

Importer d’autres fichiers

CLAUDE.md peut inclure d’autres fichiers avec un @ devant le chemin. Le fichier importé se charge avec le CLAUDE.md qui le mentionne.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

Les chemins relatifs sont résolus à partir du fichier qui contient l’import. Les imports peuvent eux-mêmes en importer d’autres, sur quatre niveaux au maximum. Le @ n’est lu qu’en dehors des blocs de code, donc entoure un chemin de backticks si tu veux le mentionner sans l’importer.

Les imports servent à s’organiser, mais ils ne réduisent pas le contexte : les fichiers importés se chargent toujours en entier. Pour des instructions personnelles que tu veux dans plusieurs copies du même dépôt, importe un fichier de ton dossier personnel, comme @~/.claude/my-project-instructions.md. La première fois qu’un projet importe un fichier situé hors du répertoire de travail, Claude Code te demande ton accord.

Quand un seul fichier devient trop long

À un moment, le fichier dépasse ce dont chaque session a besoin. Tu as quatre outils, chacun pour une tâche différente.

Des règles ciblées sur certains fichiers

Place un fichier Markdown par sujet dans .claude/rules/, comme testing.md ou api-design.md. Pour qu’une règle ne s’applique qu’à certains fichiers, ajoute un champ paths en haut :

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

# API rules

- Every endpoint validates its input
- Use the standard error response format

Une règle sans paths se charge à chaque session. Une règle ciblée se charge quand Claude lit ou modifie un fichier correspondant, ce qui garde les instructions à l’écart le reste du temps.

Si un bloc de CLAUDE.md est une procédure en plusieurs étapes, comme préparer une release, déplace-le plutôt dans une compétence. Les compétences ne se chargent que lorsqu’on s’en sert.

La mémoire auto : les notes que Claude garde pour lui

En plus du fichier que tu écris, Claude Code peut prendre des notes de lui-même. La mémoire auto est activée par défaut dans les sessions locales. Pendant qu’il travaille, Claude enregistre quatre sortes de notes : sur toi (rôle et préférences), les retours (corrections et approches que tu as confirmées), le projet (décisions et échéances invisibles dans le code) et les références (où trouver des choses hors du projet).

Il n’enregistre pas ce qu’il peut lire dans le code, ni ce que ton CLAUDE.md dit déjà. Tu verras des messages comme « Saved 2 memories » dans la session. Les notes sont du Markdown simple sous ~/.claude/projects/, et les 200 premières lignes ou 25 Ko du fichier d’index se chargent au début de chaque session.

Lance /memory pour voir chaque fichier d’instructions et le dossier de la mémoire auto, pour ouvrir n’importe lequel dans ton éditeur, et pour activer ou désactiver la mémoire auto. Si tu dis à Claude « utilise toujours pnpm, pas npm », il l’enregistre dans la mémoire auto. Pour l’ajouter plutôt dans CLAUDE.md, dis-le : « ajoute ça à CLAUDE.md ».

Dans Claude Tutorial

Écrire ce que tu devrais sinon répéter

Transformer la même correction en instruction permanente est une habitude qui paie dans tout type de travail avec Claude, pas seulement le code, et l’appli l’enseigne pas à pas.

Bientôt disponible

Télécharger dans l’App Store

DISPONIBLE SURGoogle Play

Quand Claude ne le suit pas

Passe en revue ces points dans l’ordre. Ils règlent la plupart des cas.

Deux cas supplémentaires méritent d’être connus. Après un /compact, le CLAUDE.md à la racine de ton projet est relu depuis le disque : il survit donc. Une instruction donnée seulement en conversation ne survit pas, alors déplace-la dans le fichier. Et quand un CLAUDE.md de sous-dossier est très long (plus d’environ 40 000 caractères dans une fenêtre de contexte plus petite), Claude n’en reçoit que le début : garde-les courts.

Questions fréquentes

Où dois-je mettre CLAUDE.md ?

À la racine de ton projet (./CLAUDE.md) ou dans ./.claude/CLAUDE.md. Place tes préférences personnelles pour tous les projets dans ~/.claude/CLAUDE.md. Utilise ./CLAUDE.local.md, ajouté à .gitignore, pour des notes privées sur un projet.

Quelle longueur pour un CLAUDE.md ?

Vise moins de 200 lignes. Si tu les dépasses, Claude Code affiche un avertissement au démarrage et dans /status. Déplace les parties propres à un domaine dans des règles ciblées et retire ce que Claude peut lire dans le code.

CLAUDE.md est-il la même chose qu’un prompt système ?

Non. CLAUDE.md est transmis sous forme de message après le prompt système. Claude essaie de le suivre, mais le respect strict n’est pas garanti. Pour les instructions qui doivent tenir à chaque fois, utilise un hook ou une règle de permission.

Dois-je commiter CLAUDE.md dans git ?

Oui pour le fichier projet, afin que toute l’équipe le partage et qu’il s’améliore à chaque correction. Non pour CLAUDE.local.md, qui est personnel.

Claude lit-il les CLAUDE.md des sous-dossiers ?

Oui, à la demande. Il charge le fichier d’un sous-dossier la première fois que Claude lit ou modifie un fichier de ce dossier, et affiche une ligne Loaded avec le chemin.

Quelle différence entre CLAUDE.md et une compétence ?

CLAUDE.md sert aux faits utiles à chaque session. Une compétence est une procédure ou un guide qui ne se charge que lorsqu’on l’invoque ou qu’elle est pertinente, donc elle ne prend pas de place le reste du temps.

Ta checklist CLAUDE.md

Pour aller plus loin

• Claude Code pour débutants : installer, se connecter et lancer une première tâche si tu n’as pas encore démarré de session.
• Bonnes pratiques de Claude Code : les habitudes qui donnent de meilleurs résultats pour les prompts, les vérifications et la gestion du contexte.
• Modes de permission et mode plan de Claude Code, expliqués pour décider de ce que Claude peut faire sans demander.
• Les projets Claude : un contexte qui reste pour la même idée dans l’appli Claude : des instructions permanentes gardées avec un projet.