CLAUDE.md : Guide Complet pour Configurer Claude Code en 2026

CLAUDE.md : le fichier qui transforme Claude Code en coéquipier productif

Le fichier CLAUDE.md est la première chose que Claude Code lit à chaque session — c'est sa mémoire de votre projet, ses règles internes, ses conventions. Sans CLAUDE.md, Claude Code redécouvre votre repo à chaque conversation et produit du code générique. Avec un bon CLAUDE.md, il comprend votre stack en 3 secondes et produit du code qui passe la review du premier coup.

Ce guide complet explique comment écrire un fichier CLAUDE.md efficace en 2026, présente la structure recommandée par Anthropic, fournit des templates prêts à l'emploi (Next.js, Python, monorepo), et liste les 7 erreurs qui rendent un CLAUDE.md inutile.

Sommaire

Qu'est-ce qu'un fichier CLAUDE.md ? {#definition}

Un fichier CLAUDE.md est un fichier Markdown placé à la racine de votre projet que Claude Code lit automatiquement au démarrage de chaque session. Il contient le contexte permanent de votre projet : stack technique, conventions de code, commandes utiles, règles non négociables, structure du repo.

Concrètement, CLAUDE.md joue trois rôles :

Le nom est sensible à la casse — il doit être exactement CLAUDE.md (majuscules pour CLAUDE, minuscule pour .md). Toute autre variation (claude.md, Claude.MD) sera ignorée.

Pourquoi CLAUDE.md change tout dans Claude Code {#pourquoi}

Sans CLAUDE.md, chaque session démarre à zéro. Vous devez expliquer à chaque fois que le projet utilise Next.js 16, que les composants sont en App Router, que pnpm est le gestionnaire de paquets, que les tests passent par Vitest. C'est 5 à 10 minutes perdues à chaque conversation, multipliées par 10-20 sessions par semaine.

Avec un bon fichier CLAUDE.md, ces informations sont injectées automatiquement dans le contexte au démarrage. Claude Code connaît instantanément votre stack, vos conventions et vos garde-fous. Trois bénéfices mesurables :

Anthropic confirme dans sa doc officielle que CLAUDE.md est lu en priorité, avant même la première question utilisateur. C'est littéralement le prompt système de votre projet.

Comment écrire un bon fichier CLAUDE.md ? {#comment-ecrire}

Un bon CLAUDE.md suit trois principes : court, structuré, vérifiable. Voici la méthode en 5 étapes.

Étape 1 : Lancer /init pour démarrer

Plutôt que de partir de zéro, lancez la commande /init dans Claude Code. Elle analyse votre projet (package.json, structure des dossiers, fichiers de config) et génère un CLAUDE.md de base. Vous le raffinerez ensuite, mais 80 % du travail de squelette est fait.

Étape 2 : Structurer en 5 sections principales

La structure CLAUDE.md la plus efficace en 2026 suit le pattern WHY / WHAT / HOW :

Étape 3 : Être spécifique et vérifiable

"Format the code correctly" est inutile car non vérifiable. "Use 2-space indentation, no semicolons, single quotes" est vérifiable. Claude Code respecte mieux les règles concrètes que les directives floues.

Étape 4 : Rester sous 200 lignes

Chaque ligne de CLAUDE.md consomme du contexte. Un fichier de 500 lignes pollue la fenêtre de contexte et réduit l'attention de Claude. La règle d'or : moins de 200 lignes pour le CLAUDE.md principal, idéalement entre 50 et 150.

Pour gérer le contexte intelligemment au-delà de CLAUDE.md, consultez notre guide [Claude Code : gérer le contexte avec /compact](/blog/claude-code-gerer-contexte-compact-context-rot-2026).

Étape 5 : Itérer comme un document vivant

CLAUDE.md n'est jamais "fini". Chaque fois que Claude fait une erreur évitable, ajoutez une règle. Chaque fois qu'une convention change, mettez-le à jour. C'est un living document qui grandit avec votre projet.

Pour aller plus loin, cette vidéo en français explique en détail le rôle de CLAUDE.md dans une session Claude Code :

La hiérarchie des CLAUDE.md : global, projet, sous-dossier {#hierarchie}

Beaucoup de développeurs ignorent qu'il existe trois niveaux de CLAUDE.md en 2026. Claude Code les lit et les fusionne dans un ordre précis.

Niveau 1 — Le CLAUDE.md global (`~/.claude/CLAUDE.md`)

Stocké dans votre home directory, ce fichier s'applique à tous vos projets. Réservez-le à vos préférences personnelles :

Niveau 2 — Le CLAUDE.md projet (`./CLAUDE.md`)

Placé à la racine de votre repo et versionné via Git, c'est le plus important. Il documente votre projet et est partagé avec toute l'équipe. C'est ici que vivent stack, conventions, commandes et règles métier.

Niveau 3 — Les CLAUDE.md sous-dossier

Vous pouvez placer un CLAUDE.md dans n'importe quel sous-dossier (./backend/CLAUDE.md, ./mobile/CLAUDE.md). Claude Code le lit quand il travaille dans ce dossier, en complément du CLAUDE.md racine. Idéal pour les monorepos.

Quand les trois niveaux existent, Claude Code les concatène — il n'y a pas d'écrasement, c'est un merge. Mettez donc les règles génériques en global, les règles projet à la racine, et les règles ultra-spécifiques en sous-dossier.

CLAUDE.md vs settings.json : la différence essentielle {#vs-settings}

C'est la confusion numéro 1 chez les nouveaux utilisateurs. Voici la règle simple :

CLAUDE.md = ce que Claude sait. settings.json = ce que Claude peut faire.

Si vous voulez qu'une règle soit respectée à 100 % (ne jamais lancer rm -rf, toujours formater avec Prettier avant commit), passez par un hook configuré dans settings.json. Si c'est une convention "soft" (préférer les fonctions pures, nommer les hooks en camelCase), CLAUDE.md suffit.

Pour configurer les hooks deterministes, voyez notre guide [Claude Code hooks : automatiser votre workflow](/blog/claude-code-hooks-automatiser-workflow).

Templates CLAUDE.md prêts à l'emploi {#templates}

Voici deux templates CLAUDE.md que vous pouvez copier-coller puis adapter.

Template 1 — Projet Next.js + TypeScript

# Project: SaaS Dashboard

## Stack
- Next.js 16 (App Router)
- TypeScript strict
- Tailwind CSS 4
- Prisma + PostgreSQL
- Auth via Better-Auth
- pnpm (NEVER npm or yarn)

## Commands
- Dev: pnpm dev
- Build: pnpm build (must pass before commit)
- Test: pnpm test (Vitest)
- Lint: pnpm lint (Biome)
- DB migrate: pnpm prisma migrate dev

## Conventions
- Components: PascalCase in /src/components
- Server actions: in /src/actions, suffix "Action"
- API routes: /src/app/api/[resource]/route.ts
- 2-space indent, no semicolons, single quotes
- Use shadcn/ui components, never re-create them

## Rules
- NEVER edit /src/generated (Prisma client)
- ALWAYS run pnpm build before suggesting a commit
- Server actions must validate input with Zod
- No "use client" unless strictly needed

Template 2 — Projet Python + FastAPI

# Project: ML Inference API

## Stack
- Python 3.13
- FastAPI 0.115
- Pydantic v2
- SQLAlchemy 2.0 (async)
- uv (NEVER pip)

## Commands
- Dev: uv run uvicorn app.main:app --reload
- Test: uv run pytest -xvs
- Lint: uv run ruff check . && uv run ruff format --check .
- Type check: uv run mypy app

## Conventions
- Snake_case for variables and functions
- PascalCase for classes (Pydantic models, SQLAlchemy entities)
- Async by default for I/O operations
- Pydantic models in /app/schemas, ORM models in /app/models
- One route file per resource in /app/routers

## Rules
- ALWAYS write a pytest test before merging a feature
- NEVER use sync DB calls in async routes
- Type hints obligatoires sur toutes les fonctions publiques
- Suivre PEP 8 strict via ruff (lignes max 100 chars)

Ces templates restent volontairement courts (60-80 lignes) — c'est l'idéal pour préserver le contexte. Adaptez-les à votre projet réel, ne les copiez jamais tel quel.

Les 7 erreurs courantes avec CLAUDE.md {#erreurs}

Après avoir analysé des dizaines de CLAUDE.md de développeurs francophones, voici les erreurs récurrentes qui rendent le fichier inutile ou contre-productif.

Erreur 1 — Faire un CLAUDE.md de 500 lignes

Plus c'est long, moins Claude le respecte. Au-delà de 200 lignes, vous saturez le contexte et l'attention se dilue. Soyez chirurgical.

Erreur 2 — Mélanger règles soft et règles hard

Une règle "ne jamais commit secret en clair" doit être un hook deterministe, pas une ligne dans CLAUDE.md. CLAUDE.md gère les conventions, settings.json gère les garde-fous absolus.

Erreur 3 — Documenter ce que le code dit déjà

"Le dossier /src contient le code source" est inutile — Claude le voit. Documentez ce que le code ne dit pas : pourquoi telle décision, quel pattern privilégier, quel piège éviter.

Erreur 4 — Oublier les versions des dépendances

Dire "Next.js" sans préciser "16" peut faire suggérer des API obsolètes. Toujours préciser les versions majeures de la stack.

Erreur 5 — Ne pas versionner CLAUDE.md

CLAUDE.md doit être commit dans Git. Sinon vous perdez le bénéfice collectif et chaque membre de l'équipe redécouvre les règles.

Erreur 6 — Y mettre des secrets

CLAUDE.md sera lu par Claude et par tous les contributeurs. N'y mettez jamais de clés API, URL de DB en clair, tokens. Les secrets vivent dans .env.

Erreur 7 — Ne jamais le mettre à jour

Un CLAUDE.md figé devient mensonger en 3 mois. Mettez-le à jour à chaque changement de stack majeur, chaque convention nouvelle, chaque erreur récurrente de Claude.

Si vous voulez automatiser l'évolution de CLAUDE.md, consultez notre guide [créer des commandes personnalisées avec Claude Code Skills](/blog/claude-code-skills-creer-commandes-personnalisees) — vous pouvez créer un skill /update-claude-md qui propose des ajouts pertinents.

Pour un exemple d'API construite avec Claude Code et un CLAUDE.md bien structuré, l'application [ImmoAPI](https://immoapi.app) est un cas d'usage concret de Claude Code en production sur un projet SaaS.

FAQ sur le fichier CLAUDE.md {#faq}

Qu'est-ce qu'un fichier CLAUDE.md exactement ?

Un fichier Markdown placé à la racine de votre projet que Claude Code lit automatiquement à chaque session. Il contient le contexte permanent du projet : stack, conventions, commandes, règles. Il agit comme un prompt système persistant.

Où placer le fichier CLAUDE.md dans un projet ?

À la racine du repo Git (./CLAUDE.md), au même niveau que package.json ou pyproject.toml. C'est cet emplacement qui est versionné et partagé avec l'équipe. Vous pouvez ajouter des CLAUDE.md secondaires dans des sous-dossiers pour des règles spécifiques (monorepo).

Quelle longueur idéale pour un fichier CLAUDE.md ?

Entre 50 et 200 lignes pour le CLAUDE.md principal. Au-delà, vous saturez le contexte et Claude Code respecte moins bien les règles. Soyez concis et vérifiable plutôt qu'exhaustif et flou.

Comment Claude Code lit-il le fichier CLAUDE.md ?

Au démarrage de chaque session, Claude Code détecte automatiquement le CLAUDE.md à la racine et l'injecte dans le contexte avant votre premier prompt. Il lit aussi le ~/.claude/CLAUDE.md global et les CLAUDE.md des sous-dossiers actifs. Les trois niveaux sont concaténés, pas écrasés.

Quelle différence entre CLAUDE.md et settings.json ?

CLAUDE.md contient le savoir (contexte, conventions, règles soft). settings.json contient les permissions (outils autorisés, hooks, env vars). Le premier est respecté à 80 %, le second à 100 %. Mettez les garde-fous critiques dans settings.json via des hooks.

Faut-il versionner CLAUDE.md dans Git ?

Oui, absolument. Le ./CLAUDE.md du projet doit être commit pour que toute l'équipe en bénéficie. Seul le ~/.claude/CLAUDE.md global reste local — c'est votre préférence personnelle.

Peut-on avoir plusieurs CLAUDE.md dans un projet ?

Oui. Vous pouvez placer un CLAUDE.md dans n'importe quel sous-dossier. Claude Code lit le CLAUDE.md racine plus celui du dossier où il travaille. Très utile pour les monorepos avec stacks différentes (backend Python, frontend Next.js).

Comment générer automatiquement un fichier CLAUDE.md ?

Lancez la commande /init dans une session Claude Code à la racine de votre projet. Claude analyse votre stack (fichiers de config, dépendances, structure) et génère un CLAUDE.md de base que vous raffinerez ensuite.

Conclusion

Le fichier CLAUDE.md est l'investissement à plus fort ROI sur Claude Code en 2026 — 30 minutes de rédaction vous font gagner des dizaines d'heures sur les semaines suivantes. La règle d'or : court (50-200 lignes), structuré (WHY/WHAT/HOW), vérifiable (instructions concrètes), versionné dans Git, mis à jour comme un living document.

Combiné à un settings.json bien configuré et à des hooks deterministes pour les garde-fous critiques, CLAUDE.md transforme Claude Code en coéquipier qui connaît votre projet par cœur dès la première seconde.

Pour aller plus loin et maîtriser toute la stack de configuration Claude Code, la [formation Claude Code complète](https://go.saas-ia.io/se-faire-remplacer-par-lia) couvre CLAUDE.md, settings.json, hooks, MCP et sous-agents avec des templates pour 6 stacks différentes.

Articles connexes