Si vous devez retenir une seule chose sur Claude Code, c’est celle-ci : un bon CLAUDE.md vaut dix fois mieux que dix prompts bien écrits. Ce petit fichier markdown, déposé à la racine de votre projet, est le brief permanent que Claude lit à chaque démarrage. Contexte du projet, conventions de code, stack technique, commandes utiles, pièges à éviter : tout ce que vous répétez à chaque session peut y aller une bonne fois pour toutes.
Dans ce guide, on va voir ce qu’est vraiment CLAUDE.md, où le placer selon votre usage, comment le structurer pour qu’il soit utile sans saturer le contexte, un exemple concret que vous pouvez copier, et les erreurs que je vois dans 80% des projets. Pratique, rien d’autre.
CLAUDE.md, c’est quoi ?
CLAUDE.md est un fichier texte que Claude Code injecte automatiquement dans son contexte au démarrage d’une session. Pensez-y comme au README d’un nouveau collègue qui rejoint le projet : tout ce qu’il doit savoir pour être immédiatement utile, sans avoir à poser 15 questions à chaque fois.
Le fichier est lu avant tout prompt utilisateur. Claude sait donc d’emblée dans quel projet il est, quelle stack vous utilisez, comment vous écrivez votre code, et ce que vous ne voulez surtout pas qu’il fasse. Pas besoin de le répéter au début de chaque conversation.
Contrairement aux mémoires Claude (qui sont globales au compte utilisateur), CLAUDE.md est versionné avec le projet. Il vit dans Git. Toute votre équipe en bénéficie. Si vous travaillez seul, c’est votre second cerveau projet. Si vous travaillez à plusieurs, c’est la source de vérité partagée.
Pourquoi c’est le fichier le plus important de votre projet
La différence entre Claude Code avec et sans CLAUDE.md est énorme. Je l’ai mesurée sur plusieurs projets :
- Sans CLAUDE.md : Claude passe 2 à 3 tours à comprendre votre projet, lit des fichiers au hasard, pose des questions, parfois propose du code dans le mauvais framework
- Avec CLAUDE.md bien fait : Claude attaque directement la bonne partie du code, utilise les bonnes conventions, appelle les bonnes commandes, évite vos pièges connus
En pratique, ça représente facilement 30 à 50% de tokens économisés, et surtout moins de frustration. Vous passez moins de temps à corriger Claude et plus de temps à construire.
Il y a aussi un effet plus subtil : avec un bon CLAUDE.md, Claude adopte votre style. Si votre doc mentionne « on préfère les fonctions pures aux classes » ou « toujours valider avec Zod avant d’appeler l’API », il le fait spontanément. Plus besoin de corriger.
Où placer votre CLAUDE.md (et les 3 niveaux)
Claude Code lit CLAUDE.md à trois niveaux, dans cet ordre de priorité :
1. Racine du projet (le plus courant)
Placez CLAUDE.md à la racine de votre repo, au même niveau que package.json ou pyproject.toml. C’est l’emplacement standard, versionné avec Git, partagé avec toute l’équipe.
2. Sous-dossiers
Vous pouvez aussi placer un CLAUDE.md dans un sous-dossier (par exemple frontend/CLAUDE.md et backend/CLAUDE.md). Claude les charge quand il travaille dans ces dossiers. Pratique pour des monorepos ou des projets avec des stacks très différentes selon la partie.
3. Global utilisateur
Le fichier ~/.claude/CLAUDE.md contient des préférences qui s’appliquent à tous vos projets. Utile pour « j’aime les messages de commit au format conventional commits » ou « toujours utiliser pnpm chez moi ». Attention à ne pas y mettre de contexte projet spécifique.
Les trois niveaux se cumulent. Claude charge le global d’abord, puis celui de la racine, puis celui du sous-dossier courant. En cas de conflit, le plus spécifique gagne.
La structure qui fonctionne vraiment
Un CLAUDE.md efficace fait entre 150 et 400 lignes. En dessous, vous manquez de contexte utile. Au-dessus, vous saturez la fenêtre de contexte pour peu de gain. Voici la structure que j’utilise systématiquement et qui donne les meilleurs résultats :
1. Vue d’ensemble du projet (5-10 lignes)
Qu’est-ce que c’est ? Pour qui ? Quel problème ça résout ? Très court, factuel.
2. Stack technique (liste simple)
Langages, frameworks, bibliothèques principales, outils de build. Pas besoin de justifier, juste lister.
3. Architecture et dossiers importants
Une carte minimale des dossiers clés avec ce qu’on y trouve. Pas besoin de tout lister, juste les endroits où Claude aura besoin d’aller souvent.
4. Conventions de code
Le style que vous préférez : fonctions vs classes, conventions de nommage, patterns récurrents, ce qu’on évite.
5. Commandes utiles
Les commandes shell que Claude peut lancer sans demander : build, tests, lint, dev server. Listez-les clairement.
6. Pièges connus et règles dures
Les choses à ne jamais faire. C’est probablement la section la plus sous-exploitée. Chaque fois que vous corrigez Claude sur la même erreur, ajoutez une règle ici.
7. Workflow de test
Comment Claude doit vérifier son travail avant de dire « c’est fini » : lancer les tests, faire tourner le lint, tester dans le navigateur, etc.
Exemple complet commenté
Voici un CLAUDE.md réel, utilisé sur un projet Next.js + WordPress headless. Il a été nettoyé des infos sensibles mais la structure est authentique.
# MonProjet
Site éditorial IA francophone. Next.js 16 App Router avec WordPress headless en backend. Articles, outils IA, pages comparatif.
## Stack
- Next.js 16.1.7 App Router + TypeScript strict
- Tailwind CSS v3.4.19 (NE PAS upgrader vers v4, crash prod)
- WordPress GraphQL (WPGraphQL plugin) pour le contenu
- Vercel pour le déploiement
## Structure
- `src/app/` : pages App Router
- `src/components/` : composants réutilisables
- `src/lib/` : queries GraphQL, helpers, configs
- `content/articles/` : articles HTML avant publication WP
## Conventions
- TypeScript strict partout, pas de `any`
- Composants React en fonctions pures, pas de classes
- Styling via Tailwind utility-first, pas de CSS modules
- Imports absolus avec l'alias `@/`
## Commandes
- `npm run dev` : dev server sur :3000
- `npm run build` : build prod
- `npm run lint` : ESLint (à lancer avant chaque commit)
## Règles dures
- Ne JAMAIS router GraphQL via le domaine public (intercepté par Vercel)
- Ne JAMAIS entourer `permanentRedirect` d'un try/catch (avale la RedirectError)
- Migration Lucide : utiliser `lucide-react`, pas le CDN
## Workflow de test
1. Build doit passer sans warning
2. Lint doit passer
3. Pour les changements UI : tester en navigateur sur desktop + mobileMoins de 50 lignes, mais chaque ligne porte une info que Claude ne peut pas deviner en lisant le code. C’est ça le critère : si Claude peut l’apprendre en 10 secondes en lisant un fichier, ça n’a rien à faire dans CLAUDE.md.
Les 7 erreurs classiques à éviter
1. Écrire un roman
Plus de 500 lignes = vous saturez le contexte. Claude ne peut pas tout intégrer utilement. Coupez, synthétisez.
2. Dupliquer ce qui est dans le code
Pas besoin de lister toutes vos dépendances, package.json le fait déjà. Pas besoin d’expliquer ce que fait chaque fichier, les noms le disent. Gardez ce qui n’est PAS dans le code.
3. Écrire au futur ou au conditionnel
« On pourrait utiliser Zustand plus tard » n’aide pas. Claude a besoin de l’état présent. Écrivez ce qui EST, pas ce qui POURRAIT être.
4. Oublier les règles négatives
On liste ce qu’on fait, rarement ce qu’on évite. Or les règles négatives (NE PAS upgrader, NE PAS utiliser X, NE JAMAIS appeler Y) sont souvent celles qui économisent le plus de temps.
5. Ne pas mettre à jour
Un CLAUDE.md daté fait plus de mal que de bien. Si votre stack change, mettez à jour immédiatement. Sinon Claude applique de vieilles règles.
6. Mélanger projet et préférences personnelles
« J’aime les emojis dans les commits » n’a rien à faire dans le CLAUDE.md racine, c’est une préférence perso. Mettez-le dans votre CLAUDE.md global utilisateur.
7. Écrire en anglais un projet français
Si votre équipe communique en français, écrivez CLAUDE.md en français. Le modèle adapte alors sa langue de réponse. L’inverse est vrai aussi pour un projet international.
Générer un CLAUDE.md avec /init
Claude Code embarque une commande qui analyse votre projet et génère un CLAUDE.md de base : tapez /init dans une session. Claude va parcourir votre repo, lire les fichiers clés (package.json, README, configs), et produire un premier jet que vous pouvez ensuite ajuster.
Conseil : ne gardez pas tel quel. La sortie de /init est un point de départ, pas un livrable. Elle contient souvent des évidences (votre stack en listant tous les packages) et rate les subtilités que seul le dev connaît (les pièges, les conventions internes). Ajustez, élaguez, enrichissez.
Cas d’usage typique : /init sur un projet que vous reprenez, où vous n’êtes pas à l’aise pour écrire le CLAUDE.md de zéro. Ça donne une base correcte en 30 secondes.
Comment maintenir son CLAUDE.md dans la durée
Un bon CLAUDE.md vit. Voici ma routine :
Chaque fois que je corrige Claude sur la même erreur deux fois : j’ajoute une règle dans le CLAUDE.md. Si je dois dire « utilise lucide-react, pas le CDN » trois fois, c’est que c’est une règle du projet, pas un rappel ponctuel.
À chaque gros changement de stack : relecture en 5 minutes. Upgrade de Next ? Nouvelle lib ajoutée ? Règle de sécurité renforcée ? Le CLAUDE.md doit refléter l’état courant.
Une fois par mois environ : passage complet. Je lis le fichier, je supprime ce qui est obsolète, je resserre ce qui est trop verbeux. 10 minutes, gros ROI.
Versionnez-le : CLAUDE.md fait partie du code. Il est committé, reviewé, discuté en PR. Quand un collègue modifie une convention, la PR doit inclure la mise à jour du CLAUDE.md. Sinon le fichier décroche du réel en quelques semaines.
CLAUDE.md vs mémoires personnelles
Claude Code a aussi un système de « mémoires » personnelles, stockées dans ~/.claude/memory/. Quelle est la différence ?
- CLAUDE.md = contexte projet, versionné dans Git, partagé avec l’équipe, s’applique à tous les utilisateurs qui ouvrent ce projet
- Mémoires = notes personnelles persistantes entre sessions, apprises automatiquement (qui êtes-vous, vos préférences, le contexte de votre travail), globales à votre compte
En pratique, Claude utilise les deux ensemble. Votre CLAUDE.md dit « on utilise Tailwind v3 ». Vos mémoires disent « Ugo travaille sur LesAstucesIA, préfère les explications courtes, déteste les em dashes ». Les deux s’enrichissent mais ne se chevauchent pas.
Règle simple : tout ce qui est vrai pour tous les contributeurs du projet va dans CLAUDE.md. Tout ce qui vous concerne vous personnellement reste en mémoire.
Questions fréquentes
CLAUDE.md fonctionne-t-il avec Claude (claude.ai) ou seulement Claude Code ?
CLAUDE.md est spécifique à Claude Code et à ses variantes (Claude Desktop, extensions IDE, SDK). L’interface web claude.ai n’a pas accès à votre système de fichiers, donc ne peut pas lire votre CLAUDE.md. Pour un usage similaire sur claude.ai, utilisez les Projets avec des instructions système.
Peut-on inclure du code dans CLAUDE.md ?
Oui, mais avec parcimonie. Des exemples courts (3-10 lignes) pour illustrer une convention sont utiles. Éviter les gros blocs de code : Claude peut de toute façon lire les fichiers. Privilégiez les références « voir src/lib/auth.ts pour l’exemple canonique ».
Faut-il un CLAUDE.md pour un projet perso d’une soirée ?
Non. Pour un script jetable ou un projet d’une soirée, CLAUDE.md est du sur-équipement. Dès que vous prévoyez de revenir sur le projet une semaine plus tard, oui.
Combien de temps ça prend à écrire ?
Pour un projet existant que vous connaissez, entre 20 et 45 minutes pour une première version solide. Avec /init comme point de départ, divisez ce temps par deux. Le ROI arrive en quelques sessions.
Est-ce que Claude lit VRAIMENT mon CLAUDE.md à chaque session ?
Oui, dès qu’il est présent à la racine du projet (ou dans un sous-dossier pertinent). Vous pouvez vérifier en demandant à Claude « quelles règles connais-tu sur ce projet ? » au début d’une session. Il doit restituer vos règles clés.
Puis-je avoir un CLAUDE.md privé, non versionné ?
Techniquement oui, ajoutez CLAUDE.md au .gitignore. Mais vous perdez tout l’intérêt du partage d’équipe. Alternative plus propre : utilisez CLAUDE.local.md pour vos notes perso (et ajoutez seulement celui-ci au .gitignore).
Ça marche avec les subagents ?
Oui. Les subagents héritent du CLAUDE.md du projet au même titre que l’agent principal. Un subagent qui explore votre codebase lira donc vos conventions et s’y tiendra.
En résumé
CLAUDE.md est probablement le meilleur investissement que vous pouvez faire en 30 minutes pour Claude Code. Un fichier concis, à jour, qui liste stack, conventions, commandes et pièges. Versionné avec le projet, partagé avec l’équipe. Mis à jour dès qu’une règle émerge.
Commencez aujourd’hui : /init dans votre projet, élaguez, ajoutez vos 3-5 règles dures que vous répétez le plus souvent à Claude. Testez sur deux sessions. Vous verrez la différence immédiatement.
Si vous voulez aller plus loin sur Claude Code, lisez notre guide complet Claude Code qui couvre Plan Mode, MCP, subagents, hooks et workflows avancés.
Articles similaires
Dans la catégorie Claude