CLAUDE.md : Guide Complet, Templates et Memory.md (2026)

Mis à jour le 21 avril 2026  ·  Guide vérifié contre la dernière version de Claude Code et la documentation officielle Anthropic.

Vous utilisez Claude Code tous les jours, mais vous passez 15 minutes à chaque session à ré-expliquer votre stack, vos conventions et vos commandes de build ? Multipliez par 4 sessions par jour et vous perdez une heure. Chaque jour. La solution tient en un seul fichier de 80 lignes : CLAUDE.md.

Ce fichier Markdown, placé à la racine de votre projet, agit comme la mémoire persistante de Claude Code. Il est lu automatiquement au lancement de chaque session. Résultat : Claude connaît déjà votre projet, vos règles, vos préférences. Plus besoin de vous répéter.

Dans ce guide complet, mis à jour en avril 2026, vous allez découvrir :

• 3 templates CLAUDE.md prêts à l''emploi (SaaS, landing page, app mobile) à copier-coller

• La hiérarchie complète des 5 types de mémoire (global, projet, local, rules, auto-memory)

• Les 7 erreurs courantes qui font qu''un CLAUDE.md devient inefficace

• Comment débugger quand Claude Code ignore votre fichier de configuration

Qu''est-ce que CLAUDE.md et pourquoi c''est indispensable

CLAUDE.md est un fichier Markdown que Claude Code lit automatiquement au démarrage de chaque session. Il contient vos instructions, vos conventions et le contexte de votre projet. Pensez à lui comme un briefing permanent que vous donnez à votre assistant IA — certains l''appellent aussi le fichier d''instructions Claude ou le context file.

Sans CLAUDE.md, voici ce qui se passe à chaque nouvelle conversation :

• Vous ré-expliquez que le projet utilise Next.js 15 avec l''App Router

• Vous rappelez la préférence pour Tailwind CSS et les composants shadcn/ui

• Vous redites que les tests doivent utiliser Vitest et non Jest

• Vous re-précisez que la base de données est sur Supabase

Avec CLAUDE.md, tout cela est chargé automatiquement. Claude Code sait déjà tout. Il respecte vos conventions dès la première ligne de code générée. Selon la documentation officielle d''Anthropic, c''est le levier numéro un pour améliorer la qualité des réponses.

Le concept de Context Engineering

CLAUDE.md s''inscrit dans une discipline émergente appelée Context Engineering : l''art de fournir le bon contexte à une IA pour obtenir les meilleurs résultats possibles. Plutôt que de rédiger des prompts parfaits à chaque requête, vous investissez une fois dans un fichier de configuration qui améliore toutes vos interactions.

C''est exactement ce qui distingue un vibe coder efficace d''un débutant : la capacité à configurer son environnement pour que l''IA comprenne le projet dès le départ.

La hiérarchie des fichiers CLAUDE.md

Claude Code ne se contente pas d''un seul fichier. Il utilise un système hiérarchique avec plusieurs niveaux de mémoire, chacun ayant un rôle précis. Voici comment ils s''imbriquent :

1. User Memory : vos préférences globales (global CLAUDE.md)

Le fichier ~/.claude/CLAUDE.md est le global CLAUDE.md. Il contient vos préférences personnelles qui s''appliquent à tous vos projets. C''est l''endroit idéal pour y mettre :

• Votre style de code préféré (indentation 2 espaces, guillemets simples...)

• Votre langue de communication (réponses en français)

• Vos raccourcis et alias habituels

• Vos préférences d''outils (pnpm plutôt que npm, par exemple)

Conseil : gardez ce fichier très court, 50 lignes maximum. Il est chargé dans chaque session, de chaque projet. Chaque ligne superflue consomme des tokens sur toutes vos conversations.

2. Project Memory : le cœur de votre configuration

C''est le fichier ./CLAUDE.md à la racine de votre dépôt Git. C''est le plus important. Il est partagé avec toute l''équipe via le contrôle de version. C''est ici que vous documentez tout ce que Claude Code doit savoir sur votre projet spécifique.

3. Project Rules : des règles modulaires

Pour les projets complexes, le dossier .claude/rules/ permet de découper vos instructions en fichiers thématiques :

.claude/rules/
├── code-style.md      # Conventions de code
├── testing.md         # Règles de tests
├── api-design.md      # Standards API
└── frontend/
    ├── react.md       # Règles React
    └── styles.md      # Conventions CSS

Ces fichiers supportent même le ciblage conditionnel par chemin. Vous pouvez appliquer des règles uniquement à certains fichiers avec un frontmatter YAML :

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

# Règles API
- Valider toutes les entrées avec Zod
- Utiliser le format de réponse standard

4. Local Memory : vos préférences personnelles sur le projet

Le fichier CLAUDE.local.md est automatiquement ajouté au .gitignore. Il est parfait pour vos préférences personnelles qui ne concernent pas l''équipe : URLs de sandbox, données de test, raccourcis personnels, chemins de dossiers spécifiques à votre machine.

Ordre de priorité

Quand plusieurs fichiers CLAUDE.md existent, les instructions les plus spécifiques l''emportent. La priorité va du plus général (User Memory) au plus spécifique (Local Memory). Si votre fichier global dit « utilise npm » mais que le fichier projet dit « utilise pnpm », Claude Code utilisera pnpm.

Memory.md et l''auto-mémoire de Claude Code

En plus des fichiers CLAUDE.md que vous rédigez manuellement, Claude Code possède un système d''auto-mémoire centré autour du fichier MEMORY.md. Au fil de vos sessions, il note automatiquement ce qu''il apprend sur votre projet — c''est la différence majeure avec .cursorrules ou copilot-instructions.

Où se trouve memory.md

Chaque projet dispose de son propre répertoire de mémoire dans ~/.claude/projects/<projet>/memory/. Ce dossier contient :

~/.claude/projects/mon-projet/memory/
├── MEMORY.md           # Index principal (200 premières lignes chargées)
├── debugging.md        # Notes sur les patterns de debug
├── api-conventions.md  # Conventions API découvertes
└── ...                 # Autres fichiers thématiques

Seules les 200 premières lignes de MEMORY.md sont chargées au démarrage. Les fichiers thématiques sont lus à la demande. C''est pourquoi Claude Code garde MEMORY.md concis et déporte les détails dans des fichiers séparés.

Ce que Claude Code retient automatiquement

• Patterns du projet : commandes de build, conventions de test, préférences de style

• Solutions de debug : corrections de bugs complexes, causes d''erreurs fréquentes

• Architecture : fichiers clés, relations entre modules, abstractions importantes

• Vos préférences : style de communication, habitudes de workflow

Forcer un apprentissage memory.md

Vous pouvez demander explicitement à Claude Code de mémoriser quelque chose :

• « Retiens qu''on utilise pnpm, pas npm »

• « Sauvegarde en mémoire que les tests API nécessitent un Redis local »

• « Note que le endpoint /api/users est déprécié, on utilise /api/v2/users »

Pour modifier manuellement l''auto-mémoire, utilisez la commande /memory dans Claude Code. Elle ouvre le fichier memory.md dans votre éditeur système. C''est aussi la commande à utiliser pour nettoyer la mémoire quand elle devient obsolète.

Memory.md vs CLAUDE.md : quelle différence ?

La distinction est simple : CLAUDE.md est écrit par vous (règles explicites, versionnées dans Git). MEMORY.md est écrit par Claude Code (apprentissages implicites, locaux à votre machine). Les deux se complètent : CLAUDE.md pose les garde-fous, MEMORY.md affine avec l''expérience.

Que mettre dans votre CLAUDE.md : le guide section par section

Voici les sections essentielles d''un fichier CLAUDE.md bien structuré, avec des exemples concrets.

Stack technique et architecture

Commencez toujours par décrire votre stack. Claude Code doit savoir exactement avec quoi il travaille :

# Stack technique
- Framework : Next.js 15 (App Router)
- Langage : TypeScript (strict mode)
- Styling : Tailwind CSS v4 + shadcn/ui
- Base de données : Supabase (PostgreSQL)
- Auth : Supabase Auth
- Déploiement : Vercel
- Package manager : pnpm

Conventions de code

Soyez spécifique. Ne dites pas « écris du code propre ». Dites exactement ce que vous attendez :

# Conventions de code
- Nommage des composants : PascalCase (ex: UserProfile.tsx)
- Nommage des fichiers utilitaires : camelCase (ex: formatDate.ts)
- Toujours utiliser les Server Components par défaut
- ''use client'' uniquement quand nécessaire (interactivité, hooks)
- Exports nommés (pas de default export)
- Types dans des fichiers séparés : src/types/[domaine].ts

Commandes de build et scripts

Documentez vos commandes pour que Claude n''ait pas à fouiller dans votre package.json :

# Commandes
- Dev : pnpm dev (port 3000)
- Build : pnpm build
- Tests : pnpm test (Vitest)
- Test unique : pnpm test -- --run src/path/to/test.ts
- Lint : pnpm lint
- Format : pnpm format
- DB migrate : pnpm supabase db push

Structure du projet

Donnez à Claude une carte mentale de votre architecture :

# Structure du projet
- src/app/ : Routes Next.js (App Router)
- src/components/ : Composants React réutilisables
- src/components/ui/ : Composants shadcn/ui (NE PAS MODIFIER)
- src/lib/ : Utilitaires et helpers
- src/lib/supabase/ : Client et requêtes Supabase
- src/types/ : Types TypeScript
- supabase/migrations/ : Migrations SQL

Instructions spécifiques et garde-fous

C''est ici que vous posez vos limites et vos avertissements :

# Règles importantes
- NE JAMAIS modifier les fichiers dans src/components/ui/ (générés par shadcn)
- NE JAMAIS commit les fichiers .env
- Toujours utiliser les variables d''environnement via process.env
- Les requêtes Supabase passent TOUJOURS par src/lib/supabase/
- Pas de console.log en production, utiliser le logger custom

Imports avec @path : la modularité de CLAUDE.md

Une fonctionnalité puissante et encore sous-utilisée : les imports. Vous pouvez référencer d''autres fichiers directement depuis votre CLAUDE.md avec la syntaxe @path/vers/fichier.

# Documentation du projet
Voir @README.md pour la vue d''ensemble du projet.
Voir @docs/architecture.md pour l''architecture détaillée.
Voir @package.json pour les scripts disponibles.

# Workflow Git
- @docs/git-workflow.md

Pourquoi c''est un game-changer

• Réutilisation : votre README.md sert déjà de doc ? Importez-le plutôt que de dupliquer l''info

• Modularité : découpez vos instructions en fichiers spécialisés

• Fraîcheur : quand votre doc évolue, CLAUDE.md suit automatiquement

• Partage inter-projets : avec des imports absolus, vous partagez des instructions entre dépôts

Règles techniques des imports

• Les chemins relatifs sont résolus par rapport au fichier contenant l''import (pas le répertoire de travail)

• Les imports peuvent être récursifs jusqu''à 5 niveaux de profondeur

• Les chemins absolus et les imports @~/ sont supportés

• Les imports dans les blocs de code (backticks) sont ignorés, ce qui évite les conflits

• La première utilisation d''imports externes déclenche une boîte de dialogue d''approbation pour des raisons de sécurité

3 templates CLAUDE.md prêts à l''emploi

Voici trois exemples de CLAUDE.md prêts à l''emploi selon votre type de projet. Copiez-les, adaptez-les, et vous êtes opérationnel en 5 minutes.

Template 1 : SaaS (Next.js + Supabase)

# Mon SaaS - CLAUDE.md

## Stack
- Next.js 15 (App Router) + TypeScript strict
- Supabase (auth, database, storage)
- Tailwind CSS v4 + shadcn/ui
- Stripe (paiements)
- Vercel (déploiement)
- pnpm

## Commandes
- pnpm dev / pnpm build / pnpm test
- pnpm supabase db push (migrations)
- pnpm stripe:webhook (tunnel local)

## Architecture
- src/app/(auth)/ : pages authentifiées
- src/app/(public)/ : pages publiques
- src/components/ui/ : shadcn (NE PAS MODIFIER)
- src/lib/supabase/ : client et requêtes
- src/lib/stripe/ : helpers Stripe

## Conventions
- Server Components par défaut
- ''use client'' uniquement si nécessaire
- Zod pour toute validation
- Pas de any en TypeScript
- Nommage : PascalCase composants, camelCase utils

## Règles
- RLS activée sur TOUTES les tables Supabase
- Jamais de clé API côté client
- Toujours vérifier l''auth avant les mutations

Template 2 : Landing Page (Astro + React)

# Landing Page - CLAUDE.md

## Stack
- Astro 5 + React (îlots interactifs)
- Tailwind CSS v4
- Framer Motion (animations)
- Vercel (déploiement)

## Commandes
- pnpm dev / pnpm build / pnpm preview

## Design
- Style : moderne, épuré, dark mode par défaut
- Polices : Geist Sans (titres), Geist Mono (code)
- Couleurs principales : voir src/styles/tokens.css
- Mobile-first, breakpoints : sm(640) md(768) lg(1024)

## Conventions
- Sections dans src/components/sections/
- Un composant = un fichier
- Images dans public/images/, WebP obligatoire
- Alt text descriptif sur TOUTES les images

## SEO
- Balises meta dans chaque page
- Structured data JSON-LD sur la home
- Score Lighthouse > 95 obligatoire

Template 3 : Application Mobile (React Native + Expo)

# App Mobile - CLAUDE.md

## Stack
- React Native 0.76 + Expo SDK 52
- TypeScript strict
- React Navigation v7
- Supabase (backend)
- Expo EAS (builds)

## Commandes
- npx expo start (dev)
- npx expo start --ios / --android
- eas build --platform ios/android
- pnpm test (Jest + React Native Testing Library)

## Architecture
- src/screens/ : écrans principaux
- src/components/ : composants partagés
- src/navigation/ : config React Navigation
- src/hooks/ : hooks custom
- src/services/ : appels API

## Conventions
- Styles avec StyleSheet.create (pas d''inline)
- Pas de any TypeScript
- Hooks custom pour la logique métier
- Composants fonctionnels uniquement

Ressource offerte

Pack « 8 CLAUDE.md qui tiennent la route » à télécharger

Les 3 templates ci-dessus + 5 bonus directement utilisables. Format .md propre + version Notion dupliquable, avec la structure que j''utilise sur mes propres projets.

Les 5 templates bonus :

• Chrome Extension (Manifest V3 + TS)

• Monorepo Turborepo (apps + packages partagés)

• API Node.js (Express / Fastify + Prisma)

• Python / FastAPI (venv, pytest, ruff)

• Script data (Python + pandas + Jupyter)

Zéro remplissage, zéro template générique. Chaque fichier est annoté avec les sections pourquoi ça marche pour que tu adaptes à ton stack sans perdre de temps.

Télécharger le pack complet →

Accès immédiat par email · Pas de spam, juste la ressource · Désinscription en 1 clic

Best practices : un CLAUDE.md qui reste efficace

Un fichier CLAUDE.md mal conçu peut être pire que pas de fichier du tout. S''il est trop long ou trop vague, Claude Code commence à ignorer certaines instructions. Voici les règles d''or d''un best CLAUDE.md.

Gardez le fichier lean (court et dense)

La règle empirique : 80 lignes maximum pour le fichier projet principal. Au-delà, Claude Code peut commencer à négliger certaines instructions. Si vous dépassez, utilisez les imports @path ou le dossier .claude/rules/ pour modulariser.

Soyez spécifique, pas générique

Utilisez /init pour démarrer

Pas besoin de partir d''une page blanche. La commande /init dans Claude Code analyse votre projet et génère un CLAUDE.md de base. C''est un excellent point de départ que vous affinez ensuite au fil du temps.

Faites évoluer le fichier avec votre projet

Votre CLAUDE.md n''est pas gravé dans le marbre. Mettez-le à jour quand :

• Vous ajoutez une nouvelle dépendance majeure

• Vous changez de convention de code

• Vous découvrez que Claude Code fait une erreur récurrente

• Vous restructurez votre projet

Les 7 erreurs courantes à éviter

1. Le fichier encyclopédie (trop long) : un CLAUDE.md de 300 lignes consomme trop de tokens. Restez sous 80 lignes pour le fichier principal.

2. Les instructions contradictoires : global vs projet vs local doivent être cohérents.

3. Oublier les commandes de build : la section la plus utile au quotidien est souvent absente.

4. Copier-coller un template sans l''adapter : un template est un point de départ, pas une solution clé en main.

5. Ne pas versionner le fichier : CLAUDE.md doit être dans votre dépôt Git pour que toute l''équipe en bénéficie.

6. Dupliquer l''information : si votre README contient déjà la stack, utilisez un import @README.md au lieu de copier-coller.

7. Ignorer les garde-fous : les instructions « ne pas faire » sont aussi importantes que les « faire ».

Aller plus loin que CLAUDE.md

Un CLAUDE.md bien écrit, c''est 10 % du potentiel de Claude Code.

Les 90 % restants ? Les team agents, les Skills, les MCP servers, les commandes custom, le memory management avancé. C''est ce qui sépare un dev qui utilise Claude Code d''un vibe coder qui orchestre une équipe d''IA sur ses projets.

8 soirées

en live, compatibles avec un job à temps plein

Éligible CPF

reste à charge possible à 0 € avec ton compte formation

Qualiopi

certification qualité reconnue par l''État

Découvrir la formation Vibe Coding →

Formation plébiscitée par ses apprenants · Cohortes à taille limitée pour garantir un suivi personnalisé

Troubleshooting : quand Claude Code ignore votre CLAUDE.md

Vous avez créé un fichier CLAUDE.md parfait mais Claude Code semble l''ignorer ? Voici les 5 causes les plus fréquentes et comment les diagnostiquer.

1. Le fichier n''est pas au bon endroit

Claude Code cherche CLAUDE.md dans cet ordre :

• ./CLAUDE.md (racine du répertoire de travail)

• ./.claude/CLAUDE.md (sous-dossier .claude)

• ~/.claude/CLAUDE.md (global utilisateur)

Vérifiez avec la commande /memory dans Claude Code : elle liste tous les fichiers mémoire chargés dans la session courante.

2. Le fichier est trop long

Au-delà de ~150 lignes, Claude Code commence à « oublier » les instructions du milieu du fichier. C''est l''effet lost in the middle classique des LLMs. Solution : découpez en .claude/rules/*.md.

3. Les instructions sont trop génériques

« Écris du bon code » n''est pas une instruction actionnable. Claude Code traite les règles vagues comme du bruit. Réécrivez vos règles en mode impératif et spécifique (voir la table plus haut).

4. Il y a des conflits entre fichiers

Si votre ~/.claude/CLAUDE.md global contredit votre ./CLAUDE.md projet, vous créez de l''ambiguïté. Le plus spécifique gagne, mais le conflit peut dégrader les réponses. Nettoyez les contradictions.

5. La session n''a pas rechargé le fichier

CLAUDE.md est lu au démarrage de la session. Si vous éditez le fichier en cours de session, Claude Code ne le reprendra pas automatiquement. Utilisez /memory reload ou redémarrez la session.

Diagnostic rapide : les 3 commandes à connaître

• /memory : voir tous les fichiers mémoire chargés

• /memory reload : recharger les fichiers mémoire

• /init : régénérer un CLAUDE.md propre

Pour aller plus loin sur les commandes Claude Code, consultez notre cheatsheet complète et le guide des Skills et commandes personnalisées.

CLAUDE.md vs .cursorrules vs copilot-instructions.md

Si vous hésitez entre Claude Code et Cursor, vous vous demandez probablement comment se comparent leurs fichiers de configuration respectifs.

L''auto-mémoire est un avantage majeur : Claude Code apprend de vos sessions et enrichit sa connaissance du projet automatiquement. Combiné avec les team agents, vous obtenez un système où chaque spécialiste IA garde son contexte propre — chose impossible avec .cursorrules ou copilot-instructions.

FAQ : questions fréquentes sur CLAUDE.md

CLAUDE.md fonctionne-t-il avec Claude Code dans un IDE ?

Oui. Que vous utilisiez Claude Code dans le terminal natif, dans VS Code, dans Cursor ou via Claude Code Desktop, le fichier CLAUDE.md est lu automatiquement au démarrage de la session. Le comportement est identique partout.

Combien de tokens consomme CLAUDE.md ?

Un fichier CLAUDE.md de 80 lignes consomme environ 500 à 800 tokens, soit une fraction infime de la fenêtre de contexte de Claude (200K tokens). Le retour sur investissement est massif.

Faut-il utiliser /init ou écrire le fichier à la main ?

Les deux approches se complètent. /init génère un bon squelette en analysant votre projet automatiquement. Ensuite, affinez-le manuellement en ajoutant vos conventions spécifiques et vos garde-fous.

CLAUDE.md remplace-t-il le prompting ?

Non. CLAUDE.md fournit le contexte permanent. Vos prompts fournissent les instructions ponctuelles. Les deux sont complémentaires.

Peut-on utiliser CLAUDE.md en équipe ?

Absolument. Le fichier CLAUDE.md versionné dans Git assure que toute l''équipe travaille avec le même contexte. Les préférences individuelles vont dans CLAUDE.local.md (automatiquement gitignoré).

Où trouver des exemples de CLAUDE.md ?

Outre les 3 templates fournis dans ce guide, vous pouvez explorer les repos open-source populaires sur GitHub en cherchant filename:CLAUDE.md. Des projets comme Anthropic lui-même, Vercel ou Supabase ont des CLAUDE.md publics que vous pouvez étudier.

Peut-on avoir un CLAUDE.md pour un monorepo ?

Oui, et c''est même recommandé. Placez un CLAUDE.md global à la racine du monorepo (conventions partagées, structure), puis un CLAUDE.md spécifique dans chaque package (stack locale, commandes). Claude Code chargera les deux en respectant la hiérarchie de spécificité.

Conclusion : CLAUDE.md, votre investissement le plus rentable

Configurer un fichier CLAUDE.md prend 15 minutes. Ces 15 minutes vont vous en faire gagner des dizaines chaque semaine. C''est l''optimisation la plus simple et la plus impactante que vous puissiez faire sur votre workflow de Vibe Coding.

Récapitulons les points essentiels :

• Créez un CLAUDE.md à la racine de chaque projet avec votre stack, vos conventions et vos commandes

• Restez sous 80 lignes et utilisez les imports @path ou .claude/rules/ pour modulariser

• Soyez spécifique : des instructions précises battent toujours des conseils génériques

• Exploitez memory.md pour que Claude Code apprenne automatiquement de vos sessions

• Versionnez-le pour que toute l''équipe en bénéficie

• Faites-le évoluer avec votre projet — ce n''est pas un fichier statique

Lancez /init dans votre prochain projet, affinez le résultat, et vous ne reviendrez jamais en arrière.

Pour approfondir

• Claude Code : le guide complet de l''assistant IA terminal

• Commandes essentielles Claude Code : la cheatsheet du Vibe Coder

• Claude Code Team Agents : orchestrer une équipe d''IA

• Claude Code Skills : créer des commandes personnalisées

• Claude Code Desktop vs Cursor : le comparatif 2026

Sources

• Documentation officielle Claude Code — Manage Claude''s memory

• Blog Anthropic — Using CLAUDE.md files

• Builder.io — How to Write a Good CLAUDE.md File

• HumanLayer — Writing a good CLAUDE.md

• Claude Code Docs — Best Practices