CLAUDE.md : Configurer la Mémoire Persistante de Claude Code

Mis à jour le 3 mars 2026

CLAUDE.md est LE fichier qui change tout dans ton utilisation de Claude Code. C'est ta mémoire permanente — les instructions que Claude Code lit à chaque session. Sans lui, tu répètes les mêmes consignes à chaque fois. Avec lui, Claude Code connaît ton projet, tes préférences, et tes conventions dès le départ.

Imagine devoir ré-expliquer à un collaborateur ses tâches chaque matin. C'est ce que tu fais sans CLAUDE.md. Avec ce fichier, tout est posé une fois pour toutes. Claude Code sait quoi faire, comment le faire, et ce qu'il ne doit jamais toucher. Ce guide t'explique tout : où le placer, quoi y mettre, comment l'organiser, et comment le combiner avec l'auto-memory pour un setup professionnel.

C'est quoi CLAUDE.md

CLAUDE.md est un fichier Markdown que Claude Code lit automatiquement à chaque démarrage de session. Il contient tes instructions permanentes : stack technique, conventions de code, préférences, règles du projet. C'est la mémoire de ton assistant IA.

Pense à CLAUDE.md comme un brief que tu rédiges une seule fois. Un document qui dit à Claude Code : "Voilà le projet, voilà comment je travaille, voilà ce que tu dois respecter." Chaque fois que tu lances une session, Claude Code commence par lire ce fichier. Pas besoin de rappeler ta stack, tes conventions de nommage, ou tes règles. Tout est là.

Le fichier est écrit en Markdown — le même format que les fichiers README sur GitHub. Des titres avec #, des listes avec -, du texte en gras avec **. Si tu sais écrire du texte structuré, tu sais écrire un CLAUDE.md. Aucune syntaxe complexe, aucun langage de programmation.

Et c'est toi qui le rédiges. Pas Claude Code. Pas un outil tiers. Toi. C'est ce qui le distingue de l'auto-memory (on en parle plus bas) : CLAUDE.md, c'est TA voix, TES décisions, TES contraintes. Claude Code les respecte à chaque interaction.

Si tu débutes avec Claude Code, le fichier CLAUDE.md est la première chose à mettre en place. Avant même d'écrire ta première instruction.

Où placer ton fichier CLAUDE.md

Claude Code ne cherche pas ton fichier CLAUDE.md à un seul endroit. Il a une hiérarchie de recherche — plusieurs niveaux, du plus global au plus spécifique. Chaque niveau a son rôle.

Niveau projet : ./CLAUDE.md

C'est l'emplacement le plus courant. Tu places un fichier CLAUDE.md à la racine de ton projet. Il contient les instructions spécifiques à CE projet : la stack, les conventions, les commandes de build, les règles métier. Tu peux aussi le placer dans ./.claude/CLAUDE.md — même effet. Ce fichier est versionné avec git, donc partagé avec toute l'équipe.

Niveau utilisateur : ~/.claude/CLAUDE.md

Ce fichier s'applique à TOUS tes projets. C'est l'endroit pour tes préférences personnelles qui ne changent jamais d'un projet à l'autre : ta langue préférée, ton style de communication, tes conventions globales. Par exemple : "Réponds toujours en français", "Utilise le tutoiement", "Indentation 2 espaces partout".

Niveau local : ./CLAUDE.local.md

Ce fichier est automatiquement ajouté au .gitignore — il ne sera jamais partagé avec l'équipe. C'est l'endroit pour tes overrides personnels sur un projet. Par exemple, si le projet utilise des conventions que tu veux adapter pour toi, ou si tu as des chemins spécifiques à ta machine.

Répertoires parents

Claude Code remonte l'arborescence de dossiers. Si ton projet est dans ~/projets/monapp/, Claude Code cherchera un CLAUDE.md dans monapp/, puis dans projets/, puis dans ~/. Tous les fichiers trouvés sont chargés et combinés.

Niveau managed (organisations)

Pour les entreprises qui utilisent Claude Code en équipe. Les administrateurs peuvent définir des règles au niveau de l'organisation. Ce niveau a la priorité la plus haute — il ne peut pas être overridé par les fichiers projet ou utilisateur. C'est le garde-fou ultime.

En pratique, la plupart des vibecoders utilisent deux niveaux : un CLAUDE.md utilisateur pour les préférences globales, et un CLAUDE.md projet pour chaque projet. C'est suffisant pour 90 % des cas.

Que mettre dans ton CLAUDE.md

Un bon CLAUDE.md est court, précis et structuré. Pas un roman. Pas un manifeste. Un brief opérationnel que Claude Code peut scanner en quelques secondes et appliquer immédiatement.

La description du projet

Commence par expliquer ce que fait le projet en 2-3 phrases. Claude Code utilise cette information pour contextualiser toutes ses réponses. Exemple :

# Mon Projet
Application de gestion de devis pour artisans.
Frontend Next.js, backend API Routes, base Supabase.
Déployé sur Vercel.

La stack technique

Liste les technologies utilisées. Sois explicite — "React" ne suffit pas. Précise la version, le framework, les librairies clés :

## Stack
- Framework: Next.js 15 (App Router)
- Langage: TypeScript strict
- Styling: Tailwind CSS
- UI: shadcn/ui
- Base de données: Supabase (PostgreSQL)
- Auth: Supabase Auth

Les conventions de code

C'est ici que tu définis comment le code doit être écrit. Plus tu es précis, plus Claude Code sera cohérent :

## Conventions
- Indentation: 2 espaces
- Nommage: camelCase (variables), PascalCase (composants)
- Imports: groupés par type (externes, internes, styles)
- Pas de any en TypeScript
- Commentaires: seulement quand le code ne s'explique pas lui-même

Les commandes de build et de test

Claude Code a souvent besoin de lancer des commandes. Donne-lui les bonnes :

## Commandes
- Dev: npm run dev
- Build: npm run build
- Tests: npm run test
- Lint: npm run lint

Les règles et interdictions

C'est souvent la partie la plus utile. Les règles que Claude Code doit respecter sans exception :

## Règles
- Ne jamais modifier les fichiers dans /config
- Toujours utiliser shadcn/ui avant de créer un composant custom
- Ne jamais commit de fichiers .env
- Toujours ajouter un error handling explicite (pas de catch vide)
- Répondre en français

Bonnes pratiques de rédaction

• Reste sous 200 lignes. Claude Code charge les 200 premières lignes automatiquement. Au-delà, le contenu est disponible mais pas priorisé.
• Utilise des headers et des bullets. Le Markdown structuré est plus facile à parser pour Claude Code qu'un mur de texte.
• Sois spécifique. "Indentation 2 espaces" est utile. "Formate bien le code" ne l'est pas.
• Évite les redondances. Ne répète pas ce qui est déjà dans tes rules (section suivante).

Si tu veux aller plus loin sur le prompting efficace pour tes projets, les mêmes principes de clarté s'appliquent à ton CLAUDE.md.

Les Rules : organiser par thèmes

Quand ton CLAUDE.md commence à grossir, il est temps de découper. Le répertoire .claude/rules/ est fait pour ça. Chaque fichier dans ce dossier est une règle thématique que Claude Code charge automatiquement.

Un fichier par thème

Crée un fichier Markdown par domaine. Par exemple :

• .claude/rules/testing.md — Conventions de tests, frameworks, couverture attendue
• .claude/rules/security.md — Règles de sécurité, validation des entrées, gestion des secrets
• .claude/rules/api-design.md — Conventions d'API, formats de réponse, gestion d'erreurs
• .claude/rules/styling.md — Conventions CSS, système de design, responsive

Chaque fichier est chargé automatiquement à chaque session. Pas besoin de les importer ou de les référencer dans le CLAUDE.md principal.

Des règles ciblées avec le frontmatter paths

Tu peux restreindre une règle à certains fichiers. Le frontmatter (l'en-tête du fichier Markdown entre ---) accepte un champ paths qui filtre les fichiers concernés :

---
paths:
  - src/api/**
  - src/routes/**
---

# Règles API
- Toujours valider les entrées avec Zod
- Retourner des erreurs HTTP standardisées
- Logger chaque requête avec le timestamp

Cette règle ne sera chargée que quand Claude Code travaille sur des fichiers dans src/api/ ou src/routes/. Les autres fichiers du projet ne sont pas concernés. C'est puissant pour garder le contexte pertinent et éviter de surcharger Claude Code avec des règles qui ne s'appliquent pas.

Rules utilisateur globales

Tu peux aussi créer des rules au niveau utilisateur dans ~/.claude/rules/. Elles s'appliquent à tous tes projets. C'est l'endroit idéal pour tes conventions personnelles qui ne changent jamais : ton style de commit, ta langue, tes patterns préférés.

Les rules sont un excellent complément aux skills et commandes personnalisées — les rules définissent le cadre, les skills et commandes fournissent les capacités.

L'Auto-Memory : quand Claude Code apprend seul

En plus de ton CLAUDE.md (que tu rédiges), Claude Code possède un système d'auto-memory — une mémoire qu'il construit lui-même au fil des sessions. C'est son carnet de notes personnel.

Où se trouve l'auto-memory

Les fichiers de mémoire sont stockés dans ~/.claude/projects/<project-hash>/memory/. Le fichier principal est MEMORY.md, qui sert d'index. Les détails sont répartis dans des fichiers thématiques : debugging.md, patterns.md, commands.md, etc.

Ce que Claude Code mémorise

• Les commandes de build et de test — S'il découvre que npm run dev lance le serveur, il le note pour les prochaines sessions.
• Les patterns de débogage — Si un type d'erreur revient souvent avec une solution spécifique, il l'enregistre.
• Les conventions du projet — En observant le code existant, il déduit les patterns et les note pour rester cohérent.
• Les préférences implicites — Si tu corriges systématiquement un certain style, il comprend et s'adapte.

Comment ça fonctionne

Les 200 premières lignes du fichier MEMORY.md sont chargées automatiquement à chaque session, exactement comme pour le CLAUDE.md. Le reste est disponible à la demande. Tu peux gérer la mémoire avec la commande /memory directement dans Claude Code : voir ce qui a été mémorisé, supprimer des entrées, ajouter manuellement des notes.

Pour un deep dive sur ce système, consulte le guide complet sur l'auto-memory de Claude Code.

CLAUDE.md vs Auto-Memory : comprendre la différence

Les deux systèmes coexistent et se complètent. Mais ils ont des rôles très différents.

CLAUDE.md, c'est TOI qui décides. Tu écris les instructions, tu définis le cadre, tu poses les règles. C'est prescriptif — Claude Code DOIT suivre ce qui est écrit. C'est ta voix de donneur d'ordres.

L'auto-memory, c'est Claude Code qui apprend. Il observe, il déduit, il note. C'est descriptif — il enregistre ce qu'il a compris du projet et de tes habitudes. C'est son carnet d'apprentissage.

En pratique, les deux fonctionnent en tandem. Tu poses le cadre avec CLAUDE.md. Claude Code l'enrichit avec ses observations via l'auto-memory. Au fil des sessions, ton assistant devient de plus en plus efficace — il connaît tes règles ET il a appris les subtilités de ton projet.

Le CLAUDE.md est ton contrat. L'auto-memory est l'expérience accumulée. Les deux ensemble, c'est un assistant qui ne te fait jamais répéter.

Exemple complet d'un CLAUDE.md projet

Voici un exemple réaliste et complet que tu peux adapter à tes projets. Il fait environ 50 lignes — court, dense, actionnable :

# MonApp - Gestion de devis pour artisans

Application SaaS permettant aux artisans de créer, envoyer
et suivre leurs devis. Cible : artisans indépendants, TPE.

## Stack
- Framework: Next.js 15 (App Router)
- Langage: TypeScript (strict mode)
- Styling: Tailwind CSS
- UI Components: shadcn/ui
- Base de données: Supabase (PostgreSQL + Auth)
- Déploiement: Vercel
- Tests: Vitest + Testing Library

## Conventions
- Indentation: 2 espaces
- Nommage: camelCase (vars), PascalCase (components)
- Fichiers composants: PascalCase.tsx
- Imports: externes → internes → styles
- Un composant par fichier
- Types dans un dossier /types séparé

## Commandes
- npm run dev → serveur de développement
- npm run build → build de production
- npm run test → lancer les tests
- npm run lint → vérifier le code

## Règles
- Toujours utiliser shadcn/ui avant un composant custom
- Jamais de "any" en TypeScript
- Error handling explicite, pas de catch vide
- Validation des entrées avec Zod
- Ne pas modifier /supabase/migrations sans demander
- Répondre en français, tutoiement
- Commits: type(scope): description

Ce fichier donne à Claude Code tout ce dont il a besoin pour travailler sur ton projet de manière cohérente. Pas de surprise, pas de malentendu, pas de répétition.

Si tu veux aussi automatiser des tâches autour de ton projet, les hooks de Claude Code te permettent de déclencher des actions automatiques à chaque modification de fichier, chaque commit, ou chaque démarrage de session.

Et pour les entrepreneurs qui veulent intégrer Claude Code dans leur activité au quotidien, le guide Claude Code pour entrepreneurs couvre les cas d'usage business concrets.

Meydeey — Architecte IA & Automatisation

+110 entrepreneurs formés au Vibe Coding et à l'automatisation IA avec N8N. Fondateur du Labo IA.