Le système de mémoire CLAUDE.md - Tutoriel

Ce tutoriel vous guide pas à pas pour configurer et exploiter le système de mémoire de Claude Code grâce aux fichiers CLAUDE.md, aux règles modulaires et à l'Auto Memory. Vous apprendrez à structurer la mémoire persistante de votre assistant IA pour qu'il retienne vos conventions, vos préférences et l'architecture de vos projets d'une session à l'autre.

Le système de mémoire CLAUDE.md est le mécanisme natif de Claude Code qui permet de stocker des instructions persistantes injectées automatiquement dans le prompt système à chaque nouvelle conversation. ce système repose sur une hiérarchie de fichiers Markdown lus par Claude Code au démarrage, offrant un contrôle précis sur le comportement de l'agent sans configuration complexe.

les projets utilisant un fichier CLAUDE.md bien structuré réduisent de 40 % le nombre de rappels manuels nécessaires au cours d'une session. Ce tutoriel couvre la création, la structuration et l'optimisation de chaque couche mémoire disponible dans Claude Code v1.0+.

---

Quels sont les prérequis avant de commencer ?

Avant de configurer votre système de mémoire, vérifiez que votre environnement remplit ces conditions :

• Node.js 22 ou supérieur installé
• Claude Code v1.0+ installé et fonctionnel (claude --version)
• Un projet Git initialisé dans votre répertoire de travail
• Un terminal avec accès en écriture au dossier ~/.claude/

claude --version
node --version
git status

Si vous débutez avec Claude Code, le tutoriel d'installation et de premières conversations vous guide à travers la configuration initiale complète.

⏱️ Durée totale estimée : 25-35 minutes pour l'ensemble du tutoriel.

À retenir : vérifiez vos versions avant de commencer - un environnement à jour évite 90 % des problèmes de configuration mémoire.

---

Comment fonctionne la hiérarchie des mémoires dans Claude Code ?

Le système de mémoire de Claude Code repose sur trois niveaux distincts, chacun avec une portée et une priorité spécifiques. Comprenez cette hiérarchie avant de créer vos fichiers.

Le premier niveau est le fichier ~/.claude/CLAUDE.md, dit « mémoire utilisateur ». Il s'applique à tous vos projets et contient vos préférences globales : style de code, langue, conventions de nommage.

Le deuxième niveau est le fichier CLAUDE.md à la racine de votre projet. Il contient les instructions spécifiques au dépôt : stack technique, patterns architecturaux, commandes de build. Ce fichier se versionne avec Git.

Le troisième niveau regroupe les fichiers .claude/rules/*.md du projet. Chaque fichier cible un cas précis grâce à des globs de fichiers. Cette approche modulaire évite un fichier monolithique illisible.

Pour approfondir le fonctionnement interne de cette hiérarchie, consultez l'analyse approfondie du système de mémoire CLAUDE.md qui détaille chaque couche.

En pratique, Claude Code concatène ces fichiers dans l'ordre utilisateur → projet → règles avant de les injecter dans le prompt système, soit environ 200 lignes maximum lues au démarrage.

À retenir : la mémoire suit une hiérarchie en trois niveaux - global, projet, modulaire - avec concaténation automatique au démarrage.

---

Comment créer votre fichier CLAUDE.md utilisateur ? (Étape 1 - ~2 min)

Créez le fichier de mémoire globale avec une structure claire. Ce fichier s'appliquera à chaque projet que vous ouvrez avec Claude Code.

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

Ouvrez le fichier et ajoutez vos préférences globales :

# Préférences globales

- Langue de réponse : français
- Style de code : fonctionnel, typage strict
- Toujours utiliser des imports nommés (pas de default export)
- Commits en anglais, format conventionnel (feat:, fix:, chore:)
- Ne jamais auto-commiter sans confirmation

Ce fichier ne doit pas dépasser 100 lignes. Concentrez-vous sur les règles universelles qui s'appliquent quel que soit le projet.

✅ Vérification : exécutez cat ~/.claude/CLAUDE.md et confirmez que le contenu s'affiche correctement.

⚠️ Si vous voyez No such file or directory, vérifiez que le dossier ~/.claude/ existe avec ls -la ~/.claude/.

À retenir : le fichier ~/.claude/CLAUDE.md contient vos préférences universelles - gardez-le concis, sous 100 lignes.

---

Comment configurer le CLAUDE.md de votre projet ? (Étape 2 - ~5 min)

Créez un fichier CLAUDE.md à la racine de votre dépôt Git. C'est le fichier le plus stratégique : il définit le contexte que Claude Code utilisera pour comprendre votre codebase.

touch CLAUDE.md

Voici comment structurer un fichier projet efficace. Organisez-le en sections distinctes :

# Projet : Mon Application

## Stack technique
- Next.js 15 / React 19 / TypeScript 5.7
- Base de données : PostgreSQL 16 via Prisma 6
- Tests : Vitest + Testing Library

## Architecture
- /app : routes Next.js (App Router)
- /lib : logique métier pure
- /components : composants React réutilisables

## Commandes essentielles
- Build : `npm run build`
- Tests : `npm run test`
- Lint : `npm run lint`

## Conventions
- Composants en PascalCase, hooks en camelCase avec préfixe "use"
- Un composant par fichier
- Tests colocalisés : Button.test.tsx à côté de Button.tsx

Ce fichier se versionne avec Git, ce qui permet à toute l'équipe de partager le même contexte. un CLAUDE.md projet bien structuré réduit de 35 % les erreurs de génération de code liées à des conventions manquantes.

Pour gérer les permissions d'accès aux fichiers sensibles de votre projet, consultez le tutoriel sur les permissions et la sécurité.

✅ Vérification : lancez claude dans votre projet et demandez « Quel est le stack technique du projet ? ». Claude Code doit répondre en citant les technologies listées dans votre CLAUDE.md.

⚠️ Si Claude Code ne lit pas votre fichier, vérifiez qu'il se trouve bien à la racine du dépôt Git (au même niveau que .git/).

À retenir : le CLAUDE.md projet est le fichier le plus impactant - versionnez-le avec Git pour que toute l'équipe en bénéficie.

---

Comment ajouter des règles modulaires avec .claude/rules/ ? (Étape 3 - ~5 min)

Créez le dossier de règles modulaires pour séparer vos instructions par contexte. Chaque fichier .md dans ce dossier peut cibler des types de fichiers spécifiques grâce aux globs.

mkdir -p .claude/rules

Ajoutez une première règle ciblant les fichiers TypeScript :

---
globs: "**/*.ts,**/*.tsx"
---

# Règles TypeScript

- Typage explicite pour les paramètres de fonctions publiques
- Utiliser `satisfies` plutôt que `as` pour les assertions de type
- Interfaces pour les objets, types pour les unions et intersections
- Pas de `any` - utiliser `unknown` si le type est inconnu

Créez ensuite une règle pour les tests :

---
globs: "**/*.test.ts,**/*.test.tsx"
---

# Règles de tests

- Utiliser describe/it (pas test())
- Un fichier de test par composant/module
- Noms de tests en français : "devrait afficher le bouton"
- Mocker les appels API avec msw, jamais de mocks manuels

Concrètement, quand vous ouvrez un fichier .tsx, Claude Code charge automatiquement la règle TypeScript. Quand vous travaillez sur un fichier .test.tsx, les deux règles s'appliquent simultanément.

Cette approche modulaire est complémentaire de la gestion du contexte que vous pouvez configurer pour optimiser la fenêtre de contexte disponible.

En pratique, les équipes de plus de 5 développeurs utilisent en moyenne 4 à 8 fichiers de règles modulaires pour couvrir leurs cas d'usage.

✅ Vérification : exécutez ls .claude/rules/ et confirmez que vos fichiers .md apparaissent. Ouvrez ensuite Claude Code sur un fichier TypeScript et demandez « Quelles règles s'appliquent ici ? ».

À retenir : les règles modulaires dans .claude/rules/ ciblent des fichiers par glob - concrètement, elles permettent des instructions chirurgicales sans surcharger le CLAUDE.md principal.

---

Comment activer et exploiter l'Auto Memory ? (Étape 4 - ~3 min)

L'Auto Memory est un mécanisme automatique par lequel Claude Code enregistre des notes persistantes dans un dossier dédié à chaque projet. Ce dossier se trouve dans ~/.claude/projects//memory/.

Vérifiez que le dossier de mémoire automatique existe pour votre projet :

ls ~/.claude/projects/

Le fichier principal est MEMORY.md, limité à 200 lignes. Claude Code le lit au démarrage de chaque session et y inscrit les patterns qu'il détecte au fil de vos interactions.

Voici comment déclencher une mémorisation explicite. Dites simplement à Claude Code :

"Retiens que dans ce projet, on utilise toujours pnpm et jamais npm"

Claude Code écrira cette instruction dans son fichier MEMORY.md automatiquement. Vous pouvez aussi lui demander d'oublier une information :

"Oublie la règle sur pnpm, on est revenu à npm"

l'Auto Memory stocke en moyenne 15 à 30 entrées par projet actif, couvrant les conventions de code, les chemins de fichiers importants et les décisions architecturales récurrentes.

Pour aller plus loin dans l'optimisation de cette mémoire automatique, le guide d'optimisation du système de mémoire détaille les stratégies avancées de structuration.

✅ Vérification : après avoir demandé à Claude Code de retenir quelque chose, exécutez cat ~/.claude/projects/*/memory/MEMORY.md et confirmez que l'entrée apparaît.

À retenir : l'Auto Memory fonctionne sans configuration - Claude Code y stocke automatiquement les patterns confirmés au fil des sessions.

---

Quelles sont les bonnes pratiques pour structurer votre mémoire ? (Étape 5 - ~5 min)

Appliquez ces principes pour maximiser l'efficacité de votre système de mémoire. Un CLAUDE.md mal structuré peut dégrader les performances de Claude Code au lieu de les améliorer.

Règle 1 : Soyez concis. Claude Code lit la mémoire entière à chaque démarrage. Un fichier de 500 lignes consomme du contexte inutilement. Limitez chaque CLAUDE.md à 150 lignes maximum.

Règle 2 : Utilisez des listes, pas des paragraphes. Les instructions sous forme de bullet points sont 60 % mieux respectées que les paragraphes narratifs, car Claude Code les interprète comme des directives explicites.

Règle 3 : Séparez le « quoi » du « pourquoi ». Écrivez l'instruction d'abord, puis la justification entre parenthèses si nécessaire :

- Utiliser des imports nommés (compatibilité tree-shaking)
- Tests E2E avec Playwright (adopté en janvier 2026, remplace Cypress)

Règle 4 : Mettez à jour régulièrement. Un CLAUDE.md obsolète crée des conflits. Planifiez une revue mensuelle avec la commande /memory ou en éditant directement le fichier.

Pour maîtriser les commandes slash qui facilitent la gestion de la mémoire, consultez le tutoriel sur les commandes slash essentielles.

SFEIR Institute propose une formation Claude Code d'une journée qui inclut des labs pratiques sur la configuration optimale du système de mémoire. Vous y apprendrez à structurer vos fichiers CLAUDE.md pour des projets d'entreprise avec plusieurs équipes.

⚠️ Si Claude Code ignore une règle de votre CLAUDE.md, vérifiez que le fichier ne contient pas de syntaxe Markdown cassée (tableaux mal formatés, listes sans retour à la ligne).

À retenir : un CLAUDE.md efficace est court, structuré en listes et mis à jour régulièrement - la concision l'emporte sur l'exhaustivité.

---

Comment organiser la mémoire automatique avec des fichiers thématiques ? (Étape 6 - ~5 min)

Au-delà du fichier MEMORY.md principal, Claude Code peut créer des fichiers thématiques dans le dossier memory/. Organisez votre mémoire par sujets pour éviter un fichier monolithique.

Demandez à Claude Code de créer des fichiers séparés :

"Crée un fichier memory/debugging.md avec les solutions aux bugs récurrents du projet"

Voici comment une structure thématique peut s'organiser :

~/.claude/projects/<projet>/memory/
├── MEMORY.md          # Index principal (200 lignes max)
├── debugging.md       # Solutions aux problèmes récurrents
├── patterns.md        # Patterns architecturaux du projet
└── api-conventions.md # Conventions spécifiques aux API

Le fichier MEMORY.md sert d'index. Gardez-y uniquement les références vers les fichiers thématiques et les règles les plus critiques. Les fichiers secondaires sont chargés à la demande.

En pratique, les projets de plus de 50 000 lignes de code bénéficient de 3 à 5 fichiers thématiques pour couvrir les différents domaines du codebase.

Cette organisation s'intègre avec le système d'intégration Git pour versionner les décisions architecturales importantes découvertes par Claude Code.

✅ Vérification : exécutez ls ~/.claude/projects/*/memory/ et confirmez que vos fichiers thématiques apparaissent à côté de MEMORY.md.

À retenir : créez des fichiers thématiques dans le dossier memory/ pour garder le MEMORY.md principal sous 200 lignes.

---

Comment déboguer les problèmes de mémoire dans Claude Code ? (Étape 7 - ~3 min)

Quand Claude Code ne respecte pas vos instructions malgré un CLAUDE.md configuré, suivez cette procédure de diagnostic en 4 points.

Point 1 : vérifiez le chargement. Demandez à Claude Code : « Quelles sont tes instructions actuelles ? ». Il doit citer le contenu de votre CLAUDE.md.

Point 2 : vérifiez les conflits. Si vous avez un CLAUDE.md utilisateur ET un CLAUDE.md projet avec des instructions contradictoires, le fichier projet a priorité. Supprimez les doublons.

# Afficher les deux fichiers côte à côte
diff ~/.claude/CLAUDE.md ./CLAUDE.md

Point 3 : vérifiez la taille. Un CLAUDE.md de plus de 200 lignes peut être tronqué. Comptez les lignes :

wc -l CLAUDE.md
wc -l ~/.claude/CLAUDE.md

Point 4 : vérifiez les globs. Pour les règles modulaires, un glob mal formé empêche le chargement. Testez votre glob :

# Lister les fichiers correspondant au glob
ls **/*.test.tsx

Le guide complet du système de mémoire CLAUDE.md couvre les cas de dépannage avancés incluant les conflits multi-utilisateurs.

Pour automatiser ces vérifications dans un pipeline CI/CD, consultez le tutoriel sur le mode headless qui explique comment valider la cohérence de vos fichiers mémoire.

⚠️ Si vous voyez des comportements incohérents entre sessions, vérifiez que vous n'avez pas plusieurs dossiers ~/.claude/projects/ pour le même projet (chemin absolu différent).

À retenir : un diagnostic mémoire suit 4 étapes - chargement, conflits, taille, globs - et résout 95 % des problèmes rencontrés.

---

Comment intégrer le système de mémoire dans un workflow d'équipe ? (Étape 8 - ~5 min)

Versionnez votre CLAUDE.md projet et vos règles modulaires dans Git pour partager le contexte avec toute l'équipe. Concrètement, chaque développeur bénéficie automatiquement des mêmes instructions Claude Code dès qu'il clone le dépôt.

Ajoutez ces fichiers à votre .gitignore pour protéger les préférences personnelles :

# .gitignore - fichiers mémoire personnels
.claude/memory/

Conservez les fichiers partagés dans le dépôt :

git add CLAUDE.md
git add .claude/rules/
git commit -m "chore: add Claude Code memory configuration"

En pratique, les équipes qui versionnent leur CLAUDE.md constatent une réduction de 45 % des incohérences de style entre les contributions des différents développeurs.

Établissez un processus de revue pour les modifications du CLAUDE.md, comme vous le feriez pour n'importe quel fichier de configuration critique. Utilisez des pull requests dédiées.

Pour les équipes utilisant Claude Code en CI, le tutoriel MCP (Model Context Protocol) explique comment étendre les capacités de Claude Code avec des serveurs de contexte externes.

Si vous souhaitez approfondir le développement assisté par IA au-delà de Claude Code, la formation Développeur Augmenté par l'IA de SFEIR Institute couvre sur 2 jours les méthodologies complètes d'intégration d'agents IA dans le cycle de développement. Pour les profils déjà familiers de ces pratiques, la formation avancée d'une journée approfondit les patterns d'orchestration multi-agents et les stratégies de prompt engineering avancées.

✅ Vérification : exécutez git log --oneline -- CLAUDE.md .claude/rules/ et confirmez que vos fichiers mémoire apparaissent dans l'historique de commits.

À retenir : versionnez le CLAUDE.md projet et les règles modulaires dans Git - gardez l'Auto Memory en local via .gitignore.

---

Comment aller plus loin avec le système de mémoire ?

Vous maîtrisez maintenant les fondamentaux du système de mémoire de Claude Code. Voici comment approfondir chaque aspect.

Explorez les commandes slash liées à la mémoire. La commande /memory ouvre directement le fichier MEMORY.md pour édition rapide. Le tutoriel sur les commandes slash détaille toutes les commandes disponibles.

Combinez mémoire et contexte. Le système de mémoire fonctionne en synergie avec la gestion du contexte de Claude Code. Optimisez les deux systèmes ensemble pour maximiser la pertinence des réponses.

En 2026, le système de mémoire continue d'évoluer avec des fonctionnalités comme la mémoire collaborative d'équipe et les templates de CLAUDE.md par type de projet. Surveillez les release notes d'Anthropic pour rester à jour.

À retenir : le système de mémoire CLAUDE.md est la fondation d'une utilisation professionnelle de Claude Code - investir 30 minutes dans sa configuration vous fait gagner des heures chaque semaine.