Le système de mémoire CLAUDE.md

Le fichier CLAUDE.md est le système de mémoire persistante de Claude Code qui permet de configurer le comportement de l'agent entre chaque session. Maîtrisez la hiérarchie des mémoires (du fichier racine aux règles modulaires) pour obtenir des réponses cohérentes, adaptées à votre projet et alignées avec vos conventions d'équipe. Ce guide détaille comment rédiger, structurer et optimiser chaque couche de mémoire.

Le système de mémoire CLAUDE.md est le mécanisme central par lequel Claude Code conserve vos préférences, conventions et instructions d'un échange à l'autre. Ce fichier texte, chargé automatiquement dans le contexte de la conversation, transforme un assistant générique en un partenaire de développement calibré sur votre stack. Le fichier CLAUDE.md est lu à chaque démarrage de session et son contenu influence chaque réponse générée. Notez qu'il est traité comme du contexte, sans garantie de respect strict : pour bloquer une action de manière fiable, utilisez plutôt un hook PreToolUse.

Comment fonctionne le système de mémoire CLAUDE.md dans Claude Code ?

Le fichier CLAUDE.md agit comme une mémoire déclarative persistante. Contrairement à un historique de conversation qui disparaît, ce fichier reste sur votre disque et se charge à chaque nouvelle session. Claude Code lit son contenu avant même votre première instruction.

Concrètement, le mécanisme suit trois étapes :

1. Détection : Claude Code scanne le répertoire courant et ses parents à la recherche de fichiers CLAUDE.md
2. Chargement : le contenu est concaténé dans le contexte de la conversation (et non inséré dans le prompt système lui-même)
3. Application : chaque réponse tient compte des directives trouvées, traitées comme du contexte sans garantie de respect strict

Le fichier CLAUDE.md supporte le Markdown standard. Vous pouvez y placer des règles, des exemples de code, des chemins de fichiers ou des préférences de style. Gardez votre CLAUDE.md concis. Un fichier trop long consomme du contexte inutilement.

Pour une introduction complète à l'outil, consultez la page d'accueil Claude Code qui présente l'ensemble des fonctionnalités disponibles.

À retenir : CLAUDE.md est un fichier texte lu automatiquement à chaque session, qui transforme vos instructions en comportement persistant de l'agent.

Pourquoi le fichier CLAUDE.md est-il crucial pour votre productivité ?

Sans CLAUDE.md, vous répétez les mêmes consignes à chaque session. les développeurs qui configurent un CLAUDE.md structuré réduisent significativement le nombre de corrections manuelles sur les réponses générées.

Voici les gains observés en pratique :

Ouvrez votre terminal et vérifiez si un fichier CLAUDE.md existe déjà à la racine de votre projet :

$ ls -la CLAUDE.md
$ cat CLAUDE.md

En pratique, un CLAUDE.md bien rédigé élimine la grande majorité des rappels que vous feriez manuellement, ce qui représente un gain de temps appréciable sur chaque session de travail avec l'agent. Pour découvrir comment tirer parti de ce gain dès vos premiers échanges, explorez le guide sur vos premières conversations avec Claude Code.

À retenir : un CLAUDE.md structuré réduit significativement les corrections et élimine le temps de re-contextualisation à chaque session.

Quelle est la hiérarchie des mémoires dans Claude Code ?

Claude Code ne se limite pas à un seul fichier. Il combine plusieurs niveaux de mémoire, chacun avec une portée spécifique. Ces fichiers sont concaténés dans le contexte selon leur ordre de chargement (du plus large au plus spécifique), et non hiérarchisés par un mécanisme de surcharge.

Les quatre niveaux de mémoire

Configurez d'abord le niveau utilisateur avec vos préférences globales :

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

Le niveau utilisateur contient vos conventions personnelles : langue préférée, style de commit, outils favoris. Le niveau projet contient les règles spécifiques : stack technique, structure de dossiers, patterns architecturaux.

Gérer les contradictions

Les fichiers CLAUDE.md et .claude/rules/ sont tous concaténés dans le contexte, sans mécanisme de surcharge (override). Les règles sans frontmatter paths se chargent avec la même priorité que .claude/CLAUDE.md. En cas de contradiction (par exemple un .claude/rules/testing.md qui impose Jest face à un CLAUDE.md racine qui mentionne Vitest), aucun niveau n'écrase formellement l'autre : les deux instructions sont simplement présentes dans le contexte. Évitez donc les instructions contradictoires entre vos fichiers.

Pour comprendre comment ces fichiers interagissent avec la gestion du contexte global, consultez le guide de gestion du contexte qui approfondit les mécanismes de chargement.

À retenir : les niveaux de mémoire sont concaténés dans le contexte du plus large (utilisateur) au plus spécifique (règles modulaires), sans surcharge formelle. Évitez les instructions contradictoires.

Comment rédiger un CLAUDE.md efficace en 5 étapes ?

Un CLAUDE.md mal structuré est pire que pas de CLAUDE.md du tout. Suivez ces cinq étapes pour créer un fichier qui produit des résultats immédiats. Pour un tutoriel pas-à-pas détaillé, reportez-vous au tutoriel dédié au système de mémoire CLAUDE.md.

Étape 1 : Déclarer la stack technique

Listez explicitement chaque technologie avec sa version :

# Stack technique
- Runtime : Node.js 22.x
- Framework : Next.js 15.1 (App Router)
- Langage : TypeScript 5.7 strict
- Base de données : PostgreSQL 16
- ORM : Prisma 6.2

Étape 2 : Définir les conventions de code

Précisez vos règles de nommage, de formatage et d'architecture :

# Conventions
- Nommage : camelCase pour les variables, PascalCase pour les composants
- Imports : utiliser des alias @ (ex: @/lib/utils)
- Pas de `any` en TypeScript - utiliser `unknown` si nécessaire
- Fonctions < 30 lignes

Étape 3 : Spécifier les commandes courantes

Documentez les commandes que Claude Code doit utiliser :

# Commandes
- Tests : `pnpm test`
- Lint : `pnpm lint --fix`
- Build : `pnpm build`
- Dev : `pnpm dev --port 3001`

Étape 4 : Ajouter les patterns interdits

Indiquez ce que Claude Code ne doit jamais faire. C'est souvent la section la plus utile :

# Interdictions
- NE JAMAIS utiliser `console.log` en production - utiliser le logger
- NE JAMAIS modifier les fichiers de migration existants
- NE JAMAIS commit sans lancer les tests
- NE JAMAIS utiliser `any` - préférer `unknown` ou un type spécifique

Étape 5 : Garder le fichier concis

En pratique, un CLAUDE.md de 80 à 150 lignes couvre la grande majorité des besoins. Un fichier trop long consomme du contexte inutilement. Déplacez les règles spécifiques dans des fichiers modulaires (voir section suivante). Le guide d'optimisation du système de mémoire détaille les techniques de compression.

À retenir : un CLAUDE.md efficace tient en 5 blocs (stack, conventions, commandes, interdictions) et reste sous 150 lignes.

Comment utiliser les règles modulaires dans .claude/rules/ ?

Les règles modulaires permettent de découper votre configuration en fichiers thématiques. Chaque fichier .md placé dans .claude/rules/ est chargé automatiquement, ce qui résout le problème de limite de taille du CLAUDE.md principal.

Structure recommandée

.claude/
 rules/
 testing.md # Règles de tests
 api-design.md # Conventions d'API
 security.md # Règles de sécurité
 git-workflow.md # Workflow Git
 code-style.md # Style de code

Créez votre premier fichier de règle :

$ mkdir -p .claude/rules
$ touch .claude/rules/testing.md

Règles conditionnelles

Depuis Claude Code, vous pouvez ajouter un en-tête frontmatter pour conditionner l'activation d'une règle :

---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
# Règles de test
- Utiliser `describe` / `it` (pas `test`)
- Mocker les appels réseau avec MSW
- Viser 80 % de couverture minimum

Cette règle ne se déclenche que lorsque Claude Code travaille sur des fichiers de test. En pratique, les règles conditionnelles réduisent sensiblement le bruit dans le contexte car seules les directives pertinentes sont injectées.

Pour approfondir les interactions entre règles et permissions de sécurité, notamment les restrictions d'exécution de commandes, consultez le guide dédié. Vous pouvez également parcourir les erreurs courantes liées au système de mémoire pour éviter les pièges classiques de configuration.

À retenir : les règles modulaires dans .claude/rules/ découpent la configuration par thème et supportent l'activation conditionnelle par pattern de fichier.

Comment fonctionne l'Auto Memory avec MEMORY.md ?

L'Auto Memory est un mécanisme par lequel Claude Code écrit lui-même ses observations dans un fichier MEMORY.md. Ce fichier se trouve dans ~/.claude/projects//memory/MEMORY.md (dans le répertoire utilisateur, pas dans le projet), où est dérivé du dépôt git, et persiste entre les sessions.

Différences entre CLAUDE.md et MEMORY.md

Concrètement, l'Auto Memory enregistre :

• Les erreurs récurrentes et leurs solutions
• Les patterns architecturaux détectés dans votre code
• Vos préférences implicites (style de commit, noms de branches)
• Les chemins de fichiers importants découverts pendant le travail

Déclencher l'écriture mémoire

Vous pouvez demander explicitement à Claude Code de mémoriser une information :

$ claude
> Retiens que dans ce projet, on utilise toujours bun au lieu de npm

Claude Code écrira cette préférence dans MEMORY.md. Lors de la session suivante, il utilisera automatiquement bun sans que vous ayez à le rappeler.

Pour interagir efficacement avec l'agent via les commandes intégrées, explorez le guide des commandes slash essentielles de Claude Code. Vous y trouverez les raccourcis pour gérer la mémoire directement depuis le terminal.

Bonnes pratiques pour l'Auto Memory

1. Vérifiez régulièrement le contenu de MEMORY.md, supprimez les observations obsolètes
2. Évitez les doublons avec CLAUDE.md : si une règle est stable, déplacez-la dans CLAUDE.md
3. Limitez la taille de MEMORY.md : au-delà de 200 lignes environ, le contenu peut être tronqué
4. Organisez par thème en créant des fichiers séparés (debugging.md, patterns.md)

Le guide d'astuces pour le système de mémoire propose 12 techniques avancées pour tirer le maximum de l'Auto Memory.

À retenir : MEMORY.md est la mémoire auto-alimentée par Claude Code, vérifiez-la régulièrement et déplacez les observations stables vers CLAUDE.md.

Quels sont les pièges courants à éviter avec CLAUDE.md ?

la majorité des problèmes de comportement de l'agent proviennent de trois erreurs de configuration du système de mémoire.

Piège 1 : Le fichier trop long

Un CLAUDE.md de 500 lignes noie les instructions critiques. Les fichiers CLAUDE.md sont chargés en entier quelle que soit leur longueur, mais plus le fichier est long, plus il consomme de contexte et plus les directives clés risquent de se diluer parmi les détails. Divisez le contenu en règles modulaires et gardez le fichier concis. (La limite de 200 lignes ou 25 Ko ne concerne que le fichier MEMORY.md de l'Auto Memory, pas CLAUDE.md.)

Piège 2 : Les instructions contradictoires

Écrire "utilise des arrow functions" dans CLAUDE.md et "utilise des function declarations" dans .claude/rules/code-style.md crée un conflit. Vérifiez la cohérence entre tous les niveaux de mémoire :

$ cat CLAUDE.md
$ ls .claude/rules/
$ cat .claude/rules/*.md

Piège 3 : L'absence de contexte projet

Un CLAUDE.md qui contient uniquement des préférences personnelles sans décrire le projet force Claude Code à déduire la stack. En pratique, une partie du temps de la première session est perdue en questions de clarification si le projet n'est pas décrit.

Pour aller plus loin dans la compréhension du coding agentique et voir comment la mémoire s'inscrit dans cette approche, lisez l'article dédié. Vous trouverez également des solutions détaillées dans la FAQ du système de mémoire CLAUDE.md.

À retenir : les trois pièges majeurs sont le fichier trop long, les contradictions entre niveaux et l'absence de description du projet.

Comment intégrer CLAUDE.md dans votre workflow d'équipe ?

Le fichier CLAUDE.md à la racine du projet se commit dans Git. Il devient une documentation vivante des conventions d'équipe. Chaque développeur bénéficie des mêmes directives dès qu'il clone le dépôt.

Workflow recommandé

1. Créez un CLAUDE.md initial avec les conventions d'équipe
2. Committez le fichier dans le dépôt partagé
3. Ajoutez un CLAUDE.local.md au .gitignore pour vos préférences personnelles locales (le fichier d'auto-mémoire vit déjà dans ~/.claude/projects/, hors du dépôt, et n'a pas besoin d'être gitignoré)
4. Révisez le CLAUDE.md lors des rétrospectives d'équipe

$ git add CLAUDE.md .claude/rules/
$ git commit -m "feat: add Claude Code memory configuration"
$ echo "CLAUDE.local.md" >> .gitignore

Séparer le partagé du personnel

Pour découvrir comment configurer votre environnement avant de personnaliser la mémoire, suivez le guide d'installation et premier lancement de Claude Code. L'analyse approfondie du système de mémoire couvre les cas d'usage avancés pour les équipes de plus de 10 développeurs.

Si vous souhaitez maîtriser ces mécanismes en conditions réelles, la formation Claude Code de SFEIR Institute (1 jour) inclut des labs pratiques où vous configurez un CLAUDE.md complet, testez les règles modulaires et exploitez l'Auto Memory sur un projet concret. Pour ceux qui veulent aller plus loin, la formation Développeur Augmenté par l'IA (2 jours) couvre l'intégration de Claude Code dans un workflow de développement professionnel complet.

Les profils expérimentés peuvent se tourner vers la formation Développeur Augmenté par l'IA – Avancé (1 jour) pour explorer les patterns de configuration multi-projets et l'optimisation avancée du contexte.

À retenir : committez CLAUDE.md et .claude/rules/ dans Git, mais gardez les fichiers MEMORY.md personnels hors du dépôt.

Quels résultats concrets attendre d'un système de mémoire bien configuré ?

Un système de mémoire optimisé produit des résultats visibles dès la première semaine. Les équipes qui structurent leur CLAUDE.md observent ces gains :

• Une cohérence des conventions de code nettement plus élevée et plus stable
• Une baisse marquée du nombre de corrections manuelles par session
• Un temps de re-contextualisation quasi nul en début de session
• Une montée en autonomie plus rapide des nouveaux développeurs sur le projet

Le système de mémoire reste l'un des leviers de productivité les plus sous-exploités de Claude Code. Trop peu d'utilisateurs configurent un CLAUDE.md structuré, alors que le retour sur investissement est immédiat.

Lancez votre configuration dès maintenant en créant un fichier CLAUDE.md minimal :

$ printf '# Mon Projet\n- Stack: Node.js 22, TypeScript 5.7\n- Tests: pnpm test\n- NE JAMAIS utiliser any\n' > CLAUDE.md
$ claude

En 30 secondes, vous disposez d'un agent calibré sur votre projet. Enrichissez progressivement le fichier en ajoutant des règles au fil de vos sessions.

À retenir : un CLAUDE.md minimal prend 30 secondes à créer et améliore immédiatement la pertinence de chaque réponse de Claude Code.