CLAUDE.md : comment configurer la mémoire de votre projet Claude Code ? (guide 2026)

TL;DR — L'essentiel en 5 points

Un fichier CLAUDE.md bien rédigé réduit d'environ 40 % les rappels manuels que vous devez donner à Claude Code d'une session à l'autre (SFEIR Institute, 2026). Voici pourquoi c'est le premier levier de productivité à activer, et comment le faire correctement.

Qu'est-ce que le fichier CLAUDE.md et à quoi sert-il ?

Le CLAUDE.md est un fichier Markdown que Claude Code lit automatiquement au démarrage de chaque session et injecte dans son prompt système. Concrètement, c'est la mémoire persistante de votre projet : au lieu de réexpliquer à chaque conversation votre stack, vos conventions de code ou vos commandes de build, vous les écrivez une fois dans ce fichier et Claude s'en souvient à chaque fois.

Sans CLAUDE.md, chaque nouvelle session repart de zéro : Claude devine votre architecture, choisit un style de code qui n'est pas le vôtre, relance des commandes qui échouent. Avec un CLAUDE.md soigné, il connaît d'emblée vos règles. C'est la différence entre un assistant qui vous connaît et un intérimaire qui débarque chaque matin.

Trois niveaux de fichiers cohabitent, chargés dans cet ordre de priorité :

Le fichier projet est le plus impactant : versionné avec Git, il fait bénéficier toute l'équipe des mêmes instructions.

Comment structurer un CLAUDE.md efficace ?

Un bon CLAUDE.md n'est pas un roman. Il est court, spécifique et vérifiable. Voici les sections qui rapportent le plus :

1. Vue d'ensemble du projet — 2-3 phrases : ce que fait l'app, la stack principale.
2. Commandes clés — build, test, lint, dev. Claude les relance sans vous demander.
3. Conventions de code — indentation, nommage, gestion des erreurs, patterns imposés.
4. Architecture — où vivent les composants, les routes, la data ; ce qu'il ne faut pas toucher.
5. Règles interdites — « ne jamais modifier les migrations existantes », « ne pas commiter sans lancer les tests ».

La règle d'or : une instruction spécifique et vérifiable vaut mieux que dix génériques. « Écrire du code propre » ne veut rien dire pour un agent. « Indentation 2 espaces, pas de tabulations, point-virgules obligatoires, imports triés » est actionnable et vérifiable.

« Au-delà d'environ 150 lignes, Claude Code commence à oublier les instructions du milieu du fichier. Restez concis : un fichier utilisateur de 50 lignes + un fichier projet de 80 lignes + 5 règles modulaires produit environ 2 000 tokens, soit moins de 1 % de la fenêtre de contexte. » — *SFEIR Institute, guide d'optimisation CLAUDE.md, 2026*

Exemple minimal de squelette à copier :

@@@

# Projet : API de facturation

Stack - Node 20, TypeScript, Fastify, PostgreSQL (Prisma)

Commandes - Dev : npm run dev - Test : npm test (Vitest) - Lint : npm run lint (bloquant avant commit)

Conventions - 2 espaces, pas de tabs. Point-virgules obligatoires. - Erreurs : jamais de throw brut, toujours AppError typé. - Pas de any TypeScript.

Interdits - Ne jamais éditer les migrations Prisma déjà appliquées. - Ne pas commiter si npm test échoue. @@@

Quelles erreurs éviter avec CLAUDE.md ?

Les fichiers CLAUDE.md qui échouent partagent presque toujours les mêmes défauts. En voici quatre à bannir :

• Le fichier fleuve : 400 lignes de contexte « au cas où ». Chaque ligne inutile dilue les instructions importantes. Si une règle n'a pas gagné sa place, supprimez-la.
• Les règles vagues : « code de qualité », « respecte les bonnes pratiques ». Non vérifiable = ignoré.
• La documentation morte : commandes qui n'existent plus, chemins obsolètes. Un CLAUDE.md faux est pire que pas de CLAUDE.md, car Claude fait confiance à ce qu'il lit.
• Les comportements automatiques mal placés : « à chaque fois que je fais X, fais Y » relève souvent d'un hook, pas d'une instruction mémoire. Le CLAUDE.md décrit *quoi*, les hooks exécutent *quand*.

Autre bonne pratique : utilisez le raccourci # en cours de session. Taper # toujours lancer les tests avant un commit ajoute automatiquement la règle au CLAUDE.md — vous construisez votre mémoire au fil de l'eau, sans quitter le terminal.

Selon la documentation officielle Anthropic (2026), les instructions doivent être structurées en Markdown avec des titres clairs : Claude navigue mieux dans un fichier hiérarchisé que dans un pavé de texte. Et pensez aux imports : un @docs/architecture.md dans le CLAUDE.md charge un fichier externe uniquement quand c'est pertinent, ce qui garde le fichier principal léger.

Auto Memory : la mémoire qui se met à jour toute seule

Depuis 2026, Claude Code dispose aussi d'une mémoire automatique : à chaque session, il enregistre des notes persistantes dans un dossier dédié au projet et les relit au démarrage suivant. Combinée à un CLAUDE.md manuel bien tenu, elle forme une hiérarchie complète : utilisateur → projet → règles modulaires → auto-mémoire, chaque niveau enrichissant le contexte sans surcharger le précédent.

La différence : le CLAUDE.md, c'est vous qui l'écrivez (règles délibérées, stables) ; l'auto-mémoire, c'est Claude qui la construit (apprentissages émergents au fil des sessions). Les deux se complètent. Ne mettez pas dans le CLAUDE.md ce que l'auto-mémoire capture déjà, et inversement gardez dans le CLAUDE.md les règles que vous voulez garantir à 100 %.

Impact mesuré : les projets équipés d'un CLAUDE.md structuré réduisent d'environ 40 % les rappels manuels nécessaires par session (SFEIR Institute, 2026), et le temps de démarrage réel sur une nouvelle tâche chute nettement puisque Claude n'a plus à redécouvrir le terrain.

FAQ

Où dois-je placer mon fichier CLAUDE.md ?

À la racine de votre projet (./CLAUDE.md) pour les règles partagées avec l'équipe, versionné dans Git. Pour vos préférences personnelles valables sur tous vos projets, utilisez ~/.claude/CLAUDE.md. Pour des notes locales non partagées, ./CLAUDE.local.md (à ajouter au .gitignore).

Quelle est la taille idéale d'un CLAUDE.md ?

Restez sous 150 lignes pour le fichier projet. Au-delà, Claude commence à négliger les instructions du milieu du fichier. Un CLAUDE.md efficace fait souvent 50 à 100 lignes ; la concision est une fonctionnalité, pas une contrainte.

Faut-il versionner le CLAUDE.md dans Git ?

Oui pour le CLAUDE.md de projet : c'est ce qui permet à toute l'équipe de bénéficier des mêmes règles et de les faire évoluer en revue de code. Non pour les fichiers personnels (~/.claude/CLAUDE.md) et locaux (CLAUDE.local.md).

Quelle différence entre CLAUDE.md et un hook ?

Le CLAUDE.md décrit le *contexte* et les *règles* que Claude lit et interprète. Un hook est un script shell que Claude Code exécute *automatiquement* sur un événement (avant un commit, à chaque écriture de fichier). Pour un comportement déterministe garanti (« bloque toujours rm -rf »), utilisez un hook ; pour guider les décisions de Claude, utilisez le CLAUDE.md.

Comment savoir si mon CLAUDE.md est bien pris en compte ?

Lancez /memory dans Claude Code : la commande affiche tous les fichiers mémoire chargés et leur hiérarchie. Vous pouvez aussi demander directement à Claude de résumer les règles qu'il a en tête pour votre projet.

---

*Pour aller plus loin : découvrez comment créer vos propres skills Claude Code pour automatiser vos tâches récurrentes, et comment automatiser votre business avec hooks, skills et agents. Envie de maîtriser Claude Code de A à Z avec des exercices pratiques et du coaching en français ? MaitriseLIA propose une formation dédiée.*