L’engouement autour des assistants de programmation a inondé le marché de promesses, mais une différence pratique distingue un chatbot « suggérant du code » d’un véritable agent d’aide : la capacité de travailler de manière cohérente avec un référentiel complet. C’est là qu’intervient Claude Code, l’outil agéntique d’Anthropic conçu pour lire une base de code, éditer des fichiers et exécuter des commandes dans le flux habituel de développement.

Dans cette logique, un fichier Markdown apparemment banal devient central : CLAUDE.md. Il ne s’agit pas d’un modèle décoratif ou d’un README alternatif. C’est, en essence, le document qui définit le comportement attendu de Claude Code dans un projet, les règles à suivre et ce qui signifie « terminé ». Bien conçu, il réduit les malentendus, accélère les itérations et empêche l’agent « improviser » des décisions qu’il ne devrait pas prendre.

Qu’est-ce que CLAUDE.md et pourquoi est-ce important ?

Claude Code fonctionne avec une idée centrale : le contexte ne peut pas dépendre uniquement de ce qui est dit lors d’une conversation. Les projets réels ont des conventions, des commandes récurrentes, des décisions architecturales et des exigences de validation qu’il est inutile de répéter à chaque session. Pour cela, Anthropic distingue deux formes de mémoire persistante :

• Auto memory : des notes que Claude conserve automatiquement sur les modèles du projet, les commandes clés ou préférences.
• CLAUDE.md : fichiers Markdown que l’utilisateur (ou l’équipe) rédige et maintient, contenant instructions, règles et préférences que l’agent doit suivre.

Ce découpage définit le rôle de CLAUDE.md : l’aspect normatif. Autrement dit, le « manuel d’utilisation » du référentiel : ce qui doit être fait, comment et ce qui est interdit de toucher.

Où le placer et quels niveaux de mémoire existent

Une des forces du design réside dans la hiérarchie de la mémoire, permettant de séparer les instructions selon leur portée :

• Politique gérée (organisation) : règles d’entreprise administrées par IT/DevOps (normes, conformité, sécurité).
• Mémoire du projet : ./CLAUDE.md ou ./.claude/CLAUDE.md (partagé dans le dépôt).
• Règles modulaires du projet : ./.claude/rules/*.md (par thèmes : style, tests, sécurité, API…).
• Mémoire utilisateur : ~/.claude/CLAUDE.md (préférences personnelles pour tous les projets).
• Mémoire locale du dépôt : ./CLAUDE.local.md (préférences privées pour ce dépôt, non versionné).
• Auto memory : répertoire par projet dans ~/.claude/projects//memory/.

Ce qui facilite la gestion, c’est que CLAUDE.local.md est généralement celui qui fait le plus économiser, car il est automatiquement ignoré par .gitignore. Il permet d’y stocker par exemple des URLs de sandbox ou des données de test locales sans « polluer » le dépôt avec des infos personnelles ou non partageables.

Comment Claude Code « lit » ces fichiers

Claude Code charge la mémoire de façon récursive :

• Les CLAUDE.md situés en amont du répertoire de travail se chargent intégralement au démarrage.
• Les CLAUDE.md dans les sous-dossiers sont chargés à la demande, lorsque Claude accède à ces arborescences.
• En cas de conflit, les instructions plus spécifiques ont priorité sur les générales.

Ce comportement est particulièrement utile dans de grands dépôts : on peut avoir un CLAUDE.md général à la racine, avec des règles précises pour frontend/, infra/ ou src/api/ sans que tout ne se mélange sans cohérence.

Importations : réutiliser la documentation sans dupliquer la « vérité »

Claude Code permet que CLAUDE.md importe d’autres fichiers via la syntaxe @chemin/vers/import. L’idée, simple mais puissante, est que plutôt que de recopier commandes ou conventions à plusieurs endroits, on peut importer des sources existantes (README, package.json, documents internes, guides Git, etc.).

Voici les points importants :

• Les chemins peuvent être relatifs ou absolus ; les relatifs se résolvent par rapport au fichier qui fait l’import.
• Claude Code demande une approbation la première fois qu’il détecte une importation externe (hors projet), pour des raisons de sécurité.
• Les imports ne s’évaluent pas à l’intérieur de blocs Markdown, évitant les collisions ou erreurs.
• Les imports peuvent être récursifs, avec une limite de profondeur.

De plus, la commande /memory permet de voir quelles mémoires sont chargées ainsi que d’éditer ces fichiers directement dans l’environnement interactif.

Auto memory et MEMORY.md : le carnet de notes de l’agent

Contrairement à CLAUDE.md, auto memory correspond à « ce que Claude apprend » lors de son travail. Il est stocké dans un répertoire par projet (~/.claude/projects//memory/) avec un fichier principal appelé MEMORY.md et éventuellement des fichiers thématiques (ex : debugging.md ou api-conventions.md).

Une règle cruciale : seules les 200 premières lignes de MEMORY.md sont chargées automatiquement» à chaque début de session. Le reste n’est pas par défaut intégré, et Claude est instruit pour garder cet index synthétique en déplaçant les détails dans des fichiers spécifiques lus à la demande.

Auto memory peut être activé ou désactivé via /memory, ou par configuration (~/.claude/settings.json ou .claude/settings.json), voire via une variable d’environnement pour gestion dans des scénarios CI ou orchestrations extérieures.

.claude/rules : règles modulaires par thèmes et chemins

Pour des dépôts complexes, l’approche modulaire d’Anthropic recommande des règles en .claude/rules/*.md. Plutôt que de tout mettre dans CLAUDE.md, on peut séparer les directives par thèmes : style, tests, sécurité, API, etc.

Ces règles peuvent aussi être conditionnelles en fonction du chemin, grâce à un frontmatter YAML avec un champ paths. Cela permet par exemple d’imposer une validation d’entrée et une documentation OpenAPI uniquement sur src/api/, sans l’appliquer à l’ensemble du dépôt.

Comment élaborer un CLAUDE.md efficace

Un CLAUDE.md performant ne naît pas parfait. Il se construit comme un bon runbook, étape par étape, en s’adaptant à l’utilisation réelle. Avec Claude Code, le point de départ est souvent la commande /init, qui génère une première version à partir de la structure du projet. Ensuite, l’amélioration suit généralement ces axes :

1. Préciser les commandes et flux : build, test, lint, déploiement, reproduction de bugs.
2. Définir des critères vérifiables : quels tests doivent passer, quels endpoints doivent répondre, quelles sorties sont correctes.
3. Conserver les décisions sensibles : ce qu’il ne faut surtout pas toucher (structure, dépendances interdites, motifs obligatoires).
4. Modulariser en cas de croissance : déplacer des règles dans .claude/rules/ et utiliser les imports pour éviter la répétition documentaire.
5. Garder privé ce qui doit l’être : tout ce qui est local ou personnel, dans CLAUDE.local.md, jamais dans le dépôt.

L’objectif n’est pas d’écrire une thèse, mais de réduire l’ambiguïté. Un agent est plus performant quand il a moins besoin d’interpréter « ce que voulait dire » l’humain.

Modèle simplifié (guide)

# CLAUDE.md — Guide du projet
## Contexte
- Description synthétique du dépôt et de sa finalité (2-3 lignes).

## Structure
- Détail des dossiers principaux : A, B, etc.
- Fichiers clés : nom, rôle.

## Commandes
- Installer : ...
- Développement : ...
- Tests : ...
- Lint/Format : ...
- Build/Release : ...

## Conventions
- Style, nommage, motifs.
- Dépendances autorisées/interdites.
- Points à ne pas modifier.

## Définition de « terminé »
- Tests, lint, build passés.
- Critères fonctionnels vérifiables.

Questions fréquentes

Quels sont exactement CLAUDE.md dans Claude Code ?
Un fichier Markdown contenant des instructions persistantes (règles, conventions, flux) que Claude Code charge pour assurer une cohérence dans le travail sur un projet.

En quoi diffère-t-il de auto memory (MEMORY.md) ?
CLAUDE.md est rédigé par l’utilisateur/l’équipe (normes). Auto memory, lui, écrit Claude (notes apprises) et ne charge que par défaut les 200 premières lignes de MEMORY.md.

À quoi servent .claude/rules et les règles par chemins ?
À organiser les directives par thèmes et appliquer des règles spécifiques à des parties du dépôt via des modèles de chemin.

Quelle est la façon la plus rapide de démarrer ?
Utiliser /init pour générer un brouillon, puis le peaufiner avec des commandes concrètes, critères vérifiables et règles pour limiter l’ambiguïté.

Pour plus d’informations : Retour à la programmation et Qu’est-ce que Claude.md ?