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

Le fichier CLAUDE.md est le système de mémoire persistante de Claude Code qui stocke vos préférences, conventions et instructions de projet entre les sessions. Ce guide FAQ répond aux questions les plus fréquentes sur la configuration de CLAUDE.md, la hiérarchie des mémoires et les règles modulaires pour optimiser votre productivité avec l'agent IA.

Le système de mémoire CLAUDE.md est le mécanisme central par lequel Claude Code conserve le contexte de vos projets d'une session à l'autre. ce système repose sur une hiérarchie de fichiers - CLAUDE.md, .claude/rules/ et MEMORY.md - qui permettent de personnaliser le comportement de l'agent sans répéter vos instructions. plus de 78 % des développeurs utilisant Claude Code créent un fichier CLAUDE.md dans leurs 48 premières heures d'utilisation.

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

CLAUDE.md est un fichier Markdown chargé automatiquement dans le prompt système de Claude Code à chaque nouvelle conversation. Il fonctionne comme une mémoire persistante qui transmet vos instructions, conventions et préférences à l'agent.

Concrètement, Claude Code recherche ce fichier à plusieurs emplacements au démarrage. Le contenu est injecté avant votre premier message, ce qui permet à l'agent de respecter vos règles dès la première interaction.

En pratique, un fichier CLAUDE.md de 50 lignes consomme environ 2 000 tokens de contexte, soit moins de 1 % de la fenêtre disponible avec Claude Opus 4.6.

Vérifiez que votre CLAUDE.md existe en lançant cette commande :

$ cat CLAUDE.md

Pour bien comprendre comment Claude Code gère sa fenêtre de contexte avec ces fichiers, consultez la FAQ sur la gestion du contexte qui détaille les mécanismes de compression.

À retenir : CLAUDE.md est chargé automatiquement à chaque session - c'est votre canal de communication persistant avec l'agent.

Quelle est la hiérarchie des fichiers de mémoire de Claude Code ?

Claude Code utilise trois niveaux de mémoire, chargés dans un ordre précis qui détermine leur priorité.

Le fichier à la racine du dépôt (./CLAUDE.md) est le plus utilisé. Il est versionné avec Git et partagé avec toute l'équipe. Le fichier global ~/.claude/CLAUDE.md s'applique à tous vos projets - idéal pour des préférences universelles comme votre langue ou votre style de commit.

Créez votre CLAUDE.md global avec :

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

Depuis la version 2.0 de Claude Code (janvier 2026), les fichiers de mémoire supportent l'import de règles modulaires via le dossier .claude/rules/. Pour approfondir la gestion des permissions liées à ces fichiers, consultez la FAQ sur les permissions et la sécurité.

À retenir : la hiérarchie suit le principe de spécificité - le fichier le plus proche du projet l'emporte.

Comment rédiger un CLAUDE.md efficace pour son projet ?

Structurez votre CLAUDE.md en sections claires avec des directives courtes et actionnables.

Un CLAUDE.md efficace contient entre 30 et 100 lignes. Au-delà de 200 lignes, le ratio signal/bruit diminue et consomme inutilement la fenêtre de contexte. les instructions concises en liste à puces sont 40 % plus respectées que les paragraphes longs.

Voici comment structurer un CLAUDE.md performant :

# Conventions du projet

- Langage : TypeScript strict, pas de `any`
- Tests : Vitest, coverage minimum 80%
- Commits : format Conventional Commits
- Style : Prettier + ESLint, pas de `console.log`

# Architecture

- Framework : Next.js 15 App Router
- Base de données : PostgreSQL via Prisma
- Déploiement : Vercel

# Règles de comportement

- Toujours lire un fichier avant de le modifier
- Ne jamais committer sans demander
- Utiliser les imports absolus (@/lib, @/components)

Évitez les instructions vagues comme "écris du bon code". Préférez les directives mesurables : "chaque fonction doit avoir moins de 30 lignes". Vous trouverez d'autres exemples concrets dans les astuces pour CLAUDE.md.

À retenir : un CLAUDE.md de 50 lignes ciblées vaut mieux qu'un document de 300 lignes vagues.

Quels sont les cas d'usage des règles modulaires dans .claude/rules/ ?

Les règles modulaires sont des fichiers Markdown placés dans .claude/rules/ et chargés automatiquement en complément de CLAUDE.md.

Chaque fichier .md dans ce dossier est injecté dans le prompt système. Ce mécanisme permet de séparer les préoccupations : un fichier pour le style, un pour les tests, un pour le déploiement.

En pratique, une équipe de 12 développeurs chez SFEIR utilise 6 fichiers de règles modulaires distincts pour un projet Next.js. Voici une structure type :

.claude/
  rules/
    coding-style.md      # 15 lignes
    testing.md            # 20 lignes
    git-workflow.md       # 10 lignes
    security.md           # 12 lignes

Créez un fichier de règle avec :

$ mkdir -p .claude/rules
$ echo "- Toujours écrire les tests avant le code" > .claude/rules/testing.md

Pour comprendre comment ces fichiers interagissent avec le coding agentique, pensez aux règles comme des garde-fous que l'agent respecte même en mode autonome.

À retenir : les règles modulaires facilitent la revue de code et la gouvernance des instructions données à l'agent.

Comment configurer Auto Memory et MEMORY.md ?

Auto Memory est un système où Claude Code écrit lui-même ses notes dans un fichier MEMORY.md stocké dans ~/.claude/projects/.

Contrairement à CLAUDE.md que vous rédigez manuellement, MEMORY.md est alimenté par l'agent au fil de vos sessions. Il y consigne les patterns récurrents, les erreurs corrigées et vos préférences observées. Le fichier est limité à 200 lignes dans le prompt système.

Activez Auto Memory en vous assurant que le dossier de projet existe :

$ ls ~/.claude/projects/

En pratique, après 10 sessions sur un même projet, MEMORY.md contient en moyenne 30 à 50 lignes de notes contextuelles. Vous pouvez éditer ce fichier manuellement pour corriger ou supprimer des informations obsolètes.

Pour aller plus loin sur la gestion de la mémoire, le guide complet du système de mémoire CLAUDE.md détaille chaque mécanisme en profondeur.

À retenir : MEMORY.md est la mémoire apprise de l'agent - CLAUDE.md est la mémoire que vous lui imposez.

Peut-on partager CLAUDE.md avec son équipe via Git ?

Oui, le fichier CLAUDE.md à la racine du projet est conçu pour être versionné et partagé via Git.

Commitez votre CLAUDE.md comme n'importe quel fichier de configuration. Toute l'équipe bénéficiera des mêmes instructions. En revanche, MEMORY.md et .claude/settings.local.json doivent rester dans le .gitignore car ils contiennent des données personnelles.

Voici comment configurer votre .gitignore :

# Claude Code - fichiers personnels
.claude/settings.local.json
.claude/memory/

# Claude Code - fichiers partagés (NE PAS ignorer)
# CLAUDE.md
# .claude/rules/

les équipes qui partagent leur CLAUDE.md constatent une réduction de 35 % des corrections de style lors des revues de code. Pour découvrir comment automatiser l'application de ces règles en CI/CD, consultez la FAQ sur le mode headless.

À retenir : versionnez CLAUDE.md et .claude/rules/, gardez MEMORY.md en local.

Combien de tokens consomme le système de mémoire ?

Un fichier CLAUDE.md de 100 lignes consomme environ 4 000 tokens, soit 2 % de la fenêtre de contexte de Claude Opus 4.6 (200 000 tokens).

Chaque fichier de règle modulaire ajoute entre 200 et 800 tokens selon sa taille. Le total de vos fichiers de mémoire ne devrait pas dépasser 10 000 tokens pour laisser suffisamment d'espace au code et aux échanges.

En pratique, 9 600 tokens représentent 4,8 % de la fenêtre de 200 000 tokens - un investissement raisonnable pour la cohérence obtenue. Pour comprendre comment optimiser le contexte restant, la FAQ sur la gestion du contexte propose des stratégies concrètes.

À retenir : visez un budget mémoire total sous les 10 000 tokens pour préserver 95 % de votre fenêtre de contexte.

Quelles erreurs éviter dans son fichier CLAUDE.md ?

L'erreur la plus fréquente est de rédiger un CLAUDE.md trop long avec des instructions contradictoires.

Voici les 5 erreurs les plus courantes, classées par fréquence :

1. Instructions contradictoires - "utilise des points-virgules" dans une section et "pas de points-virgules" dans une autre
2. Paragraphes vagues - "fais attention à la qualité du code" sans critères mesurables
3. Duplication - répéter les mêmes règles dans CLAUDE.md et .claude/rules/
4. Fichier trop volumineux - au-delà de 200 lignes, l'agent perd en précision de suivi
5. Absence de structure - pas de sections Markdown, tout en vrac

Testez votre CLAUDE.md en demandant à Claude Code de le résumer :

$ claude "Résume les instructions de mon CLAUDE.md en 5 points"

Si l'agent ne peut pas résumer clairement vos instructions, elles sont trop floues ou contradictoires. Le guide des erreurs courantes liées à CLAUDE.md documente chaque piège avec des solutions concrètes.

À retenir : un CLAUDE.md doit être lisible par un humain ET par un LLM - testez les deux lectures.

Comment demander à Claude Code de mémoriser une préférence ?

Dites simplement "Retiens que j'utilise toujours Bun au lieu de npm" et l'agent enregistrera cette préférence dans MEMORY.md.

Claude Code distingue deux types de demandes : les instructions de session (temporaires) et les demandes de mémorisation (persistantes). Le mot-clé "retiens" ou "souviens-toi" déclenche l'écriture dans MEMORY.md.

Voici comment formuler vos demandes de mémorisation :

# Demandes qui seront mémorisées
"Retiens que je préfère les arrow functions"
"Souviens-toi de toujours utiliser pnpm"
"N'oublie pas : jamais de console.log en production"

# Demandes de session uniquement (non mémorisées)
"Pour cette session, utilise des tabs"
"Aujourd'hui, ne touche pas au dossier /legacy"

Concrètement, chaque préférence mémorisée occupe 1 à 3 lignes dans MEMORY.md. Avec la limite de 200 lignes, vous disposez d'un budget d'environ 80 à 150 préférences distinctes. Pour vos premières interactions avec l'agent, la FAQ sur vos premières conversations vous guide pas à pas.

À retenir : utilisez "retiens" pour les préférences durables, réservez CLAUDE.md pour les règles d'équipe.

Faut-il un CLAUDE.md différent par branche Git ?

Non, un seul CLAUDE.md à la racine du projet suffit dans la majorité des cas.

Le fichier suit les règles de Git : si vous le modifiez sur une branche, la modification reste sur cette branche jusqu'au merge. Cela peut servir pour des branches de refactoring majeur avec des conventions temporaires différentes.

En 2026, la pratique recommandée par SFEIR Institute est de maintenir un CLAUDE.md stable sur main et d'ajouter des fichiers de règles modulaires spécifiques sur les branches de feature quand nécessaire.

# Sur une branche de migration TypeScript
$ echo "- Convertir tous les .js en .ts avant modification" > .claude/rules/migration.md
$ git add .claude/rules/migration.md
$ git commit -m "chore: add migration rules for Claude Code"

Cette approche évite les conflits de merge sur CLAUDE.md tout en adaptant le comportement de l'agent au contexte de la branche. Pour configurer Claude Code sur un nouveau projet depuis l'installation, pensez à créer votre CLAUDE.md dès le premier jour.

À retenir : gardez un CLAUDE.md stable sur main et utilisez les règles modulaires pour les variations par branche.

Quels sont les liens entre CLAUDE.md et le Model Context Protocol (MCP) ?

CLAUDE.md et MCP sont deux systèmes complémentaires : CLAUDE.md fournit des instructions statiques, MCP connecte Claude Code à des sources de données dynamiques.

MCP (Model Context Protocol) est un standard ouvert qui permet à Claude Code d'interagir avec des serveurs externes (bases de données, API, systèmes de fichiers distants). Vous pouvez référencer vos serveurs MCP dans CLAUDE.md pour que l'agent les utilise automatiquement.

# Dans CLAUDE.md
## Serveurs MCP disponibles

- Serveur PostgreSQL : données clients (lecture seule)
- Serveur GitHub : accès aux issues et PRs
- Utiliser le serveur MCP PostgreSQL pour toute requête sur les données clients

En pratique, 23 % des projets avec un CLAUDE.md configurent aussi au moins un serveur MCP. Pour comprendre comment configurer et utiliser MCP, consultez la FAQ complète sur le Model Context Protocol.

À retenir : CLAUDE.md donne les instructions, MCP fournit les outils - les deux se complètent pour un agent plus capable.

Comment auditer et maintenir son CLAUDE.md dans le temps ?

Planifiez une revue trimestrielle de votre CLAUDE.md, comme pour toute documentation technique.

Un CLAUDE.md non maintenu accumule des instructions obsolètes - versions de dépendances dépassées, conventions abandonnées, règles contradictoires ajoutées par différents membres de l'équipe. la bonne pratique consiste à dater chaque section modifiée.

Voici un processus d'audit en 4 étapes :

1. Lancez une analyse par Claude Code : claude "Liste les instructions potentiellement obsolètes dans CLAUDE.md"
2. Vérifiez la cohérence avec votre package.json et tsconfig.json
3. Supprimez les règles qui dupliquent votre configuration ESLint ou Prettier
4. Validez que le total reste sous 100 lignes

Concrètement, un audit trimestriel prend entre 15 et 30 minutes et réduit en moyenne de 25 % le nombre de tokens consommés par la mémoire. Pour approfondir les techniques de maintenance, les astuces pour CLAUDE.md proposent des checklists prêtes à l'emploi.

Si vous souhaitez maîtriser ces techniques en conditions réelles, la formation Claude Code de SFEIR Institute (1 jour) vous permet de configurer un environnement complet avec CLAUDE.md, règles modulaires et serveurs MCP lors de labs pratiques encadrés.

Pour aller plus loin, la formation Développeur Augmenté par l'IA (2 jours) couvre l'intégration de ces outils dans un workflow de développement professionnel complet, tandis que le module Développeur Augmenté par l'IA – Avancé (1 jour) approfondit les patterns avancés d'automatisation et de personnalisation.

À retenir : traitez CLAUDE.md comme du code - versionnez, reviewez et nettoyez régulièrement.