CLAUDE.md : le guide complet pour écrire le meilleur fichier de contexte pour Claude Code

CLAUDE.md est le fichier qui permet à Claude Code de comprendre votre projet avant de travailler dessus. Il lui donne les informations essentielles sur votre codebase : architecture, stack technique, commandes, conventions, workflows, règles de sécurité et pièges connus.

Un bon CLAUDE.md peut rendre Claude beaucoup plus efficace. Un mauvais CLAUDE.md peut faire l’inverse : saturer le contexte, créer des contradictions, pousser Claude à suivre des règles inutiles ou l’amener à ignorer les instructions importantes.

Ce guide explique comment écrire un CLAUDE.md clair, court, maintenable et optimisé pour les agents de code.

Qu’est-ce qu’un CLAUDE.md ?

CLAUDE.md est un fichier Markdown utilisé par Claude Code pour charger des instructions persistantes liées à un projet. Il sert à donner à Claude le contexte dont il a besoin pour travailler correctement dans une codebase.

En pratique, CLAUDE.md répond à trois questions :

| Question | Réponse attendue | | ------------ | --------------------------------------------------------- | | Pourquoi ? | À quoi sert le projet | | Quoi ? | Quelle est la stack, la structure, les modules importants | | Comment ? | Comment installer, tester, modifier et vérifier le projet |

Il ne remplace pas la documentation complète du projet. Il agit plutôt comme une carte d’entrée pour Claude.

Pourquoi CLAUDE.md est important

Claude ne connaît pas votre codebase au début d’une session. Il ne sait pas automatiquement quel gestionnaire de paquets vous utilisez, où se trouvent les tests, quels modules sont sensibles, quelles conventions sont propres au projet ou quels outils doivent être privilégiés.

CLAUDE.md permet d’éviter à Claude de redécouvrir les mêmes informations à chaque fois.

Un bon fichier peut aider Claude à :

• trouver plus vite les bons fichiers ;
• utiliser les bonnes commandes ;
• respecter les conventions locales ;
• éviter les erreurs récurrentes ;
• vérifier son travail correctement ;
• poser moins de questions inutiles ;
• produire des changements plus cohérents.

CLAUDE.md n’est pas un prompt magique

Il faut comprendre une chose importante : CLAUDE.md guide Claude, mais ne contrôle pas Claude de manière absolue.

Claude peut ignorer certaines instructions si elles semblent non pertinentes pour la tâche en cours. Et c’est normal. Si vous mettez des règles de migration SQL dans le fichier racine, Claude n’a pas forcément besoin de les appliquer quand il corrige un bouton React.

La bonne stratégie n’est donc pas d’ajouter plus d’instructions. La bonne stratégie est d’ajouter moins d’instructions, mais plus pertinentes.

Quelle est la longueur idéale d’un CLAUDE.md ?

Un bon CLAUDE.md doit rester court.

Repères pratiques :

| Longueur | Qualité probable | | ---------------- | ------------------------------------- | | 50 à 100 lignes | Excellent pour la plupart des projets | | 100 à 200 lignes | Encore raisonnable | | 200 à 300 lignes | À surveiller | | 300+ lignes | Souvent trop long | | 500+ lignes | Généralement contre-productif |

L’objectif n’est pas d’être exhaustif. L’objectif est d’être utile dans presque toutes les sessions.

Si une information n’est utile que dans 10 % des tâches, elle n’a probablement pas sa place dans le fichier racine. Mettez-la plutôt dans un document spécialisé et pointez vers ce document.

Que mettre dans CLAUDE.md ?

Un bon CLAUDE.md contient seulement les informations universellement utiles.

1. Une vue d’ensemble du projet

Claude doit comprendre rapidement ce que fait le projet.

Exemple :

## Overview This project is a B2B SaaS platform for subscription analytics. It helps finance and growth teams track MRR, churn, expansion and cohort retention.

Cette section doit être courte. Deux à cinq phrases suffisent.

2. La structure du repo

Claude doit savoir où chercher.

Exemple :

`## Repository Structure

• apps/web: Next.js frontend
• apps/api: backend API
• packages/db: database schema and query helpers
• packages/ui: shared UI components
• packages/config: shared TypeScript and lint config`

Cette section est particulièrement importante dans les monorepos.

3. Les commandes essentielles

Claude doit connaître les commandes correctes.

Exemple :

`## Commands

• Install: pnpm install
• Dev server: pnpm dev
• Test: pnpm test
• Typecheck: pnpm typecheck
• Lint: pnpm lint
• Full check: `pnpm lint && pnpm typecheck && pnpm test``

Ne mettez pas 40 commandes. Mettez les commandes que Claude doit vraiment utiliser.

4. Les règles de travail

Claude doit savoir comment agir dans le repo.

Exemple :

`## Working Rules

• Read nearby code before editing.
• Prefer existing patterns over new abstractions.
• Keep changes scoped to the requested task.
• Run relevant checks after changing code.
• Do not commit unless explicitly asked.`

Ces règles sont utiles parce qu’elles s’appliquent à presque toutes les tâches.

5. Les règles d’architecture

Claude doit comprendre les limites importantes.

Exemple :

`## Architecture Rules

• API routes should call service-layer functions, not database helpers directly.
• Shared UI components belong in packages/ui.
• Business logic should not live in React components.`

Ici aussi, restez sélectif. Ne documentez pas toute l’architecture. Donnez les règles qui évitent les mauvaises décisions.

6. Les règles de sécurité

Les agents de code peuvent manipuler des fichiers sensibles. Soyez explicite.

Exemple :

`## Security

• Never print, commit or expose secrets.
• Do not modify production config without approval.
• Use existing auth helpers for protected endpoints.
• Validate external input before persistence.`

Pour les règles critiques, utilisez aussi des permissions, hooks ou protections techniques. CLAUDE.md seul ne suffit pas.

7. Les pièges connus

Les “gotchas” sont très utiles parce qu’ils évitent à Claude de perdre du temps.

Exemple :

`## Known Gotchas

• E2E tests require the dev server on port 3000.
• pnpm test can be noisy; use pnpm test -- --runInBand when debugging.
• Database migrations must be backward-compatible.`

Limitez cette section aux pièges fréquents et coûteux.

Ce qu’il ne faut pas mettre dans CLAUDE.md

Un mauvais CLAUDE.md devient vite un fourre-tout. Voici ce qu’il faut éviter.

Les règles vagues

Évitez :

Write clean code. Use best practices. Think carefully. Avoid bugs.

Ces phrases ne donnent pas d’information exploitable. Claude sait déjà qu’il doit écrire du bon code.

Préférez :

Prefer existing service patterns in apps/api/src/services before adding new abstractions.

Les longues règles de style

Claude n’est pas un linter. Ne mettez pas une page entière de conventions de formatage.

Mauvais :

Use two spaces. Sort imports alphabetically. Avoid trailing commas. Keep lines under 100 chars.

Meilleur :

Run pnpm formatandpnpm lint before finalizing code changes.

Les linters, formatters et hooks font ce travail mieux, plus vite et de façon déterministe.

Les procédures longues

Un processus de release en 30 étapes n’a pas sa place dans le fichier racine.

Mettez plutôt :

For releases, read agent_docs/release_process.md.

Les informations rarement utiles

Si vous travaillez sur le frontend, Claude n’a pas toujours besoin de voir 150 lignes sur les migrations SQL. Gardez les informations spécifiques dans des fichiers spécialisés.

Les secrets

Ne mettez jamais :

• clés API ;
• tokens ;
• mots de passe ;
• URLs privées sensibles ;
• exemples contenant de vraies credentials.

La méthode Progressive Disclosure

La meilleure pratique avancée pour CLAUDE.md est la progressive disclosure.

Le principe : ne donnez pas tout à Claude dès le départ. Donnez-lui une carte, puis laissez-le lire les documents pertinents quand la tâche l’exige.

Exemple d’organisation :

agent_docs/ building.md testing.md architecture.md database.md frontend.md release.md

Puis dans CLAUDE.md :

`## Additional Context Read these only when relevant:

• agent_docs/testing.md: test strategy and flaky test notes
• agent_docs/database.md: schema rules and migration policy
• agent_docs/frontend.md: UI conventions and component patterns
• agent_docs/release.md: release checklist`

Cette approche a plusieurs avantages :

• le fichier racine reste court ;
• Claude charge moins de contexte inutile ;
• les règles spécialisées sont plus faciles à maintenir ;
• chaque document peut être précis sans polluer toutes les sessions.

CLAUDE.md vs AGENTS.md

AGENTS.md est un équivalent ouvert utilisé par d’autres agents et environnements de coding agent. Les principes sont très proches : donner des instructions projet à l’agent.

Différence pratique :

| Fichier | Usage courant | | --------------- | --------------------------------------------- | | CLAUDE.md | Claude Code | | AGENTS.md | Codex, OpenCode, Cursor, Zed et autres agents | | CLAUDE.local.md | Préférences locales privées |

Si votre repo utilise déjà AGENTS.md, vous pouvez créer un CLAUDE.md minimal :

`@AGENTS.md

Claude Code Notes

Use Claude Code project memory and read relevant docs before making broad changes.`

Cela évite de maintenir deux fichiers contradictoires.

CLAUDE.md vs Skills

Les skills sont plus adaptées aux workflows longs ou spécialisés.

Utilisez CLAUDE.md pour :

• contexte projet ;
• commandes essentielles ;
• règles universelles ;
• architecture de haut niveau ;
• liens vers documents utiles.

Utilisez une skill pour :

• processus de release ;
• audit sécurité ;
• génération de tests ;
• migration complexe ;
• revue de PR ;
• workflow répétable.

Exemple :

`## Workflows

• For security reviews, use the security review skill.
• For release preparation, read agent_docs/release.md.`

Le fichier racine doit rester une boussole, pas un manuel complet.

CLAUDE.md vs hooks et settings

Certaines règles ne doivent pas seulement être “demandées” à Claude. Elles doivent être imposées techniquement.

Exemple : si vous ne voulez jamais que Claude lance une commande dangereuse, ne comptez pas seulement sur ceci :

Do not run destructive commands.

Utilisez aussi :

• permissions ;
• hooks ;
• sandbox ;
• protections git ;
• scripts de validation ;
• CI.

Bon principe :

| Besoin | Outil recommandé | | -------------------- | -------------------------------------------- | | Informer Claude | CLAUDE.md | | Guider une procédure | Skill ou doc spécialisée | | Bloquer une action | Permission ou hook | | Formater le code | Formatter | | Détecter les erreurs | Linter / tests / CI | | Protéger la prod | Settings, secrets manager, branch protection |

Exemple complet de CLAUDE.md optimisé

`# Project Instructions

Overview

This project is a B2B SaaS analytics platform for subscription businesses. It tracks MRR, churn, expansion, retention and customer cohorts.

Repository Structure

• apps/web: Next.js frontend
• apps/api: backend API
• packages/db: schema, migrations and query helpers
• packages/ui: shared design system
• packages/config: shared tooling config

Commands

• Install: pnpm install
• Dev: pnpm dev
• Test: pnpm test
• Typecheck: pnpm typecheck
• Lint: pnpm lint
• Full check: pnpm lint && pnpm typecheck && pnpm test

Working Rules

• Read nearby code before editing.
• Prefer existing patterns over new abstractions.
• Keep changes scoped to the requested task.
• Run relevant checks after code changes.
• Do not commit unless explicitly asked.

Architecture Rules

• API routes should call service-layer functions.
• Business logic should not live in React components.
• Shared UI primitives belong in packages/ui.

Additional Context

Read only when relevant:

• agent_docs/testing.md: test conventions and flaky test notes
• agent_docs/database.md: migration and schema rules
• agent_docs/frontend.md: UI component patterns
• agent_docs/release.md: release process

Security

• Never print, commit or expose secrets.
• Do not modify production config without approval.
• Use existing auth helpers for protected endpoints.
• Validate external inputs before persistence.

Known Gotchas

• E2E tests require the dev server on port 3000.
• Database migrations must be backward-compatible.
• Some integration tests require Docker.`

Exemple de CLAUDE.md pour un monorepo

`# Monorepo Instructions

Overview

This monorepo contains multiple apps and shared packages for the company platform.

Apps

• apps/web: customer-facing frontend
• apps/admin: internal admin dashboard
• apps/api: public and internal API

Packages

• packages/ui: shared UI components
• packages/db: database schema and migrations
• packages/auth: auth utilities and middleware
• packages/config: shared tooling config

Commands

• Install: pnpm install
• Run all tests: pnpm test
• Typecheck all: pnpm typecheck
• Test one package: pnpm --filter <package> test

Rules

• Prefer package-level commands when changing one app or package.
• Do not modify unrelated packages.
• Check package-specific docs before broad refactors.
• Keep shared packages backward-compatible.`

Exemple de CLAUDE.md pour une API backend

`# Backend Instructions

Overview

This service exposes the public API and internal admin API.

Structure

• src/routes: HTTP route definitions
• src/services: business logic
• src/db: query helpers and repositories
• src/middleware: auth, logging and request handling

Commands

• Test: pytest
• Typecheck: mypy .
• Lint: ruff check .
• Format: ruff format .

Rules

• Routes should stay thin.
• Business logic belongs in services.
• Use repository helpers for database access.
• Add tests for new service behavior.
• Do not log secrets or personal data.`

Exemple de CLAUDE.md pour un frontend

`# Frontend Instructions

Overview

This is a Next.js frontend for the customer dashboard.

Structure

• app: routes and pages
• components: feature-specific components
• packages/ui: shared primitives
• lib: client utilities and API helpers

Commands

• Dev: pnpm dev
• Test: pnpm test
• Typecheck: pnpm typecheck
• Lint: pnpm lint

Rules

• Use existing UI primitives before creating new ones.
• Keep business logic out of presentational components.
• Prefer server components unless interactivity requires client components.
• Test complex user flows.`

Comment maintenir CLAUDE.md

CLAUDE.md doit évoluer avec le projet.

À faire régulièrement :

1. Supprimer les règles obsolètes.
2. Ajouter les pièges récurrents.
3. Remplacer les longues sections par des liens vers docs dédiées.
4. Vérifier que les commandes fonctionnent encore.
5. Éviter les doublons avec README.md.
6. Faire reviewer les changements en PR.
7. Garder les instructions personnelles hors du fichier partagé.

Un bon test : demandez-vous si chaque ligne aide Claude dans au moins 70 % des sessions. Si non, déplacez-la ailleurs.

Comment optimiser CLAUDE.md pour les résultats réels

Un bon fichier ne suffit pas. Il doit s’intégrer à un workflow.

Workflow recommandé :

1. Claude lit CLAUDE.md.
2. Claude explore les fichiers pertinents.
3. Claude lit les documents spécialisés si nécessaire.
4. Claude propose un plan pour les changements complexes.
5. Claude modifie le code.
6. Claude lance les tests ciblés.
7. Claude corrige les erreurs.
8. Claude résume ce qui a changé.

Votre CLAUDE.md doit soutenir ce workflow, pas essayer de le remplacer.

Erreurs fréquentes

Erreur 1 : auto-générer puis ne jamais relire

Les commandes comme /init peuvent créer une base, mais ce n’est pas suffisant. Un fichier auto-généré contient souvent trop de bruit ou manque de jugement projet.

Utilisez-le comme brouillon, pas comme version finale.

Erreur 2 : copier la documentation entière

CLAUDE.md ne doit pas être un deuxième README. Il doit pointer vers la documentation utile, pas la recopier.

Erreur 3 : mélanger règles d’équipe et préférences personnelles

Les préférences locales doivent aller dans CLAUDE.local.md ou une mémoire utilisateur, pas dans le fichier partagé.

Erreur 4 : écrire des règles impossibles à vérifier

Mauvais :

Make elegant decisions.

Meilleur :

Before adding a new abstraction, check whether a similar pattern already exists in src/services.

Erreur 5 : oublier les commandes de vérification

Un agent de code travaille mieux quand il peut vérifier son résultat. Donnez-lui les commandes exactes.

FAQ sur CLAUDE.md

CLAUDE.md est-il obligatoire ?

Non. Mais sur un projet sérieux, il devient rapidement indispensable. Il réduit le temps de découverte et améliore la cohérence des changements.

Quelle est la différence entre CLAUDE.md et README.md ?

README.md est écrit pour les humains. CLAUDE.md est écrit pour guider Claude Code dans son travail. Il doit être plus opérationnel, plus court et plus orienté actions.

Peut-on avoir plusieurs CLAUDE.md ?

Oui. Vous pouvez avoir un fichier racine et des fichiers dans des sous-dossiers. Les instructions proches du dossier de travail peuvent donner un contexte plus spécifique.

Faut-il mettre les règles de style dans CLAUDE.md ?

Très peu. Mettez surtout les commandes de formatage et de lint. Les détails doivent être gérés par les outils.

Faut-il mettre les commandes de test ?

Oui. C’est l’une des informations les plus importantes. Claude doit savoir comment vérifier son travail.

CLAUDE.md peut-il contenir des imports ?

Oui, vous pouvez pointer vers d’autres fichiers avec des imports ou des références. Mais souvenez-vous : importer trop de contenu peut aussi augmenter le contexte chargé.

CLAUDE.md fonctionne-t-il pour Codex ?

Codex utilise plutôt AGENTS.md, mais les bonnes pratiques sont presque identiques : rester court, précis, orienté action, et éviter le bruit.

Checklist finale

Avant de publier votre CLAUDE.md, vérifiez ceci :

• Le fichier est court.
• Le projet est expliqué en quelques phrases.
• La structure du repo est claire.
• Les commandes essentielles sont exactes.
• Les règles sont concrètes.
• Les règles s’appliquent souvent.
• Les procédures longues sont déplacées.
• Les règles critiques sont enforceées ailleurs.
• Les secrets sont absents.
• Le fichier ne duplique pas le README.
• Les préférences personnelles sont séparées.
• Les pièges connus sont utiles et récents.
• Les liens vers docs spécialisées sont à jour.

Conclusion

CLAUDE.md est l’un des fichiers les plus puissants de Claude Code, mais sa puissance vient de sa précision, pas de sa longueur.

Le meilleur CLAUDE.md n’est pas celui qui contient le plus d’instructions. C’est celui qui donne à Claude juste assez de contexte pour travailler intelligemment : comprendre le projet, trouver les bons fichiers, utiliser les bonnes commandes, respecter les limites importantes et vérifier son travail.

Gardez-le court. Rendez-le concret. Déplacez le détail ailleurs. Utilisez les linters, hooks, settings et tests pour ce qui doit être imposé. Traitez CLAUDE.md comme une boussole pour agent de code, pas comme une encyclopédie.