Accueil › Claude Code › CLAUDE.md

CLAUDE.md : le fichier qui rend Claude Code réellement utile

CLAUDE.md est un fichier Markdown à la racine de votre projet que Claude Code lit automatiquement à chaque session. Il donne à l’agent le contexte persistant qu’il ne peut pas déduire du code seul : commandes, conventions, architecture et workflows.

Sans CLAUDE.md, chaque session Claude Code démarre avec zéro mémoire. L’agent ne connaît pas vos conventions de code, ne sait pas comment lancer vos tests, ignore vos patterns architecturaux et ne connaît pas les workarounds spécifiques à votre projet. Vous finissez par répéter les mêmes instructions à chaque conversation.

Avec un CLAUDE.md bien structuré, l’agent applique automatiquement vos standards, utilise les bonnes commandes et produit du code cohérent avec votre codebase existante. C’est l’investissement le plus rentable que vous puissiez faire dans votre workflow Claude Code.

Pourquoi CLAUDE.md est indispensable

Claude Code charge CLAUDE.md dans le contexte de chaque session. C’est une injection de contexte permanente, pas de la documentation. Chaque ligne consomme du budget de fenêtre de contexte qui pourrait servir pour votre code. C’est pourquoi la concision est critique.

Les modèles de langage comme Claude Opus 4.6 ou Sonnet 4.6 peuvent suivre environ 150 à 200 instructions avec une cohérence raisonnable. Le system prompt de Claude Code en contient déjà environ 50. Cela signifie que votre CLAUDE.md dispose d’un budget effectif de 100 à 150 instructions. Au-delà, la qualité du suivi d’instructions se dégrade uniformément : l’agent n’ignore pas les nouvelles instructions, il commence à ignorer toutes les instructions de façon aléatoire.

La règle d’or : chaque ligne doit gagner sa place. Si vous retirez une instruction et que Claude produit toujours du bon code, supprimez-la.

Démarrer avec /init

La façon la plus rapide de créer un CLAUDE.md est d’utiliser la commande /init dans une session Claude Code :

cd ~/mon-projet
claude
/init

Claude Code analyse votre codebase : il détecte le système de build, le framework de tests, les patterns de code et la structure du projet. Il génère un fichier CLAUDE.md de base que vous affinerez ensuite.

Vous pouvez aussi utiliser /init sur un projet qui a déjà un CLAUDE.md. Claude review le fichier existant et suggère des améliorations basées sur ce qu’il découvre dans le code.

Structure recommandée

Les CLAUDE.md les plus efficaces suivent un pattern WHY/WHAT/HOW qui reflète la façon dont on brieferait un développeur senior rejoignant l’équipe :

# Nom du projet

Description en 1-2 lignes de ce que fait le projet.

## Stack
- TypeScript strict, React 19, Next.js 15 (App Router)
- Prisma + PostgreSQL
- Tailwind CSS + shadcn/ui
- Tests : Vitest + Testing Library

## Commandes
- `npm run dev` : serveur de développement (port 3000)
- `npm run test` : lancer les tests Vitest
- `npm run test:e2e` : tests end-to-end Playwright
- `npm run lint` : vérification ESLint
- `npm run build` : build de production
- `npm run db:migrate` : migrations Prisma

## Architecture
- /app : pages et layouts Next.js App Router
- /components/ui : composants réutilisables
- /lib : utilitaires et logique partagée
- /prisma : schéma et migrations
- /app/api : routes API

## Conventions
- Composants fonctionnels uniquement, pas de classes
- Exports nommés (pas de default export)
- Tailwind utilities, pas de CSS custom
- Pas de `any` en TypeScript (utiliser unknown)

## Points critiques
- Ne JAMAIS committer de fichiers .env
- Le webhook Stripe dans /app/api/webhooks/stripe
  doit valider les signatures
- Images stockées sur Cloudinary, pas en local

Ce fichier fait environ 35 lignes. Claude le traite efficacement parce qu’il est organisé avec des headings clairs, des listes à puces pour la scannabilité, et des commandes spécifiques plutôt que des instructions vagues.

Que mettre dans CLAUDE.md

Ce qui doit y figurer

Commandes de build/test/lint. C’est la priorité absolue. N’importe quel développeur (humain ou IA) devrait pouvoir lancer claude, taper « run the tests » et obtenir un résultat correct du premier coup. Si ce n’est pas le cas, votre CLAUDE.md manque des commandes essentielles.

Architecture de haut niveau. La structure des dossiers et ce que chaque dossier contient. L’agent peut scanner les fichiers, mais un résumé de 5 lignes lui évite de parcourir des dizaines de fichiers pour comprendre l’organisation.

Points critiques et pièges. Les choses que l’agent ne peut absolument pas deviner : fichiers à ne pas toucher, workarounds techniques, contraintes de sécurité, dépendances entre modules non évidentes.

Workflows spécifiques. Conventions de nommage de branches, process de déploiement, exigences de code review. Tout ce qui est propre à votre équipe et non inférable du code.

Instructions de compaction. Quand le contexte est automatiquement résumé, certaines informations peuvent être perdues. Ajoutez « When compacting, always preserve the full list of modified files and any test commands » pour que les données critiques survivent à la compaction.

Ce qui ne doit PAS y figurer

Règles de style de code détaillées. N’envoyez jamais un LLM faire le travail d’un linter. Les LLM sont lents et coûteux comparés aux formatters déterministes. Configurez Prettier, ESLint ou Biome pour le style, et laissez CLAUDE.md se concentrer sur les décisions de design que les outils automatiques ne peuvent pas prendre.

Documentation complète du projet. CLAUDE.md n’est pas un wiki. C’est un fichier d’injection de contexte. Si vous avez besoin de documentation détaillée pour certains domaines, déplacez-la dans des fichiers séparés et référencez-les.

Instructions conditionnelles rares. Une instruction sur la structure des schémas de base de données sera inutile (et distraira le modèle) quand vous travaillez sur du CSS frontend. Déplacez les instructions spécifiques à un domaine dans .claude/rules/.

Ce que Claude fait déjà correctement sans instruction. Les LLM apprennent du contexte. Si votre code suit des patterns cohérents, Claude les détectera naturellement via la recherche dans la codebase. Ne réécrivez pas dans CLAUDE.md ce que le code montre déjà.

Organisation multi-fichiers

Pour les projets complexes, un seul CLAUDE.md peut devenir trop volumineux. Deux approches complémentaires permettent de découper les instructions :

Le répertoire .claude/rules/

Placez des fichiers Markdown dans .claude/rules/. Ils sont automatiquement chargés avec la même priorité que CLAUDE.md, sans besoin d’imports explicites.

mon-projet/
├── CLAUDE.md                    # Instructions essentielles
├── .claude/
│   └── rules/
│       ├── code-style.md        # Conventions de code
│       ├── testing.md           # Conventions de tests
│       └── security.md          # Exigences de sécurité

Cette approche fonctionne bien quand différents membres de l’équipe maintiennent différents fichiers de règles. L’équipe frontend gère code-style.md, l’équipe sécurité gère security.md.

CLAUDE.md dans un monorepo

Claude Code supporte un chargement hiérarchique : il lit le CLAUDE.md parent (racine du monorepo) puis le CLAUDE.md du sous-répertoire dans lequel vous travaillez. Cela permet d’avoir des instructions globales et des instructions spécifiques par package :

monorepo/
├── CLAUDE.md                    # Instructions globales
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # Instructions spécifiques frontend
│   ├── backend/
│   │   └── CLAUDE.md            # Instructions spécifiques backend
│   └── shared/
│       └── CLAUDE.md            # Instructions librairie partagée

Faire évoluer CLAUDE.md dans le temps

Le fichier CLAUDE.md n’est pas un one-shot. C’est un document vivant qui évolue avec votre projet. Voici les bonnes pratiques de maintenance :

Utilisez le raccourci #. Pendant une session Claude Code, appuyez sur # pour ajouter rapidement une instruction que vous vous retrouvez à répéter. Ces ajouts s’accumulent dans un CLAUDE.md qui reflète réellement la façon dont votre équipe travaille.

Commitez dans Git. CLAUDE.md doit être versionné avec le code. Toute l’équipe en bénéficie, et les changements sont traçables.

Auditez régulièrement. Une fois par mois, relisez le fichier et supprimez les instructions obsolètes. Les frameworks évoluent, les conventions changent, et un CLAUDE.md accumulant des instructions contradictoires est pire qu’aucun fichier.

Testez la suppression. Pour chaque instruction, demandez-vous « Si je retire cette ligne, est-ce que Claude fera des erreurs ? » Si la réponse est non, supprimez-la. Moins de bruit signifie un meilleur suivi des instructions restantes.

CLAUDE.md vs Cursor Rules

Si vous utilisez aussi Cursor, la comparaison avec les Cursor Rules est pertinente :

Les deux approches servent le même objectif (donner du contexte persistant à l’agent IA) avec des mécanismes légèrement différents. Si vous utilisez les deux outils, maintenez les deux fichiers synchronisés ou utilisez un script qui génère l’un à partir de l’autre.

Exemples concrets par type de projet

Projet Next.js fullstack

# ShopFront
E-commerce Next.js 15 App Router, Stripe, Prisma.

## Commandes
- `npm run dev` : dev server (port 3000)
- `npm run test` : Vitest
- `npm run test:e2e` : Playwright
- `npm run lint` : ESLint
- `npm run db:migrate` : Prisma migrate

## Architecture
- /app : pages App Router
- /app/api : routes API
- /components/ui : shadcn/ui
- /lib : utilitaires
- /prisma : schéma + migrations

## Conventions
- Server Components par défaut, "use client" seulement si nécessaire
- Zod pour la validation des inputs API
- Zustand pour l'état client

## Critique
- Webhook Stripe : toujours valider la signature
- Images sur Cloudinary, jamais en local
- Ne pas committer .env*

API Python FastAPI

# Inventory API
API REST FastAPI pour la gestion d'inventaire.

## Commandes
- `uvicorn app.main:app --reload` : dev server
- `pytest` : tests
- `pytest --cov` : couverture
- `alembic upgrade head` : migrations DB
- `ruff check .` : linting

## Architecture
- /app/api/v1 : routes versionnées
- /app/models : modèles SQLAlchemy
- /app/schemas : schémas Pydantic
- /app/services : logique métier
- /app/core : config, sécurité, deps

## Conventions
- Dependency injection via Depends()
- Async partout (pas de sync DB)
- Chaque endpoint a un schéma request + response
- Erreurs via HTTPException avec codes standards

Monorepo TypeScript (Turborepo)

# Platform
Monorepo Turborepo : web (Next.js), api (Express), shared.

## Commandes globales
- `turbo run build` : build tous les packages
- `turbo run test` : tests tous les packages
- `turbo run lint` : lint tous les packages

## Packages
- packages/web : frontend Next.js 15
- packages/api : backend Express + tRPC
- packages/shared : types, utils, validations Zod
- packages/config : configs ESLint, TypeScript, Tailwind

## Conventions
- Types partagés dans packages/shared/types
- Imports cross-package via @platform/shared
- Pas de duplication de types entre packages
- PR doit passer turbo run build + test avant merge

Techniques avancées

Tags conditionnels pour les instructions critiques

Si votre CLAUDE.md commence à dépasser 100 lignes, les instructions les plus importantes risquent d’être noyées. Une technique efficace est d’utiliser des tags <important> pour signaler les règles que l’agent ne doit jamais ignorer :

<important>
Ne JAMAIS modifier les fichiers dans /core/auth/ sans
exécuter la suite de tests complète après. Les changements
dans ce module ont des implications de sécurité critiques.
</important>

Cette technique n’est pas documentée officiellement par Anthropic mais est largement utilisée par la communauté pour réduire le taux d’instructions ignorées sur les fichiers CLAUDE.md plus longs.

Instructions de compaction

En sessions longues, Claude compacte automatiquement le contexte pour libérer de l’espace. Vous pouvez contrôler ce qui survit à la compaction :

## Compaction
Quand le contexte est compacté, toujours préserver :
- La liste complète des fichiers modifiés
- Les commandes de test utilisées et leurs résultats
- Les décisions architecturales prises pendant la session

Vous pouvez aussi déclencher la compaction manuellement avec /compact suivi d’instructions : /compact Focus on the API changes résume la conversation en ne gardant que ce qui concerne les changements d’API.

Commandes personnalisées référencées depuis CLAUDE.md

CLAUDE.md peut mentionner l’existence de commandes custom dans .claude/commands/ pour que l’agent sache qu’elles existent :

## Commandes custom disponibles
- `/review` : review du diff Git courant (sécurité, perf, erreurs)
- `/deploy-preview` : déploiement preview sur Vercel
- `/new-feature [nom]` : scaffold d'une nouvelle feature

Les commandes elles-mêmes sont des fichiers Markdown dans .claude/commands/ avec des instructions détaillées. CLAUDE.md les résume pour que l’agent (et vos collègues) sachent ce qui est disponible.

Hooks comme alternative aux règles de style

Plutôt que d’écrire des règles de style dans CLAUDE.md, configurez un hook Stop qui lance automatiquement votre formatter après chaque modification de Claude :

{
  "hooks": {
    "Stop": [{
      "command": "npx prettier --write $(git diff --name-only)",
      "description": "Format modified files on stop"
    }]
  }
}

Cette approche est plus fiable qu’une instruction dans CLAUDE.md et ne consomme aucun budget de contexte. L’instruction dans CLAUDE.md est alors remplacée par une simple ligne : « Le style de code est géré par Prettier via hook automatique. »

Erreurs courantes à éviter

Le CLAUDE.md « évier de cuisine ». 500 lignes d’instructions qui couvrent tous les cas possibles. Résultat : Claude ignore la moitié parce que les instructions importantes se perdent dans le bruit. Gardez le fichier sous 200 lignes.

Les instructions MUST en majuscules. Mettre « MUST » ou « ALWAYS » en majuscules ne rend pas l’instruction plus fiable. Ce qui fonctionne : être spécifique et concis. Au lieu de « You MUST ALWAYS use TypeScript strict mode », écrivez simplement « TypeScript strict, no any. »

Dupliquer le travail du linter. Si ESLint ou Prettier gèrent déjà le formatage, ne réécrivez pas ces règles dans CLAUDE.md. Utilisez plutôt un hook Stop qui lance automatiquement le formatter après les modifications de Claude.

Ne jamais mettre à jour le fichier. Un CLAUDE.md écrit il y a 6 mois et jamais modifié contient probablement des instructions obsolètes. Les projets évoluent, le fichier doit suivre.

Ignorer la compaction. En session longue, Claude compacte automatiquement le contexte. Si vous ne spécifiez pas quelles informations préserver, les détails critiques peuvent être résumés et perdus. Ajoutez des instructions de compaction explicites.