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

Le fichier CLAUDE.md constitue la mémoire persistante de Claude Code, chargé automatiquement dans le contexte de la conversation à chaque session. Maîtriser sa hiérarchie (projet, utilisateur, auto-mémoire) et ses règles modulaires vous permet de configurer un agent de développement cohérent et productif d'une session à l'autre.

CLAUDE.md est un fichier Markdown de configuration mémoire que Claude Code charge automatiquement au démarrage de chaque session pour personnaliser son comportement, ses conventions et ses instructions persistantes. ce mécanisme constitue le principal levier de personnalisation de l'agent. la plupart des utilisateurs avancés de Claude Code exploitent au moins un fichier CLAUDE.md dans leurs projets.

Qu'est-ce que CLAUDE.md et pourquoi ce fichier est-il essentiel ?

CLAUDE.md est un fichier Markdown placé à la racine d'un projet ou dans le répertoire utilisateur ~/.claude/. Claude Code le détecte et l'injecte dans le contexte de la conversation (sous forme de message utilisateur ajouté après le prompt système) avant toute interaction. Ce mécanisme transforme l'agent en un assistant contextualisé.

Sans CLAUDE.md, chaque nouvelle session repart de zéro. Vous perdez les conventions d'équipe, les chemins de fichiers critiques et les préférences de workflow. Avec un CLAUDE.md bien rédigé, Claude Code applique vos règles dès la première commande.

En pratique, un CLAUDE.md de 80 lignes réduit significativement le nombre de corrections manuelles sur un projet TypeScript de 50 000 lignes. Le fichier agit comme un contrat entre vous et l'agent, garantissant la cohérence du code produit.

Pour comprendre comment Claude Code fonctionne en tant qu'agent autonome, consultez l'article Qu'est-ce que le coding agentique ? qui pose les bases conceptuelles.

À retenir : CLAUDE.md est le fichier de configuration mémoire qui persiste vos instructions entre les sessions Claude Code.

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

Claude Code implémente une hiérarchie à trois niveaux de fichiers mémoire. Chaque niveau a une portée et une priorité différentes. Comprenez cette architecture pour structurer vos instructions au bon endroit.

Niveau 1 : CLAUDE.md projet (racine du dépôt)

Ce fichier vit à la racine de votre repository Git. Il est partagé avec toute l'équipe via le contrôle de version. Placez ici les conventions de code, l'architecture du projet et les commandes de build.

# CLAUDE.md (racine projet)
- Framework : Next.js 15 avec App Router
- Tests : Vitest, lancer avec `npm run test`
- Style : Prettier + ESLint, tabs de 2 espaces
- Ne jamais modifier les fichiers dans /generated/

Niveau 2 : CLAUDE.md utilisateur (~/.claude/CLAUDE.md)

Ce fichier est propre à votre machine. Il n'est pas versionné. Configurez ici vos préférences personnelles : langue de réponse, style de commit, outils préférés.

# ~/.claude/CLAUDE.md
- Répondre en français
- Utiliser bun au lieu de npm
- Toujours proposer des tests unitaires

Niveau 3 : Auto Memory (~/.claude/projects/.../memory/)

Claude Code crée et maintient automatiquement ce répertoire. Il y stocke les patterns découverts au fil des sessions. Ce niveau est détaillé dans une section dédiée plus bas.

Pour une vue complète sur la gestion du contexte et son impact sur la mémoire, explorez l'analyse approfondie de la gestion du contexte.

Tous les fichiers mémoire sont concaténés dans le contexte. En cas de conflit, le contenu chargé en dernier (l'auto-mémoire) peut prendre le dessus, mais Claude Code évite en général d'écrire dans l'auto-mémoire des entrées qui contredisent un CLAUDE.md existant.

À retenir : trois niveaux de mémoire coexistent (projet, utilisateur et auto-mémoire). Tous sont concaténés dans le contexte et, en cas de conflit, le contenu chargé en dernier peut prévaloir.

Comment rédiger un CLAUDE.md efficace ?

Un CLAUDE.md performant suit des principes précis. les fichiers concis obtiennent un meilleur taux d'application des règles. Gardez votre CLAUDE.md concis : un fichier trop long consomme du contexte inutilement.

Structurez par sections thématiques

Organisez votre fichier en blocs clairs avec des titres Markdown. Claude Code parcourt le fichier séquentiellement et attribue plus de poids aux premières lignes.

# Architecture
- Monorepo pnpm avec 3 packages : api, web, shared
- Base de données : PostgreSQL 16 via Prisma 5.x

# Conventions
- Noms de composants en PascalCase
- Hooks personnalisés préfixés par use
- Pas de `any` en TypeScript

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

Soyez directif, pas descriptif

Écrivez des instructions impératives. Remplacez « Le projet utilise TypeScript » par « Utilisez TypeScript strict pour tout nouveau fichier ». Claude Code traite les impératifs comme des règles, les descriptions comme du contexte optionnel.

Concrètement, un CLAUDE.md rédigé en règles impératives produit un code conforme bien plus souvent. Le même contenu rédigé en style descriptif est nettement moins bien respecté.

Précisez les interdictions

Les règles négatives sont aussi puissantes que les positives. Listez explicitement ce que Claude Code ne doit pas faire.

# Interdictions
- Ne JAMAIS modifier les fichiers dans /migrations/
- Ne pas utiliser moment.js (utiliser date-fns)
- Ne pas créer de fichiers.env avec des valeurs réelles

Pour optimiser davantage votre fichier, le guide d'optimisation du système de mémoire CLAUDE.md fournit des techniques avancées de structuration.

À retenir : un CLAUDE.md court, impératif et structuré par sections maximise le taux d'application des règles.

Quels sont les avantages des règles modulaires.claude/rules/ ?

Le répertoire .claude/rules/ permet de découper vos instructions en fichiers thématiques. Chaque fichier .md dans ce dossier est chargé comme un CLAUDE.md additionnel. Cette approche résout le problème de CLAUDE.md qui devient trop long.

Architecture du répertoire

.claude/
├── rules/
│ ├── testing.md # Règles de tests
│ ├── api-conventions.md # Conventions API REST
│ ├── security.md # Règles de sécurité
│ └── git-workflow.md # Workflow Git
├── CLAUDE.md # CLAUDE.md projet (alternatif à ./CLAUDE.md)
└── projects/
 └── <hash>/
 └── memory/
 └── MEMORY.md # Auto-mémoire

Créez un fichier par domaine. En pratique, un projet avec 5 fichiers de règles de 30 lignes chacun obtient un meilleur taux d'application qu'un CLAUDE.md unique de 150 lignes, car chaque fichier reste court et ciblé.

Chargement conditionnel

Depuis Claude Code, les fichiers dans .claude/rules/ supportent le frontmatter YAML pour un chargement conditionnel :

---
paths: ["**/*.test.ts"]
---
# Règles de test
- Utiliser describe/it, pas test()
- Mocker les dépendances externes avec vi.mock
- Chaque test doit avoir un seul assert

Ce fichier ne se charge que lorsque Claude Code travaille sur des fichiers *.test.ts. Vous réduisez ainsi le bruit dans le contexte de la conversation et gagnez des tokens pour le contexte utile.

Pour comprendre comment ces règles interagissent avec le workflow Git, consultez les bonnes pratiques d'intégration Git.

À retenir : les règles modulaires dans .claude/rules/ offrent un meilleur taux d'application et une maintenance simplifiée par rapport à un fichier monolithique.

Comment fonctionne l'Auto Memory avec MEMORY.md ?

L'auto-mémoire est un mécanisme par lequel Claude Code crée et met à jour automatiquement des fichiers dans ~/.claude/projects//memory/. Le fichier principal est MEMORY.md, chargé dans le contexte de la conversation à chaque session.

Mécanisme d'écriture

Claude Code écrit dans MEMORY.md lorsqu'il détecte un pattern récurrent ou une correction que vous appliquez plusieurs fois. Le processus suit ces étapes :

1. Vous corrigez un comportement de Claude Code
2. L'agent identifie une règle implicite
3. Il vérifie si MEMORY.md contient déjà cette information
4. Si non, il ajoute une entrée concise

# MEMORY.md (généré automatiquement)
- Le projet utilise bun, pas npm
- Les tests e2e sont dans /tests/e2e/ et utilisent Playwright
- Toujours exécuter `bun run typecheck` avant de commiter

Limite de taille

MEMORY.md est chargé dans le contexte. Au-delà de 200 lignes environ, le contenu peut être tronqué. Vérifiez régulièrement la taille de votre fichier avec :

wc -l ~/.claude/projects/*/memory/MEMORY.md

Un MEMORY.md de 200 lignes ne consomme qu'une fraction négligeable de la fenêtre de contexte. La documentation officielle charge au maximum les 200 premières lignes ou les 25 Ko du fichier, selon ce qui survient en premier.

Fichiers thématiques complémentaires

En plus de MEMORY.md, vous pouvez créer des fichiers comme debugging.md ou patterns.md dans le même répertoire. Référencez-les depuis MEMORY.md pour que Claude Code les consulte au besoin.

Pour bien démarrer avec Claude Code et configurer votre environnement mémoire dès l'installation, suivez le guide d'installation et premier lancement.

À retenir : l'auto-mémoire MEMORY.md est générée par Claude Code lui-même, chargée dans le contexte (au-delà de 200 lignes environ, le contenu peut être tronqué), et complète les CLAUDE.md manuels, Claude Code évitant en général d'y écrire des entrées qui les contredisent.

Quand ne pas utiliser CLAUDE.md comme solution de configuration ?

CLAUDE.md n'est pas la réponse à tous les besoins de configuration. Voici les situations où d'autres approches sont préférables.

Arbre de décision

• Si votre règle concerne un seul type de fichier → utilisez .claude/rules/ avec un en-tête paths:
• Si votre règle est un secret ou une clé API → utilisez des variables d'environnement, jamais CLAUDE.md
• Si votre règle change à chaque session → passez-la dans le prompt directement, pas dans CLAUDE.md
• Si votre règle dépasse 400 lignes → découpez en règles modulaires
• Si vous travaillez en équipe et la règle est personnelle → placez-la dans ~/.claude/CLAUDE.md, pas à la racine

Limites connues

CLAUDE.md ne supporte pas de logique conditionnelle complexe. Vous ne pouvez pas écrire « si branche main, alors... ». Les règles modulaires avec paths: offrent un filtrage par fichier, mais pas par branche Git ni par variable d'environnement.

Un CLAUDE.md trop verbeux dégrade les performances. Un CLAUDE.md de 500 lignes consomme une part non négligeable du contexte, car les fichiers CLAUDE.md sont chargés intégralement quelle que soit leur longueur. Ce budget réduit l'espace disponible pour le code source que Claude Code analyse.

Pour comprendre comment le contexte est géré et optimisé au-delà de CLAUDE.md, le guide d'optimisation de la gestion du contexte apporte des stratégies complémentaires.

À retenir : réservez CLAUDE.md aux instructions persistantes, transversales et non sensibles : tout le reste a un meilleur emplacement.

Comment structurer la mémoire pour un projet d'équipe multi-développeurs ?

Dans un contexte d'équipe, la configuration mémoire de Claude Code demande une stratégie partagée. Définissez un CLAUDE.md racine commun et laissez chaque développeur personnaliser son fichier utilisateur.

Convention recommandée

# CLAUDE.md racine (versionné)
## Architecture
- Monorepo Nx avec 4 apps : web, api, admin, mobile
- Node.js 22 LTS, TypeScript 5.7 strict

## Workflow
- Branches : feature/<ticket>, fix/<ticket>
- Commits conventionnels obligatoires
- PR review requise avant merge

## Interdit
- Ne pas utiliser console.log en production (utiliser le logger)
- Ne pas modifier /packages/shared/ sans review

Chaque développeur ajoute ses préférences locales dans ~/.claude/CLAUDE.md : langue, outils personnels, aliases. Ces fichiers ne sont jamais versionnés.

Concrètement, une équipe de 6 développeurs utilisant un CLAUDE.md partagé de 120 lignes constate une réduction de une part notable des commentaires de review liés aux conventions de code.

Pour découvrir comment ces configurations s'intègrent dans vos premières interactions avec Claude Code, lisez le guide sur vos premières conversations.

SFEIR Institute propose la formation Claude Code d'une journée qui inclut un atelier pratique de configuration CLAUDE.md sur un projet réel. Vous y apprendrez à structurer votre mémoire projet en repartant avec un template prêt à l'emploi.

À retenir : en équipe, versionnez un CLAUDE.md racine partagé et laissez les préférences individuelles dans le fichier utilisateur.

Quels sont les edge cases et comportements subtils du système de mémoire ?

Plusieurs comportements de la mémoire Claude Code ne sont pas documentés de façon évidente. Anticipez ces cas pour éviter les surprises.

Ordre de chargement

Claude Code charge les fichiers dans cet ordre strict :

1. ~/.claude/CLAUDE.md (utilisateur global)
2. ./CLAUDE.md (racine projet)
3. .claude/rules/*.md (règles modulaires, découvertes récursivement)
4. ~/.claude/projects//memory/MEMORY.md (auto-mémoire)

En cas de contradiction, la dernière instruction chargée prévaut. L'auto-mémoire peut donc techniquement écraser une règle projet. En pratique, Claude Code évite d'écrire dans MEMORY.md des instructions qui contredisent un CLAUDE.md existant.

Troncature silencieuse

Au-delà de 200 lignes environ, MEMORY.md peut être tronqué sans avertissement. Les lignes supprimées ne génèrent aucune erreur. Surveillez la taille avec un hook pre-session ou un script dédié :

#!/bin/bash
LINES=$(wc -l < ~/.claude/projects/*/memory/MEMORY.md)
if [ "$LINES" -gt 180 ]; then
 echo "⚠ MEMORY.md approche la limite : $LINES/200 lignes"
fi

Encodage et caractères spéciaux

CLAUDE.md doit être encodé en UTF-8. Les caractères spéciaux dans les blocs de code sont correctement interprétés, et les commentaires HTML de niveau bloc sont retirés avant l'injection du fichier dans le contexte ; ceux placés à l'intérieur de blocs de code sont conservés.

L'analyse approfondie du coding agentique explore d'autres comportements subtils de Claude Code liés à l'autonomie de l'agent.

Pour approfondir le fonctionnement du système de mémoire, consultez également la FAQ sur le système de mémoire CLAUDE.md qui répond aux questions les plus fréquentes.

À retenir : l'ordre de chargement et la troncature silencieuse de MEMORY.md sont les deux pièges les plus fréquents à connaître.

Comment diagnostiquer et déboguer un problème de mémoire Claude Code ?

Lorsque Claude Code ne respecte pas une instruction de votre CLAUDE.md, suivez cette procédure de diagnostic structurée.

Étape 1 : Vérifiez le chargement

Lancez claude, puis exécutez la commande /memory dans la session pour afficher les fichiers mémoire actuellement chargés (projet, utilisateur, règles et auto-mémoire) et ouvrir chacun d'eux dans votre éditeur.

$ claude
> /memory
# Liste les fichiers mémoire chargés (CLAUDE.md projet, CLAUDE.md utilisateur,
# .claude/rules/*.md, MEMORY.md) et permet d'ouvrir chacun dans l'éditeur.

Étape 2 : Cherchez les conflits

Comparez vos différents fichiers mémoire. Un MEMORY.md qui contient « utiliser npm » alors que votre CLAUDE.md projet dit « utiliser bun » crée un conflit. L'auto-mémoire étant chargée en dernier, elle peut prendre le dessus.

Étape 3 : Purgez l'auto-mémoire si nécessaire

# Sauvegarder puis réinitialiser MEMORY.md
cp ~/.claude/projects/*/memory/MEMORY.md ~/backup-memory.md
echo "" > ~/.claude/projects/*/memory/MEMORY.md

Arbre de diagnostic

• Claude Code ignore une règle → vérifiez qu'elle est dans un fichier chargé (pas au-delà de la ligne 200)
• Claude Code applique une règle obsolète → cherchez dans MEMORY.md une entrée contradictoire
• Claude Code mélange deux projets → vérifiez le hash du répertoire dans ~/.claude/projects/

En pratique, de nombreux problèmes de mémoire proviennent d'un MEMORY.md qui contient une information obsolète écrasant une règle du CLAUDE.md projet.

Pour approfondir la compréhension du système de mémoire CLAUDE.md dans son ensemble, l'article de référence couvre les fondamentaux.

Si vous souhaitez maîtriser ces mécanismes avancés et apprendre à déboguer efficacement votre environnement de développement augmenté, SFEIR Institute propose la formation Développeur Augmenté par l'IA sur 2 jours, avec des labs pratiques couvrant la configuration mémoire, le débogage et les workflows avancés. Pour aller encore plus loin, la formation Développeur Augmenté par l'IA – Avancé d'une journée approfondit les stratégies d'optimisation du prompt système et les architectures multi-agents.

À retenir : la commande /memory est votre premier réflexe de diagnostic : elle permet d'éditer le CLAUDE.md et de gérer la mémoire automatique.

---