Imaginez un collègue brillant, rapide, disponible jour et nuit… mais amnésique. Chaque matin, il a tout oublié : vos conventions de code, vos commandes de test, les pièges de votre projet. C’est exactement ainsi que Claude Code se comporte d’une session à l’autre. Dans ce module, vous allez régler ce problème une bonne fois pour toutes, avec un simple fichier texte : CLAUDE.md. C’est probablement le meilleur investissement de toute cette formation.

Ce que vous allez apprendre

• Pourquoi chaque session repart de zéro, et comment CLAUDE.md donne une mémoire durable à votre projet
• Les trois emplacements du fichier et leur portée : projet, personnel, sous-dossier
• La création avec /init, et l’enrichissement à la volée avec le préfixe # et /memory
• Ce qu’un bon CLAUDE.md contient, et ce qu’il ne doit surtout pas contenir
• Comment en faire un contrat d’équipe, relu et amélioré comme du code

Le problème : Claude oublie tout entre deux sessions

Commençons par une observation frustrante. Vous passez une heure avec Claude Code. Vous lui expliquez que les tests se lancent avec npm run test. Que les composants se nomment en PascalCase, c’est-à-dire avec une majuscule à chaque mot. Que le dossier legacy ne doit surtout pas être modifié. La session se termine. Le lendemain, vous relancez claude… et tout est à réexpliquer.

Pourquoi ? Parce que chaque session démarre avec un contexte vierge. Le contexte, retenez bien ce mot, c’est la mémoire de travail de Claude : tout ce qu’il sait de la conversation en cours. Quand la session se ferme, cette mémoire s’efface. Intégralement.

La solution tient dans un fichier : CLAUDE.md. Un simple fichier texte au format markdown, posé dans votre projet. Sa particularité : Claude Code le lit automatiquement au démarrage de chaque session. Tout ce qu’il contient est injecté dans le contexte avant même votre premier message.

Pensez au cahier de consignes qu’on laisse au remplaçant dans une boulangerie : le four chauffe lentement, le fournisseur livre le mardi, la clé de la réserve est dans le tiroir. Le remplaçant change chaque semaine, mais le cahier reste. CLAUDE.md, c’est ce cahier. Vous l’écrivez une fois, chaque session en profite.

Trois emplacements, trois portées

CLAUDE.md n’est pas un fichier unique. Il peut vivre à trois endroits, et chaque emplacement a sa portée. Regardez bien la logique, elle est très naturelle.

À la racine du projet : la mémoire d’équipe

Le premier emplacement, le plus important : ./CLAUDE.md, à la racine de votre projet. Ce fichier est versionné dans git, c’est-à-dire enregistré dans l’historique du projet et partagé avec toute personne qui clone le dépôt. Vos conventions, vos commandes de build, vos pièges connus : tout vit ici. Un nouveau développeur rejoint l’équipe ? Son Claude Code connaît les règles de la maison dès la première session.

Dans votre dossier personnel : vos préférences à vous

Deuxième emplacement : ~/.claude/CLAUDE.md, dans votre dossier utilisateur. Le tilde, ce petit signe ondulé, désigne votre répertoire personnel. Ce fichier vous suit dans tous vos projets, mais ne quitte jamais votre machine. C’est l’endroit idéal pour vos préférences : répondre en français, expliquer les choix avant de modifier un fichier, privilégier tel style de code.

Dans les sous-dossiers : des consignes locales

Troisième possibilité : placer un CLAUDE.md dans un sous-dossier du projet. Celui-ci n’est pas chargé au démarrage. Il est lu à la demande, quand Claude travaille sur des fichiers de ce dossier. Imaginez le règlement général affiché à l’entrée de l’usine, puis des consignes spécifiques sur la porte de chaque atelier. Le dossier api/ a ses règles de validation, le dossier front/ a ses conventions de composants : chacun garde ses consignes chez lui.

💡 Astuce — Il existe un quatrième fichier, plus discret : CLAUDE.local.md, à la racine du projet. Il fonctionne comme CLAUDE.md, mais il est destiné à vos notes personnelles sur ce projet précis : vos adresses de test, vos données de démonstration. Ajoutez-le au fichier .gitignore pour qu’il ne soit jamais partagé avec l’équipe.

Créer le fichier : /init, puis l’enrichir à la volée

Bonne nouvelle : vous n’avez pas à rédiger ce fichier à la main. Claude Code sait générer une première version tout seul. Placez-vous à la racine de votre projet et lancez une session.

cd mon-projet   # se placer à la racine du projet
claude          # lancer la session interactive

Dans la session, tapez la commande /init. Claude analyse alors votre projet : la structure des dossiers, les fichiers de configuration, les scripts disponibles. Il en déduit un premier CLAUDE.md avec les commandes de build, les instructions de test et les conventions qu’il a repérées. Et si un CLAUDE.md existe déjà, /init propose des améliorations au lieu de l’écraser.

Cette première version est un point de départ, pas un aboutissement. La vraie valeur vient de l’enrichissement au fil des sessions. Et pour cela, il existe un raccourci formidable : le préfixe dièse. Commencez n’importe quel message par le caractère # et l’instruction est mémorisée dans CLAUDE.md.

# Toujours lancer npm run lint avant de proposer un commit

Voilà. Une ligne tapée en trois secondes, et la consigne survivra à toutes vos sessions futures. Enfin, pour relire ou modifier vos fichiers mémoire, tapez /memory : la commande liste les fichiers chargés et vous permet de les éditer.

💡 Astuce — Adoptez la règle des deux fois. La première fois que vous corrigez Claude sur un point, passez. La deuxième fois que vous tapez la même correction, arrêtez-vous : c’est le signal qu’elle mérite une ligne dans CLAUDE.md. Un dièse, une phrase, et cette correction ne sera plus jamais nécessaire.

Quoi mettre : le concret qui fait gagner du temps

Que met-on dans ce fichier ? Retenez cinq familles de contenu, toutes guidées par la même question : qu’est-ce que je réexplique à chaque session ?

Première famille : les commandes exactes. Build, test, vérification du style. Pas des descriptions vagues, des commandes copiables-collables. « Les tests se lancent avec npm run test » vaut infiniment mieux que « pense à tester ».

Deuxième famille : les conventions de code. Le nommage des fichiers, le style d’indentation, la langue des commentaires. Tout ce qu’une revue de code vous ferait corriger.

Troisième famille : l’architecture en cinq lignes. Pas un schéma complet, juste l’essentiel : où vit le front, où vit l’API, qui a le droit de parler à qui.

Quatrième famille : les pièges connus du projet. Le dossier en cours de migration, la dépendance capricieuse, le fichier généré qu’il ne faut jamais éditer à la main. C’est souvent la partie la plus précieuse : elle évite les erreurs avant qu’elles n’arrivent.

Cinquième famille : les définitions métier. Chaque projet a son vocabulaire. Si « commande validée » a un sens précis dans votre application, écrivez-le. Claude utilisera vos mots correctement.

Quoi ne pas mettre : la sobriété est une vertu

Aussi important que le contenu : ce qu’il faut laisser dehors. Trois choses.

Pas de romans. Chaque ligne de CLAUDE.md est chargée à chaque session et consomme du contexte, cette mémoire de travail limitée dont nous parlions. Une documentation de cinquante pages recopiée dans CLAUDE.md, c’est un loyer payé à chaque session pour des informations qui ne servent presque jamais. Visez un fichier qui tient sur un écran ou deux.

Pas d’évidences. Claude connaît déjà React, git et les bonnes pratiques générales. Écrire « bien indenter le code » n’apporte rien. Réservez chaque ligne à ce qui est spécifique à votre projet.

Et surtout : pas de secrets. Jamais.

⚠️ Piège courant — CLAUDE.md est un fichier versionné, partagé, lisible par toute l’équipe et par tout outil qui accède au dépôt. On n’y met JAMAIS de clé d’API, de mot de passe ou de jeton d’accès. Si une commande a besoin d’un secret, indiquez où le trouver — une variable d’environnement, un gestionnaire de secrets — sans jamais écrire sa valeur.

Les imports : découper sans disperser

Votre CLAUDE.md grossit et vous aimeriez l’organiser ? Il existe une syntaxe d’import : écrivez un arobase suivi d’un chemin de fichier, et le contenu de ce fichier est inclus dans votre CLAUDE.md.

Voir @README pour la présentation générale du projet.

## Conventions détaillées
- Style de code : @docs/conventions.md
- Processus de revue : @docs/revue-de-code.md

L’intérêt est double. D’abord, vous réutilisez la documentation existante au lieu de la dupliquer : le README évolue, CLAUDE.md en profite automatiquement. Ensuite, l’équipe peut maintenir des fichiers thématiques courts plutôt qu’un gros bloc monolithique. Les imports peuvent même être récursifs : un fichier importé peut en importer un autre, jusqu’à une profondeur maximale de cinq niveaux.

⚠️ Piège courant — Les imports organisent votre mémoire, mais ne l’allègent pas. Les fichiers importés sont chargés au démarrage, exactement comme le CLAUDE.md qui les référence. Importer une documentation de 2 000 lignes revient à les recopier. Découpez pour la lisibilité, oui ; mais la discipline de concision s’applique à l’ensemble.

Exemple complet : un CLAUDE.md efficace pour un projet web

Assez de théorie. Voici un CLAUDE.md complet pour une boutique en ligne fictive. Une trentaine de lignes, cinq sections, et chaque ligne mérite sa place.

# Boutique Lumen — guide pour Claude

## Le projet en bref
Site e-commerce en Node.js et React.
Front dans app/, API dans server/, tests dans tests/.
Base de données PostgreSQL, accédée uniquement via server/db/.

## Commandes
- Développement : npm run dev
- Tests : npm run test (à lancer avant tout commit)
- Vérification du style : npm run lint
- Build de production : npm run build

## Conventions de code
- Composants React en PascalCase : PanierResume.tsx
- Fonctions utilitaires en camelCase, dans app/utils/
- Indentation : 2 espaces, pas de point-virgule
- Textes visibles par l'utilisateur : toujours en français

## Architecture
Le front appelle l'API via app/api/client.ts, jamais en direct.
Les prix sont TOUJOURS manipulés en centimes (nombres entiers).
La conversion en euros se fait uniquement à l'affichage.

## Pièges connus
- server/legacy/ est en cours de migration : ne pas y ajouter de code
- Les tests de paiement exigent une clé de test (voir le README)

## Vocabulaire métier
- « Panier abandonné » : panier sans commande depuis 48 heures
- « Référence » : identifiant produit au format LUM-XXXX

Analysons pourquoi ce fichier fonctionne. La présentation tient en trois lignes : Claude sait immédiatement où chercher quoi. Les commandes sont exactes, prêtes à l’emploi, avec une consigne d’usage — les tests avant chaque commit. Les conventions sont vérifiables : PascalCase, 2 espaces, français. Aucune place à l’interprétation.

La section architecture est mon passage préféré : la règle des centimes. C’est typiquement le genre de décision invisible qui provoque des bugs coûteux — au sens propre — quand on l’ignore. Une ligne dans CLAUDE.md, et Claude ne convertira jamais un prix au mauvais endroit. Les pièges connus protègent le dossier legacy, et le vocabulaire métier garantit que « panier abandonné » signifie la même chose pour vous et pour l’IA.

Trente lignes. Pas une de plus. Et pourtant, ce fichier transforme chaque session : Claude ne redécouvre plus, il sait.

En équipe : un contrat relu comme du code

Terminons par un changement de perspective. Dès que vous travaillez à plusieurs, CLAUDE.md n’est plus une note personnelle : c’est le contrat entre l’équipe et l’IA. Il définit ce que tout assistant, sur toutes les machines, doit savoir et respecter.

Et un contrat, ça se relit. Traitez CLAUDE.md exactement comme du code : chaque modification passe par une pull request, cette demande de relecture avant fusion dans le projet. L’équipe discute, amende, valide. Vous changez une convention de nommage ? La mise à jour de CLAUDE.md fait partie de la même contribution que le code concerné.

Ce rituel a une vertu cachée : il force l’équipe à expliciter ses règles. Beaucoup d’équipes découvrent, en rédigeant leur premier CLAUDE.md, que leurs conventions n’étaient écrites nulle part. Le fichier destiné à l’IA devient la meilleure documentation d’accueil pour les humains. Si des termes comme dépôt, commit ou markdown restent flous, notre glossaire les définit simplement, et notre dossier IA replace ces outils dans le paysage plus large des assistants.

💡 Astuce — Relisez votre CLAUDE.md tous les deux ou trois mois. Les projets évoluent, les consignes vieillissent. Une instruction obsolète est pire qu’une instruction absente : Claude la suivra consciencieusement. Profitez-en pour supprimer, fusionner, raccourcir. Un bon CLAUDE.md maigrit aussi souvent qu’il grossit.

À vous de jouer

Passons à la pratique sur votre propre projet. Comptez dix minutes.

1. Ouvrez un terminal à la racine d’un vrai projet — le vôtre, pas un exemple — et lancez claude.
2. Tapez /init et laissez Claude analyser le projet. Lisez attentivement sa proposition avant de l’accepter : c’est un excellent aperçu de ce qu’il comprend de votre code.
3. Ouvrez le fichier généré avec /memory et repérez ce qui manque : quelle convention, quel piège, quelle habitude d’équipe Claude ne pouvait pas deviner ?
4. Ajoutez trois conventions réelles de votre projet : une règle de nommage, une règle de style, une règle d’organisation des dossiers.
5. Ajoutez la commande de test exacte, avec la consigne de la lancer avant tout commit.
6. Fermez la session, relancez claude, puis demandez : quelle commande dois-je utiliser pour lancer les tests ? Si Claude répond juste, sans chercher, votre mémoire de projet est en place.

En résumé

• Chaque session Claude Code démarre avec un contexte vierge ; CLAUDE.md est le fichier lu automatiquement au démarrage qui donne une mémoire durable au projet.
• Trois emplacements, trois portées : ./CLAUDE.md à la racine (équipe, versionné dans git), ~/.claude/CLAUDE.md (vos préférences, tous projets), et des CLAUDE.md de sous-dossiers chargés à la demande.
• /init génère une première version, le préfixe # mémorise une instruction en cours de session, /memory permet de relire et d’éditer.
• Contenu gagnant : commandes exactes, conventions vérifiables, architecture en cinq lignes, pièges connus, vocabulaire métier. À proscrire : les romans, les évidences, et surtout les secrets.
• La syntaxe @chemin importe d’autres fichiers (profondeur maximale de cinq niveaux), mais les imports sont chargés eux aussi : concision obligatoire.
• En équipe, CLAUDE.md est un contrat avec l’IA : il se modifie en pull request et se relit régulièrement, comme du code.

Votre projet a désormais une mémoire. Dans le prochain module, vous allez lui donner des règles : le fichier settings.json et le système de permissions, pour décider finement ce que Claude a le droit de faire — et partager ces garde-fous avec toute votre équipe.