CLAUDE.md : le fichier que Claude Code lit avant votre code

Ce que vous allez apprendre, et pourquoi personne ne vous l’a dit

Quand vous lancez Claude Code, la première chose qui se passe n’est pas ce que vous croyez. Avant de lire votre code, avant d’analyser votre arborescence, avant même de considérer votre question, Claude Code cherche un fichier. Un fichier Markdown. Il s’appelle CLAUDE.md, et son contenu est injecté dans chaque conversation, chaque session, chaque interaction, sans exception.

La documentation officielle d’Anthropic consacre à ce fichier une page d’environ 400 mots. Un tableau, quelques commandes, trois bullet points de bonnes pratiques. C’est à peu près tout. On y apprend qu’il sert à « documenter des commandes bash, des guidelines et de l’étiquette de dépôt ». C’est factuellement exact. C’est aussi spectaculairement insuffisant.

En réalité, CLAUDE.md n’est pas un fichier de documentation. C’est un prompt système persistant, le seul que vous écriviez une fois et qui s’exécute à chaque session. C’est le levier à plus haut rendement de tout l’écosystème Claude Code (un écosystème dont Anthropic a fait le fer de lance de sa stratégie) et la plupart des développeurs soit l’ignorent, soit le remplissent avec du contenu qui dégrade activement les performances du modèle.

Cet article est le guide que la documentation officielle n’a pas écrit. Il couvre la mécanique interne (comment Claude Code injecte réellement le fichier, et ce n’est pas ce que vous imaginez), la hiérarchie complète des niveaux de mémoire (il y en a six, pas quatre), l’économie de l’attention (chaque ligne a un coût mesurable), les patterns qui fonctionnent en production, les anti-patterns qui sabotent silencieusement vos résultats, et un exemple complet commenté ligne par ligne. Le tout adossé à la documentation officielle, aux retours des équipes internes d’Anthropic, et aux découvertes des développeurs qui utilisent Claude Code quotidiennement sur des systèmes de production.

Si vous avez déjà lu mon guide sur les fichiers SKILL.md, vous connaissez l’approche : on part de la doc officielle, on la dépasse, et on construit quelque chose d’actionnable.

Sommaire

Toggle

Ce que CLAUDE.md est vraiment

Pas un README, pas une doc : un prompt

Il faut commencer par déconstruire un malentendu. La métaphore la plus répandue pour décrire CLAUDE.md est celle du « README pour Claude » ou du « guide d’onboarding pour un nouveau développeur ». C’est une métaphore séduisante. C’est aussi la raison pour laquelle la plupart des fichiers CLAUDE.md sont médiocres.

Un README s’adresse à un humain qui va le lire une fois, retenir l’essentiel, et revenir le consulter ponctuellement. Un CLAUDE.md s’adresse à un modèle de langage qui le lit intégralement, à chaque session, et dont l’attention est une ressource finie et mesurable en tokens.

Un guide d’onboarding explique le contexte, les raisons historiques, les nuances culturelles. Il peut se permettre d’être verbeux parce qu’un humain filtre naturellement ce qui est pertinent. Un modèle de langage ne filtre pas de la même manière, ou plutôt, il filtre, mais pas toujours ce que vous voudriez qu’il filtre.

La bonne métaphore, celle qui change concrètement la façon dont vous allez écrire le fichier, c’est celle du prompt système incrémental. CLAUDE.md est un prompt que vous peaufinez au fil du temps, qui s’empile avec les autres couches de contexte (prompt système de Claude Code, Skills, fichiers lus pendant la session), et qui consomme du budget d’attention à chaque conversation.

Eyad Khrais, CTO et ancien ingénieur chez Amazon, Disney et Capital One, résume la distinction de manière tranchante : « Un mauvais CLAUDE.md ressemble à de la documentation écrite pour un nouveau développeur. Un bon CLAUDE.md ressemble aux notes que vous vous laisseriez si vous saviez que vous auriez une amnésie demain. »

La différence avec AGENTS.md

Si vous suivez l’écosystème des outils de codage assistés par IA, vous avez probablement croisé AGENTS.md, un format ouvert, désormais géré par l’Agentic AI Foundation sous la Linux Foundation, qui sert exactement le même objectif : fournir du contexte persistant à un agent de codage.

La différence est philosophique. AGENTS.md est un standard inter-plateformes conçu pour être portable : OpenAI Codex, Google Jules, Cursor, Factory l’utilisent tous. Claude Code, lui, ne lit pas AGENTS.md. Il utilise exclusivement CLAUDE.md.

Ce n’est pas un caprice. Le choix d’Anthropic reflète le fait que CLAUDE.md est traité comme un fichier de prompt interne, pas comme une documentation externe. La preuve la plus tangible de cette distinction est la façon dont Claude Code injecte le contenu : nous y reviendrons dans la section sur la mécanique interne, et c’est probablement la révélation la plus contre-intuitive de cet article.

Pour les projets multi-outils, deux approches coexistent. La première est le lien symbolique : ln -s CLAUDE.md AGENTS.md à la racine du dépôt, pour que tous les agents lisent le même fichier. La seconde est l’import : dans votre CLAUDE.md, ajouter une ligne @AGENTS.md qui tire le contenu du fichier standard. Chaque approche a ses compromis : le symlink est plus simple mais empêche la différenciation, l’import permet d’avoir un noyau commun et des instructions spécifiques à Claude.

L’articulation avec les Skills et MCP

CLAUDE.md n’existe pas seul. Il s’inscrit dans un écosystème à trois couches que j’ai détaillé dans mon article sur les Skills :

• CLAUDE.md = identité et conventions. C’est le « qui je suis et comment je travaille ». Toujours chargé, à chaque session.
• Skills = savoir procédural réutilisable. C’est le « comment faire telle tâche ». Chargé à la demande, quand Claude détecte qu’une Skill est pertinente.
• MCP = connexions au monde extérieur. C’est les « mains et yeux sur les systèmes externes ». Activé quand une interaction avec un service tiers est nécessaire.

L’heuristique est simple : si c’est purement contextuel et applicable à toutes les sessions → CLAUDE.md. Si c’est un workflow réutilisable avec des étapes précises → Skill. Si ça touche un système externe (GitHub, Slack, base de données, API) → MCP.

Un exemple concret pour fixer les idées : la convention de nommage des branches git va dans CLAUDE.md (applicable à chaque session). Le workflow complet de release (créer la branche, bumper la version, générer le changelog, ouvrir la PR) va dans une Skill. La publication effective sur GitHub via l’API va dans un serveur MCP.

La différence de coût est réelle. Chaque token dans CLAUDE.md pèse plus lourd qu’un token dans une Skill, parce qu’il est présent à chaque session, même quand il n’est pas pertinent. Les Skills bénéficient du chargement progressif en trois niveaux : seul le frontmatter est permanent, le corps se charge à la demande. CLAUDE.md n’a pas ce luxe. Tout son contenu est injecté, tout le temps. Si la mécanique des tokens et de la troncature vous intéresse, j’ai consacré un article entier à la façon dont les IA gèrent (et dégradent) le contexte qu’on leur fournit.

La mécanique interne : comment Claude Code injecte réellement le fichier

La révélation du proxy

C’est probablement l’information la plus importante de cet article, et elle ne figure dans aucune documentation officielle.

Les développeurs de HumanLayer ont placé un proxy de journalisation entre le CLI Claude Code et l’API Anthropic via ANTHROPIC_BASE_URL pour observer exactement ce que Claude Code envoie au modèle. Ce qu’ils ont découvert est contre-intuitif.

Le contenu de CLAUDE.md n’est pas injecté dans le prompt système (le system message de l’API). Il est injecté dans le message utilisateur, accompagné d’un rappel explicite :

IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.

Relisez cette phrase. Anthropic dit explicitement au modèle que le contenu de votre CLAUDE.md peut ne pas être pertinent, et qu’il ne devrait en tenir compte que s’il le juge « hautement pertinent » pour la tâche en cours.

Les implications pratiques

Cette découverte change radicalement la façon dont vous devriez écrire le fichier.

Première implication : plus vous avez de contenu non universellement applicable dans le fichier, plus il est probable que Claude ignore l’ensemble de vos instructions, y compris celles qui sont pertinentes. Le modèle reçoit un signal explicite lui disant de filtrer, et un fichier verbeux rempli de cas particuliers lui donne de bonnes raisons de filtrer agressivement.

Deuxième implication : les instructions qui ne s’appliquent qu’à certains types de tâches (par exemple, « comment structurer un nouveau schéma de base de données ») polluent le contexte quand vous travaillez sur autre chose. Claude les voit, évalue leur pertinence, et les écarte, mais ce processus d’évaluation consomme de l’attention et brouille le signal.

Troisième implication : la concision n’est pas une préférence esthétique, c’est une nécessité mécanique. Chaque ligne qui n’est pas universellement pertinente augmente la probabilité que les lignes pertinentes soient ignorées.

C’est pour cette raison qu’Anthropic mentionne dans ses best practices qu’il est parfois nécessaire d’utiliser des emphases comme « IMPORTANT » ou « YOU MUST » pour améliorer l’adhérence, et qu’ils recommandent de passer le contenu de CLAUDE.md dans leur propre prompt improver. C’est un aveu implicite : le modèle ne suit pas automatiquement tout ce qui se trouve dans le fichier.

Le mécanisme de lookup

Quand vous lancez Claude Code dans un répertoire, voici ce qui se passe dans l’ordre :

1. Récursion ascendante : Claude Code part du répertoire courant et remonte l’arborescence jusqu’à la racine du système de fichiers (exclu), en lisant chaque CLAUDE.md et CLAUDE.local.md rencontré en chemin.
2. Chargement au lancement : tous les fichiers trouvés lors de cette récursion sont injectés dans le contexte immédiatement.
3. Découverte descendante : les fichiers CLAUDE.md dans les sous-répertoires du répertoire courant ne sont pas chargés au lancement. Ils sont inclus à la demande, quand Claude travaille avec des fichiers dans ces sous-répertoires.

En monorepo, cela signifie que si vous lancez Claude Code depuis monorepo/apps/web/, il chargera :

• monorepo/CLAUDE.md (racine du projet)
• monorepo/apps/CLAUDE.md (si existant)
• monorepo/apps/web/CLAUDE.md (répertoire courant)

Et si pendant la session il édite un fichier dans monorepo/apps/web/components/, il découvrira et chargera monorepo/apps/web/components/CLAUDE.md à ce moment-là, pas avant.

La hiérarchie complète : six niveaux, pas quatre

La documentation officielle présente quatre niveaux de mémoire. En réalité, il en existe six. Voici la hiérarchie complète, du plus global au plus spécifique.

TL;DR des six niveaux : Enterprise policy (organisation) → User memory (personnel, global) → Project memory (équipe, commit) → Project local (personnel, gitignored) → Rules scoped (équipe, conditionnel) → Auto memory (Claude écrit pour lui-même).

Niveau 1 : Enterprise policy

Emplacement :

• macOS : /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux : /etc/claude-code/CLAUDE.md
• Windows : C:\Program Files\ClaudeCode\CLAUDE.md

Objectif : instructions à l’échelle de l’organisation, gérées par IT/DevOps. Standards de codage d’entreprise, politiques de sécurité, exigences de conformité.

Déployé via : systèmes de gestion de configuration (MDM, Group Policy, Ansible). Les développeurs individuels n’ont pas à s’en préoccuper, c’est l’affaire des administrateurs.

Partagé avec : tous les utilisateurs de l’organisation.

Niveau 2 : User memory

Emplacement : ~/.claude/CLAUDE.md

Objectif : préférences personnelles qui s’appliquent à tous vos projets. Style de code, raccourcis personnels, préférences d’outillage.

Partagé avec : personne. C’est votre fichier personnel.

Exemples de contenu :

# Préférences personnelles
- Répondre en français sauf indication contraire
- Utiliser des noms de variables explicites, jamais d'abréviations
- Toujours commiter avec des messages conventionnels (feat:, fix:, refactor:)
- Ne pas me féliciter, si c'est correct fais-le, si c'est douteux demande
Langage du code : Markdown (markdown)

Niveau 3 : Project memory

Emplacement : ./CLAUDE.md ou ./.claude/CLAUDE.md à la racine du projet

Objectif : instructions partagées par l’équipe pour le projet. Architecture, conventions de code, commandes fréquentes, workflows.

Partagé avec : tous les membres de l’équipe via le contrôle de version. C’est le fichier que vous committez et que vous maintenez en PR.

C’est le niveau le plus important et celui sur lequel porte l’essentiel de cet article.

Niveau 4 : Project memory (local)

Emplacement : ./CLAUDE.local.md

Objectif : préférences personnelles spécifiques au projet. Vos URLs de sandbox, vos données de test préférées, vos raccourcis personnels.

Partagé avec : personne. Automatiquement ajouté à .gitignore.

Niveau 5 : Rules (le mécanisme méconnu)

Emplacement : .claude/rules/*.md

Objectif : règles conditionnelles scopées à des fichiers spécifiques via un frontmatter YAML.

C’est le mécanisme le plus puissant et le moins documenté de toute la hiérarchie. Les fichiers dans .claude/rules/ sont automatiquement chargés avec la même priorité que .claude/CLAUDE.md, mais ils peuvent être conditionnés à des patterns de fichiers.

Exemple d’une règle scopée au frontend :

---
paths:
  - "src/frontend/**/*.tsx"
  - "src/frontend/**/*.ts"
---
# Règles Frontend React

- Utiliser des composants fonctionnels avec hooks, jamais de classes
- Tous les composants doivent avoir un fichier de test associé
- Utiliser React Testing Library, pas Enzyme
- Les styles passent par Tailwind, pas de fichiers CSS séparés
- Les composants partagés vivent dans src/frontend/components/ui/
Langage du code : Markdown (markdown)

Exemple d’une règle scopée au backend :

---
paths:
  - "src/api/**/*.py"
---
# Règles Backend FastAPI

- Toutes les routes API doivent inclure la validation d'entrée avec Pydantic
- Utiliser le format de réponse d'erreur standard (voir src/api/errors.py)
- Inclure les commentaires de documentation OpenAPI
- Tester chaque endpoint avec pytest et httpx
Langage du code : Markdown (markdown)

Les règles sans champ paths sont chargées inconditionnellement et s’appliquent à tous les fichiers. Les règles peuvent être organisées en sous-répertoires :

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md
Langage du code : Markdown (markdown)

L’avantage est majeur : au lieu de surcharger votre CLAUDE.md principal avec des instructions qui ne sont pertinentes que pour certains types de fichiers, vous les isolez dans des règles scopées. Le contenu spécifique au frontend ne pollue pas le contexte quand Claude travaille sur le backend, et inversement. C’est la divulgation progressive appliquée à la mémoire projet.

Niveau 6 : Auto memory

Emplacement : ~/.claude/projects/<projet>/memory/

Objectif : notes que Claude écrit pour lui-même au fil des sessions.

C’est le mécanisme le plus récent et le plus inhabituel. Contrairement aux cinq autres niveaux où c’est vous qui écrivez le contenu, l’auto memory contient des notes que Claude rédige de sa propre initiative, basées sur ce qu’il découvre en travaillant sur votre projet.

Le répertoire contient un fichier MEMORY.md (point d’entrée concis, chargé à chaque session) et des fichiers thématiques optionnels :

~/.claude/projects/<projet>/memory/
├── MEMORY.md          # Index concis, chargé systématiquement
├── debugging.md       # Notes sur les patterns de débogage
├── api-conventions.md # Conventions d'API découvertes
└── gotchas.md         # Pièges identifiés
Langage du code : Markdown (markdown)

Chaque projet obtient son propre répertoire de mémoire, dérivé de la racine du dépôt git. Tous les sous-répertoires d’un même dépôt partagent un seul répertoire d’auto memory. Les worktrees git obtiennent des répertoires séparés.

L’auto memory est en déploiement progressif. Si vous ne la voyez pas encore, vous pouvez l’activer avec CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 dans votre environnement.

⚠️ Attention : l’auto memory peut devenir verbeuse. Claude a tendance à prendre des notes abondantes, et le fichier MEMORY.md grossit sans élagage humain. Prévoyez des revues régulières pour supprimer les notes redondantes ou obsolètes : le même principe d’élagage que pour CLAUDE.md s’applique ici.

Vue d’ensemble : ce qui est chargé quand

L’économie de l’attention : chaque ligne a un prix

Le budget que personne ne compte

Voici un fait que la documentation officielle ne mentionne jamais : tout le contenu de CLAUDE.md est chargé dans le contexte de Claude Code à chaque session. Les mots que vous écrivez dans ce fichier sont des tokens qui seront présents dans chaque conversation, qu’ils soient pertinents ou non.

Claude Code utilise Opus 4.6 ou Sonnet 4.5, avec des fenêtres de contexte de 200 000 tokens. Sonnet peut atteindre un million de tokens en contexte étendu. On pourrait croire qu’avec autant d’espace, quelques centaines de lignes de CLAUDE.md sont insignifiantes. C’est une erreur.

Le problème n’est pas l’espace : c’est l’attention. Eyad Khrais, qui utilise Claude Code quotidiennement sur des systèmes de production, observe que le modèle ne peut suivre de manière fiable qu’environ 150 à 200 instructions simultanées, et que le prompt système de Claude Code en consomme déjà une cinquantaine. Chaque instruction que vous ajoutez dans CLAUDE.md entre en compétition avec les autres pour cette attention limitée.

Plus frappant encore : la dégradation de qualité ne commence pas à 100 % de la fenêtre de contexte. Elle commence entre 20 et 40 %, selon les observations convergentes de plusieurs développeurs. Si vous avez déjà vu Claude Code compacter le contexte (/compact) puis continuer à produire des résultats médiocres, c’est exactement ce phénomène : le modèle était déjà dégradé avant la compaction, et la compaction ne restaure pas magiquement la qualité.

Le « fading memory »

Un second phénomène, moins documenté mais observé de manière récurrente, est l’attention inégale au sein du fichier. Les instructions placées en début et en fin de CLAUDE.md sont mieux suivies que celles placées au milieu. C’est cohérent avec ce que l’on sait du comportement des transformers sur les longs contextes : le phénomène « lost in the middle » bien documenté dans la littérature de recherche.

Implication pratique : les instructions les plus critiques doivent être placées en tête du fichier. Les instructions importantes mais secondaires en fin. Le milieu est la zone de moindre attention.

Quantifier : combien de lignes avant la contre-productivité ?

Il n’existe pas de chiffre officiel d’Anthropic. Mais le consensus des power users converge :

• Moins de 60 lignes : c’est ce que pratique HumanLayer, et c’est le sweet spot pour les projets où la concision est prioritaire.
• Moins de 150 lignes : zone de confort pour la plupart des projets. Chaque instruction a de bonnes chances d’être suivie.
• Moins de 300 lignes : limite haute recommandée par la communauté. Au-delà, les retours indiquent une dégradation mesurable de l’adhérence.
• Au-delà de 300 lignes : vous écrivez de la documentation, pas un prompt. Déportez le surplus vers des .claude/rules/ scopées ou des fichiers references/ importés à la demande.

La règle empirique : si vous ne pouvez pas relire votre CLAUDE.md en moins de deux minutes, il est trop long.

Que mettre dedans, et surtout que ne PAS mettre

Le framework WHAT / WHY / HOW

Les développeurs de HumanLayer proposent un cadre simple pour structurer le contenu :

WHAT : Dire à Claude ce qu’est le projet : la stack technique, la structure du dépôt, les composants principaux. Donner une carte du codebase. C’est particulièrement important dans les monorepos : indiquer ce que sont les apps, les packages partagés, et à quoi sert chaque composant.

WHY : Dire à Claude le but de chaque partie du projet. Pas juste « voici un dossier auth/ », mais « le système d’authentification utilise des sessions Redis parce qu’on a eu des problèmes de scalabilité avec les JWT en production ».

HOW : Dire à Claude comment travailler sur le projet. Le gestionnaire de paquets utilisé, les commandes de build, de test, de lint, les workflows de vérification. Les informations nécessaires pour qu’il puisse faire un travail utile.

Ce qui a un rendement élevé

Les commandes fréquentes : c’est le contenu qui a le meilleur rapport coût/bénéfice. Quatre lignes qui évitent à Claude de chercher comment lancer les tests valent plus que quarante lignes d’architecture.

## Commandes
- `pnpm dev` : serveur de développement (port 3000)
- `pnpm build` : build de production
- `pnpm test` : tests unitaires (vitest)
- `pnpm test:e2e` : tests end-to-end (playwright)
- `pnpm lint` : ESLint + Prettier
- `pnpm db:migrate` : migrations Prisma
Langage du code : Markdown (markdown)

Les conventions non évidentes : ce que Claude ne peut pas deviner en lisant le code. Les choses bizarres, les choix contre-intuitifs, les pièges spécifiques.

## Conventions
- Les imports sont groupés : 1) React, 2) third-party, 3) locaux (@/*)
- On utilise Zustand pour le state management (pas Redux) — voir src/stores/
- Le webhook Stripe dans /app/api/webhooks/stripe DOIT valider les signatures
- Les images produit sont stockées sur Cloudinary, jamais localement
- IMPORTANT : Ne jamais committer de fichiers .env
Langage du code : Markdown (markdown)

Le « pourquoi » derrière les règles : Eyad Khrais insiste sur ce point avec raison. « Utilise TypeScript strict mode » est une instruction correcte. « Utilise TypeScript strict mode parce qu’on a eu des bugs en production liés à des types any implicites » est une instruction que Claude suivra mieux, parce que le contexte lui permet de faire des choix cohérents dans les cas que vous n’avez pas anticipés.

Ce que Claude ne doit PAS faire : les tendances du modèle qu’il faut contrer explicitement. Claude (particulièrement avec Opus 4.5 et 4.6) a une tendance documentée à la suringénierie : fichiers supplémentaires, abstractions non demandées, flexibilité dont personne n’a besoin.

## À ne PAS faire
- Ne pas créer d'abstractions non demandées
- Ne pas ajouter de fichiers au-delà de ce qui est strictement nécessaire
- Ne pas ajouter de dépendances sans approbation explicite
- Garder les solutions simples — un seul fichier si possible
- Ne pas commenter ce que le code fait (le rendre auto-documenté), seulement pourquoi
Langage du code : Markdown (markdown)

Ce qui a un rendement faible ou négatif

Les explications de ce que Claude sait déjà : ne pas expliquer ce qu’est un composant React, comment fonctionne un import ES module, ou ce que fait un try/catch. Claude le sait. Chaque ligne qui explique l’évident dilue l’attention portée aux lignes qui comptent.

Les instructions vagues : « Formate le code correctement » ne veut rien dire. « Utilise une indentation de 2 espaces, des guillemets simples, et un point-virgule en fin de ligne » est actionnable. L’article d’Anthropic sur les best practices recommande d’être aussi spécifique que possible.

Les instructions conditionnelles trop spécifiques : « Quand tu crées un nouveau schéma de base de données, utilise toujours des UUID v7 comme clés primaires et ajoute les colonnes created_at et updated_at. » Cette instruction est pertinente peut-être 2 % du temps. Les 98 % restants, elle consomme du budget d’attention pour rien. Déplacez-la dans un fichier .claude/rules/database.md scopé aux fichiers de migration.

Les arborescences complètes du projet : c’est la tentation classique. Reproduire toute l’arborescence dans le CLAUDE.md pour « donner une carte à Claude ». Le problème : Claude peut exécuter find, ls, tree par lui-même. Une arborescence statique dans le fichier prend de la place, devient obsolète dès que la structure évolue, et documente des chemins qui changent constamment. Préférez une description sémantique : « les composants partagés vivent dans src/components/ui/, le state management dans src/stores/, les routes API dans src/app/api/ ».

Les templates et exemples exhaustifs : si vous avez besoin que Claude suive un template spécifique pour les composants ou les routes API, mettez le template dans un fichier séparé et référencez-le : « Pour les conventions de composants React, voir @docs/component-template.md ». Ne collez pas le template dans CLAUDE.md.

La technique du prompt improver

Anthropic recommande officieusement, dans son article sur les best practices, de passer les fichiers CLAUDE.md dans leur propre prompt improver. L’outil reformule et structure les instructions pour maximiser l’adhérence du modèle. C’est un aveu pragmatique : le contenu de CLAUDE.md est un prompt, et il mérite le même soin que n’importe quel prompt de production.

Concrètement, cela signifie :

• Utiliser des verbes impératifs plutôt que des suggestions (« Utilise » vs « Tu pourrais utiliser »)
• Ajouter des emphases sur les règles critiques (« IMPORTANT », « YOU MUST », « JAMAIS »)
• Tester l’adhérence en lançant plusieurs sessions avec les mêmes tâches et en vérifiant la cohérence des résultats

Patterns d’architecture pour projets réels

Pattern 1 : Projet solo

La configuration la plus simple. Un seul fichier CLAUDE.md à la racine, court et focalisé.

mon-projet/
├── CLAUDE.md           # Tout est ici, < 100 lignes
├── CLAUDE.local.md     # Mes URLs perso, tokens de test (gitignored)
├── src/
└── package.json
Langage du code : Markdown (markdown)

Le CLAUDE.md importe le README pour le contexte projet sans le dupliquer :

Voir @README.md pour la vue d'ensemble du projet et @package.json pour les commandes npm.

## Commandes
- `npm run dev` : serveur de dev (port 3000)
- `npm test` : vitest
- `npm run lint` : ESLint

## Conventions
- TypeScript strict, pas de type `any`
- Exports nommés, jamais de default exports
- Tailwind pour le style, pas de fichiers CSS séparés
- Composants fonctionnels avec hooks

## Important
- NE JAMAIS committer de fichiers .env
- Le handler de webhook Stripe dans /app/api/webhooks/stripe doit valider les signatures
Langage du code : Markdown (markdown)

Pattern 2 : Monorepo d’équipe

La configuration qui exploite pleinement la hiérarchie et les rules scopées.

monorepo/
├── CLAUDE.md                    # Conventions globales (commandes, git, CI)
├── .claude/
│   └── rules/
│       ├── frontend/
│       │   ├── react.md         # Règles React (paths: src/apps/web/**)
│       │   └── styles.md        # Règles Tailwind (paths: **/*.css, **/*.tsx)
│       ├── backend/
│       │   ├── api.md           # Règles FastAPI (paths: src/api/**)
│       │   └── database.md      # Règles Prisma (paths: prisma/**)
│       └── testing.md           # Règles de test (sans paths = global)
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Spécificités de l'app web
│   └── admin/
│       └── CLAUDE.md            # Spécificités du dashboard admin
├── packages/
│   ├── ui/
│   │   └── CLAUDE.md            # Conventions du design system
│   └── core/
└── package.json
Langage du code : Markdown (markdown)

Le CLAUDE.md racine ne contient que ce qui est universel :

# Monorepo Acme

Plateforme SaaS : app web (Next.js), API (FastAPI), packages partagés.

## Commandes globales
- `pnpm install` : installer les dépendances (tous les packages)
- `pnpm turbo run build` : build complet
- `pnpm turbo run test` : tests complets
- `pnpm turbo run lint` : lint complet

## Git
- Branches : feat/xxx, fix/xxx, refactor/xxx
- Commits conventionnels : feat:, fix:, refactor:, docs:, test:
- Toujours créer une PR, jamais de push direct sur main
- Les PR doivent passer le CI avant merge

## Architecture
- apps/web : app client Next.js (port 3000)
- apps/admin : dashboard admin Next.js (port 3001)
- packages/ui : composants React partagés (Radix + Tailwind)
- packages/core : logique métier pure, zéro dépendance externe
- src/api : API FastAPI (port 4000)

## Règles critiques
- IMPORTANT : l'accès base de données passe UNIQUEMENT par les repositories de packages/db
- JAMAIS de Prisma brut dans les apps
- Les types partagés vivent dans packages/core/types
Langage du code : Markdown (markdown)

Et le CLAUDE.md de apps/web/ ne contient que ce qui est spécifique :

# App Web (Next.js 15)

Voir @../../CLAUDE.md pour les conventions globales.

## Commandes locales
- `pnpm dev --filter web` : serveur de dev
- `pnpm test --filter web` : tests vitest
- `pnpm build --filter web` : build Next.js

## Spécificités
- App Router (pas Pages Router)
- Les Server Components sont le défaut, marquer explicitement "use client"
- Les URL params dans les pages sont des promesses et doivent être await
- Tout le contenu visible utilise les composants de @acme/ui
Langage du code : Markdown (markdown)

Pattern 3 : Projet open source

Le cas particulier où le CLAUDE.md doit servir à la fois aux contributeurs qui utilisent Claude Code et au mainteneur.

# Browser Use — Framework d'automatisation de navigateur

Monorepo Python/Next.js. Voir @README.md pour la présentation du projet.

## Structure
- browser-use/ : bibliothèque Python core
- cloud/ : plateforme cloud (FastAPI backend + Next.js frontend)

## Tests
- Utiliser de vrais objets, pas de mocks (sauf pour le LLM → browser-use/tests/ci/mocks.py)
- Utiliser pytest-httpserver via fixtures pour servir du HTML, JAMAIS d'URLs live
- Pas besoin de @pytest.mark.asyncio (configuré en mode auto dans pyproject.toml)
- Regrouper les tests d'un même composant dans un seul fichier
- Toujours exécuter les tests avec un timeout pour éviter les deadlocks
- Après un travail, passer en revue les tests et supprimer les doublons

## Workflow de contribution
- Vérifier les tests/, examples/ et docs/ existants avant de coder
- Commiter avec des messages conventionnels
- Une PR par fonctionnalité
Langage du code : Markdown (markdown)

Ce fichier est inspiré du CLAUDE.md réel du projet browser-use, et il illustre une bonne pratique : les instructions sont concentrées sur les choses non évidentes (le mode auto d’asyncio, l’interdiction des URLs live dans les tests, le regroupement des tests) plutôt que sur des banalités.

Pattern 4 : Mémoire externe inter-sessions

Ce pattern n’est pas à proprement parler un CLAUDE.md, mais il complète le système de mémoire. Eyad Khrais utilise un fichier SCRATCHPAD.md ou plan.md pour les projets complexes qui s’étalent sur plusieurs sessions.

L’idée : quand vous terminez une session de travail, demandez à Claude d’écrire un résumé de l’état actuel dans un fichier dédié. Quand vous reprenez le lendemain, Claude lit ce fichier et reprend là où il s’est arrêté, au lieu de repartir de zéro.

# Plan de migration — Sprint 3

## État actuel (mis à jour le 2026-02-21)
- ✅ Migration du schéma utilisateurs terminée
- ✅ Tests de la nouvelle API auth passent (47/47)
- ð En cours : migration des données historiques (script dans scripts/migrate-history.py)
- ⏳ Reste à faire : mise à jour des webhooks Stripe, tests d'intégration e2e

## Décisions prises
- UUID v7 pour toutes les nouvelles tables (performance de tri)
- Sessions Redis avec expiry 24h (pas JWT — voir discussion dans PR #234)
- Rollback possible via script scripts/rollback-v2.py

## Prochaine étape
Terminer le script de migration historique, puis lancer les tests e2e complets.
Langage du code : Markdown (markdown)

Ce fichier n’est pas dans CLAUDE.md : il est référencé quand nécessaire : « Lis @SCRATCHPAD.md et continue à partir de l’état actuel ». C’est de la mémoire à la demande, pas de la mémoire permanente.

Un CLAUDE.md complet commenté

Voici un fichier réaliste pour un projet de taille moyenne (une app Next.js avec API), annoté avec le raisonnement derrière chaque section.

# Plateforme FinTrack

App de suivi financier personnel. Next.js 15 (App Router) + FastAPI + PostgreSQL.

## Commandes
# [RENDEMENT ÉLEVÉ — évite des dizaines de recherches par session]
- `pnpm dev` : serveur Next.js (port 3000) + API FastAPI (port 4000)
- `pnpm test` : vitest (frontend) + pytest (backend)
- `pnpm test:e2e` : playwright
- `pnpm lint` : ESLint + ruff
- `pnpm db:migrate` : alembic upgrade head
- `pnpm db:seed` : python scripts/seed.py

## Architecture
# [RENDEMENT ÉLEVÉ — la carte du projet en 8 lignes]
- src/app/ : pages et layouts Next.js (App Router)
- src/components/ui/ : composants réutilisables (shadcn/ui)
- src/lib/ : utilitaires et logique partagée
- src/stores/ : state management (Zustand, pas Redux)
- api/ : routes FastAPI
- api/models/ : modèles SQLAlchemy
- api/schemas/ : schémas Pydantic (validation entrée/sortie)
- prisma/ : schéma Prisma pour les migrations

## Conventions de code
# [RENDEMENT ÉLEVÉ — les choses non évidentes]
- TypeScript strict, aucun type `any` — parce qu'on a eu des bugs en prod
- Exports nommés uniquement, jamais de default exports
- Composants fonctionnels + hooks, jamais de classes
- Tailwind pour le style, pas de fichiers CSS séparés
- Tout le contenu utilisateur est en français

## Règles critiques
# [RENDEMENT ÉLEVÉ — ce qui casse si c'est ignoré]
- IMPORTANT : NE JAMAIS committer de fichiers .env
- IMPORTANT : Le webhook Stripe (/api/webhooks/stripe) DOIT valider les signatures
- IMPORTANT : Toute modification de schéma DB nécessite une migration Alembic
- Les montants financiers sont stockés en centimes (integer), JAMAIS en float

## Ce que tu ne dois PAS faire
# [RENDEMENT ÉLEVÉ — contrer les tendances du modèle]
- Ne pas créer d'abstractions non demandées
- Ne pas ajouter de fichiers au-delà du strict nécessaire
- Ne pas installer de nouvelles dépendances sans approbation
- Ne pas commenter ce que le code fait, seulement pourquoi
- Ne pas utiliser de mocks dans les tests sauf pour les appels API externes

## Git
- Branches : feat/xxx, fix/xxx, refactor/xxx
- Commits conventionnels (feat:, fix:, refactor:, docs:, test:)
- Toujours créer une PR, jamais de push direct sur main

## Contexte additionnel
- Pour le flux d'authentification : voir @docs/authentication.md
- Pour les conventions de composants : voir @docs/component-guide.md
Langage du code : Markdown (markdown)

Total : ~50 lignes. Chaque section justifie sa présence. Les instructions spécifiques au frontend ou au backend qui ne sont pas universelles vivent dans .claude/rules/, pas ici.

Ce qu’il faut noter :

• Les commandes sont en premier : c’est ce que Claude utilise le plus souvent, et c’est en tête du fichier (zone de forte attention).
• L’architecture est sémantique, pas structurelle : pas d’arborescence tree, juste la signification de chaque dossier.
• Le « pourquoi » est inclus quand il change le comportement attendu (TypeScript strict parce que des bugs en prod, centimes parce que jamais de float pour les montants).
• Les références externes utilisent @ : Claude charge ces fichiers à la demande, pas systématiquement.
• Les emphases sont réservées aux règles critiques : si tout est « IMPORTANT », rien ne l’est.

Tester votre propre seuil d’adhérence

Les chiffres de 150–300 lignes sont des repères communautaires, pas des lois universelles. Votre projet, votre stack et votre style d’instructions produiront un seuil différent. Voici un protocole empirique en quatre étapes pour le trouver.

Étape 1 : Baseline. Préparez 5 tâches représentatives de votre travail quotidien (un refactor, un nouveau composant, un fix de bug, un test, une review de code). Lancez chaque tâche dans une session fraîche avec votre CLAUDE.md actuel. Notez le taux d’adhérence : sur les instructions clés, combien sont respectées sans correction manuelle ?

Étape 2 : Surcharge contrôlée. Dupliquez le fichier et ajoutez 50 lignes de contenu réaliste mais secondaire (conventions supplémentaires, cas d’usage rares). Relancez les mêmes 5 tâches. Comparez.

Étape 3 : Élagage agressif. Réduisez le fichier au strict minimum : commandes, conventions critiques, interdictions. Visez 40–60 lignes. Relancez. Comparez.

Étape 4 : Ajustement. Réintroduisez progressivement les instructions retirées, par ordre de priorité, en testant après chaque ajout. Le point où l’adhérence commence à baisser est votre seuil personnel.

Ce protocole prend une heure. Il vous évitera des semaines de corrections récurrentes.

Workflow multi-modèles : CLAUDE.md comme colonne vertébrale

Si vous utilisez plusieurs modèles dans votre stack IA, CLAUDE.md joue un rôle central que la documentation officielle ne mentionne pas : c’est le socle commun entre les modèles.

Le pattern le plus courant dans les équipes avancées est le tandem Opus pour la planification, Sonnet pour l’exécution. Opus (plus lent, plus cher, plus intelligent) reçoit le CLAUDE.md et produit un plan détaillé dans un fichier SCRATCHPAD.md ou plan.md. Sonnet (plus rapide, moins cher) exécute chaque étape du plan en s’appuyant sur le même CLAUDE.md pour respecter les conventions.

Dans ce workflow, CLAUDE.md devient le contrat partagé entre les deux modèles. C’est ce qui garantit que Sonnet produit du code cohérent avec les décisions architecturales prises par Opus. Sans CLAUDE.md, chaque switch de modèle recommence à zéro.

Concrètement, cela implique que les instructions dans CLAUDE.md doivent être compréhensibles par les deux modèles, sans contexte implicite lié aux capacités spécifiques de l’un ou l’autre. Évitez les instructions qui s’appuient sur la capacité de raisonnement avancé d’Opus : Sonnet doit pouvoir les suivre aussi.

Sécurité : ce que CLAUDE.md ne doit jamais contenir

Un point que la documentation officielle mentionne à peine mais qui mérite une section dédiée : CLAUDE.md est un fichier versionné, souvent public, et les LLM ont des vulnérabilités connues que votre fichier ne doit pas aggraver.

Jamais de secrets dans CLAUDE.md. Pas de clés API, pas de tokens, pas de mots de passe, pas d’URLs internes sensibles. Le fichier est commité dans le dépôt et lisible par quiconque a accès au code. Les secrets passent par des variables d’environnement, référencées dans CLAUDE.md sous forme de placeholders :

## Configuration
- API Stripe : utiliser la variable d'environnement $STRIPE_SECRET_KEY
- Base de données : connection string dans $DATABASE_URL
- Ne JAMAIS hardcoder de credentials
Langage du code : Markdown (markdown)

Les données personnelles dans CLAUDE.local.md. Vos URLs de sandbox, vos identifiants de test, vos préférences personnelles vont dans CLAUDE.local.md, qui est automatiquement gitignored.

Pas d’instructions de contournement. Ne mettez pas dans CLAUDE.md des instructions qui désactivent des protections du modèle ou qui encouragent des raccourcis de sécurité. Claude Code a ses propres garde-fous ; votre fichier doit les compléter, pas les contourner.

Le cycle de vie : créer, itérer, élaguer

Bootstrapper avec /init

La commande /init dans Claude Code génère automatiquement un CLAUDE.md basé sur l’analyse de votre projet : stack détectée, commandes trouvées dans package.json ou Makefile, structure de dossiers.

Le fichier généré est un point de départ, pas un produit fini. La recommandation pragmatique : partir de /init et supprimer plutôt que d’écrire from scratch. Supprimer est plus facile que créer, et le fichier généré inclut souvent des évidences (« ce projet utilise TypeScript ») qui diluent l’attention sans rien apporter.

Ajouter au fil de l’eau avec #

Pendant une session de travail, quand vous corrigez Claude sur quelque chose ou que vous identifiez une convention importante, tapez # suivi de l’instruction. Claude Code l’ajoutera automatiquement au CLAUDE.md approprié.

# Toujours utiliser pnpm, jamais npm ou yarn
# Les tests d'intégration nécessitent Docker running
# Les fichiers de migration doivent être nommés YYYYMMDD_description.py
Langage du code : Markdown (markdown)

Note importante : le raccourci # a été ajouté puis retiré puis ré-ajouté au fil des versions de Claude Code. Selon votre version, il peut être disponible directement ou via la commande /memory. Vérifiez avec votre version actuelle.

La règle des deux corrections

C’est la règle d’Eyad Khrais, et elle est d’une efficacité redoutable dans sa simplicité : si vous corrigez Claude deux fois sur le même point, cette correction doit aller dans CLAUDE.md. Point final.

La première correction peut être un malentendu ponctuel. La deuxième est un pattern. Et si vous ne l’inscrivez pas, vous le corrigerez une troisième fois, une quatrième, à chaque nouvelle session.

Éditer avec /memory

La commande /memory ouvre le fichier dans votre éditeur système pour des modifications plus substantielles : réorganisation, élagage, ajout de sections.

Élaguer : le corollaire oublié

Un CLAUDE.md qui ne fait que grossir finit par se retourner contre vous. L’élagage est aussi important que l’ajout. Planifiez une revue périodique (mensuelle, ou à chaque sprint) :

• Supprimer les instructions devenues obsolètes (dépendance retirée, convention abandonnée)
• Fusionner les instructions redondantes
• Déplacer les instructions conditionnelles vers des .claude/rules/ scopées
• Vérifier que le fichier tient toujours sous la barre des 150-300 lignes

Versionner en PR

Traitez CLAUDE.md comme du code, pas comme des notes. Incluez les modifications dans les PR, faites-les relire par l’équipe, discutez des ajouts. Un CLAUDE.md écrit par plusieurs personnes sans coordination accumule des instructions contradictoires, et Claude ne résout pas les contradictions de manière prévisible.

Une pratique observée dans les équipes qui utilisent le GitHub Action de Claude Code : tagger @claude dans les commentaires de PR pour lui demander de mettre à jour le CLAUDE.md directement. « @claude ajoute au CLAUDE.md : ne jamais utiliser d’enums TypeScript, toujours préférer les unions de littéraux string. » Claude met à jour le fichier et commite le changement dans la PR.

Dépannage

« Claude ignore mes instructions »

C’est le problème le plus fréquent, et les causes sont multiples.

Le fichier est trop long. C’est la cause numéro un. Au-delà de 300 lignes, l’adhérence chute. Rappelez-vous le system-reminder injecté par Claude Code : le modèle est explicitement autorisé à ignorer le contenu qu’il juge non pertinent. Plus le fichier est long, plus il y a de contenu « non pertinent » aux yeux du modèle, et plus le filtrage est agressif.

Les instructions sont vagues. « Écris du code propre » sera ignoré. « Indentation 2 espaces, guillemets simples, point-virgule en fin de ligne, exports nommés uniquement » sera suivi.

Le fichier n’est pas au bon endroit. Claude Code cherche CLAUDE.md dans le répertoire courant et ses parents. Si vous lancez Claude Code depuis un sous-répertoire et que le fichier est à la racine du dépôt, il sera trouvé. Mais si vous lancez depuis un répertoire en dehors du dépôt, il ne le trouvera pas. Vérifiez avec /memory quels fichiers sont effectivement chargés.

Les instructions se contredisent entre niveaux. Si votre ~/.claude/CLAUDE.md dit « utilise des tabs » et que le projet dit « utilise des espaces », Claude reçoit les deux instructions. Le comportement n’est pas garanti. Vérifiez la cohérence entre les niveaux.

Solution universelle : demandez à Claude « Quand utiliserais-tu l’instruction X de mon CLAUDE.md ? ». Claude citera l’instruction en retour, et vous verrez si sa compréhension correspond à votre intention. Ajustez en fonction.

/compact ne résout pas les problèmes de contexte

Le réflexe quand Claude donne des résultats médiocres est de compacter le contexte. Mais comme le note Eyad Khrais, si la qualité a commencé à se dégrader à 30 % du contexte, compacter à 30 % ne restaure pas la qualité perdue.

La meilleure approche est le « copy-paste reset » : copiez les informations importantes de la session, faites /clear pour un contexte vierge, puis recollez uniquement ce qui est nécessaire. C’est brutal mais efficace. Claude aura toujours votre CLAUDE.md, donc le contexte projet est préservé.

La Skill ne se déclenche pas alors que CLAUDE.md fonctionne

CLAUDE.md et les Skills sont deux systèmes distincts. Un CLAUDE.md qui fonctionne ne garantit pas que les Skills se déclenchent correctement. Si vous avez des instructions dans CLAUDE.md qui devraient être dans une Skill (ou inversement), consultez mon guide sur les Skills pour la démarcation.

Checklist de validation

Avant de commencer

• [ ] Vous avez identifié les 5-10 commandes les plus fréquentes du projet
• [ ] Vous connaissez les conventions non évidentes (ce que Claude ne peut pas deviner)
• [ ] Vous avez listé les pièges spécifiques au projet
• [ ] Vous avez décidé ce qui est universel (→ CLAUDE.md) vs conditionnel (→ rules/)

Pendant la rédaction

• [ ] Le fichier fait moins de 150 lignes (idéal) ou 300 lignes (maximum)
• [ ] Les commandes fréquentes sont en premier (zone de forte attention)
• [ ] Chaque instruction est spécifique et actionnable
• [ ] Le « pourquoi » est inclus pour les règles non évidentes
• [ ] Les instructions négatives (« ne pas faire ») sont présentes
• [ ] Les emphases (IMPORTANT, JAMAIS) sont réservées aux points critiques
• [ ] Aucune arborescence complète tree : descriptions sémantiques uniquement
• [ ] Les templates et docs détaillés sont dans des fichiers séparés, référencés avec @
• [ ] Pas d’explication de concepts que Claude connaît déjà

Après la mise en place

• [ ] Testé sur 3-5 tâches courantes : Claude suit-il les instructions ?
• [ ] Vérifié avec /memory que les bons fichiers sont chargés
• [ ] Le fichier est versionné et passé en revue en PR
• [ ] CLAUDE.local.md existe pour les préférences personnelles (gitignored)
• [ ] Les instructions spécifiques à certains fichiers sont dans .claude/rules/
• [ ] Un processus d’élagage périodique est prévu

Signaux d’alerte

• [ ] Vous corrigez Claude deux fois sur le même point → ajouter au CLAUDE.md
• [ ] Claude ignore une instruction → vérifier la longueur du fichier et la spécificité
• [ ] Les résultats varient entre les membres de l’équipe → vérifier la cohérence entre niveaux
• [ ] Le fichier dépasse 300 lignes → élaguer et déporter vers rules/

Le mot de la fin

Il y a quelque chose de presque comique dans le fait que le levier le plus puissant de Claude Code soit un fichier texte. Pas de SDK. Pas d’API. Pas de configuration YAML complexe. Un fichier Markdown, avec des bullet points et des titres de niveau 2.

Mais c’est précisément cette simplicité qui en fait un outil si mal utilisé. Parce qu’il ressemble à de la documentation, on le traite comme de la documentation. On y écrit des paragraphes explicatifs, des arborescences exhaustives, des guides d’onboarding pour développeurs juniors. On oublie que derrière cette surface familière, il y a un mécanisme d’injection de contexte qui consomme des tokens, qui est explicitement filtrable par le modèle, et dont l’efficacité décroît avec la longueur.

Le bon CLAUDE.md est celui que vous n’avez pas besoin de lire pour savoir s’il fonctionne : vous le voyez dans la qualité des résultats de Claude. Il est court parce que chaque ligne a mérité sa place. Il est précis parce que la précision est ce qui survit au filtre d’attention. Il évolue parce que votre projet évolue, et qu’un prompt figé face à un projet vivant finit toujours par dériver.

Si vous ne retenez qu’une seule chose de cet article, que ce soit celle-ci : CLAUDE.md n’est pas un fichier de documentation. C’est le prompt le plus important que vous n’écrirez jamais qu’une seule fois, et comme tout prompt, il mérite d’être testé, itéré et élagué avec la même rigueur que votre code.

Ressources

• Documentation officielle : Manage Claude’s memory (doc principale), Claude Code Best Practices (article engineering blog Anthropic), Claude Code Settings (hiérarchie et configuration)
• Retours de terrain : How Anthropic teams use Claude Code (PDF interne Anthropic), Writing a good CLAUDE.md (HumanLayer, découverte du system-reminder), How to Write a Good CLAUDE.md File (Builder.io)
• Exemples publics : CLAUDE.md monorepo browser-use, Template monorepo SaaS, CLAUDE.md Next.js minimaliste
• Standard ouvert AGENTS.md : agents.md (site officiel), What Great CLAUDE.md Files Have in Common (analyse comparative)
• Mes articles précédents : Guide complet du fichier SKILL.md, Ma stack IA en 2026, Comment les IA lisent le web, Anthropic et Claude Code : avis de liquidation, Les LLM sont des gruyères