Le guide complet CLAUDE.md

Le CLAUDE.md, c'est quoi ?

Le fichier CLAUDE.md est le contexte persistant de votre projet. Claude Code le lit automatiquement au début de chaque session et l'utilise comme base pour toutes ses réponses. C'est votre moyen le plus efficace de transformer Claude d'un assistant généraliste en un membre de votre équipe qui connaît votre projet sur le bout des doigts.

Générer un CLAUDE.md avec /init

La manière la plus rapide de créer un CLAUDE.md est d'utiliser la commande built-in /init. Elle analyse automatiquement votre projet et génère un fichier adapté.

# Dans votre terminal, lancez Claude Code à la racine du projet
claude

# Puis tapez la commande /init
> /init

Structure recommandée

Un CLAUDE.md efficace suit une structure en 6 sections. L'ordre compte : les informations les plus importantes d'abord, car Claude les pondère davantage.

Section 1 : Présentation du projet

# CLAUDE.md

Site de documentation Next.js 14 (App Router), TypeScript strict, Tailwind CSS, MDX.
Déployé via Docker (Nginx Alpine). 100% statique (SSG), pas de SSR ni d'API routes.
URL : https://mon-site.fr

Cette section donne à Claude le contexte minimal pour comprendre quel projet il accompagne. Soyez bref : 2-3 lignes suffisent.

Section 2 : Commandes

## Commandes

- `npm run dev` : Serveur de dev (port 3000)
- `npm run build` : Build de production
- `npm run lint` : ESLint + Prettier
- `npm run type-check` : Vérification TypeScript
- `npm run test` : Vitest en mode watch
- `npm run test:coverage` : Couverture de tests

Claude utilise ces commandes pour exécuter les vérifications nécessaires. Listez toutes les commandes que Claude pourrait avoir besoin d'utiliser.

Section 3 : Architecture

## Architecture

/app                  → Pages et layouts (App Router)
/components/ui        → Composants réutilisables
/components/layout    → Header, Footer, Sidebar
/lib                  → Utilitaires et helpers
/content              → Fichiers MDX
/public               → Assets statiques

Cette section aide Claude à naviguer dans votre codebase et à créer les fichiers au bon endroit.

Section 4 : Style de code

## Style de code

- TypeScript strict, jamais de `any`
- Exports nommés uniquement, pas de default exports (sauf pages Next.js)
- Composants fonctionnels avec hooks, pas de classes React
- Tailwind CSS uniquement, pas de CSS custom
- Fichiers < 400 lignes, fonctions < 50 lignes
- Immutabilité : toujours créer de nouveaux objets, jamais muter

Ce sont les règles que Claude doit toujours respecter dans ce projet. Soyez explicite.

Section 5 : Contenu et rédaction

## Contenu

- Tout le contenu est en français avec accents
- Ton : accessible, enthousiaste, jamais condescendant
- Utiliser des analogies concrètes pour les concepts techniques
- Blocs de code avec langage spécifié pour le syntax highlighting

Si votre projet contient de la documentation ou du contenu éditorial, ces règles assurent la cohérence.

Section 6 : Règles importantes

## Règles importantes

- JAMAIS de secrets, clés API ou .env dans le repo
- Accessibilité : WCAG 2.1 AA minimum
- Images en WebP avec lazy loading
- Score Lighthouse visé : > 90 sur les 4 métriques

Les règles critiques qui ne doivent jamais être violées. Claude les traite comme des contraintes prioritaires.

Exemple réel de CLAUDE.md bien écrit

Voici un CLAUDE.md complet pour un projet SaaS typique.

# CLAUDE.md

MonApp : SaaS de gestion de projet. Monorepo pnpm.
Stack : Next.js 14 (App Router), TypeScript, Tailwind CSS, Prisma, PostgreSQL.
API : tRPC. Auth : NextAuth.js v5. Déploiement : Vercel.

## Commandes

- `pnpm dev` : Dev (turbo)
- `pnpm build` : Build production
- `pnpm lint` : ESLint
- `pnpm type-check` : TypeScript
- `pnpm test` : Vitest
- `pnpm db:push` : Push schema Prisma
- `pnpm db:seed` : Seed données de test

## Architecture

apps/web/           → Frontend Next.js
apps/api/           → API tRPC
packages/ui/        → Design system partagé
packages/db/        → Prisma schema + client
packages/config/    → ESLint, TypeScript, Tailwind configs

## Style de code

- TypeScript strict (no any, no as unknown)
- Immutabilité obligatoire
- Feature-based: src/features/[feature]/{components,hooks,utils}
- Repository pattern pour l'accès données
- Erreurs gérées avec Result<T, E> (pas de throw)

## Conventions

- Commits : feat:, fix:, refactor:, test:, docs:
- PR : description détaillée + test plan
- Tests : TDD obligatoire, couverture > 80%
- API responses : { success, data, error, meta }

## Sécurité

- Pas de secrets en dur (.env uniquement)
- Inputs validés avec Zod à toutes les frontières
- Requêtes Prisma paramétrées
- Rate limiting sur les endpoints publics

Ce CLAUDE.md fait environ 50 lignes. Il couvre l'essentiel sans surcharger le contexte.

Les 3 niveaux de CLAUDE.md

Claude Code supporte des fichiers CLAUDE.md à plusieurs niveaux, du plus global au plus spécifique.

La hiérarchie fonctionne par accumulation : les trois niveaux se combinent, avec le niveau le plus spécifique qui a la priorité en cas de conflit.

Comment Claude charge les fichiers CLAUDE.md

Il ne suffit pas de créer les fichiers : encore faut-il savoir lesquels Claude charge, et à quel moment. Il y a deux mécanismes distincts.

Chargement vers le haut (ancestor loading)

Au démarrage, Claude remonte l'arbre de dossiers depuis votre répertoire courant jusqu'à la racine du système. Chaque CLAUDE.md trouvé sur le chemin est chargé, du plus éloigné au plus proche. Le plus proche a la priorité.

/                          ← CLAUDE.md chargé en 1er
  home/
    vous/
      projets/
        monapp/            ← cwd au démarrage
          CLAUDE.md        ← chargé en 2nd (prioritaire)
          src/
            CLAUDE.md      ← pas encore chargé

Si vous lancez Claude depuis /monapp, seuls /.../monapp/CLAUDE.md et les CLAUDE.md parents sont chargés. Le fichier dans src/ ne l'est pas encore.

Chargement vers le bas (descendant loading)

Claude charge les fichiers CLAUDE.md des sous-dossiers de façon paresseuse : uniquement quand il touche un fichier dans ce sous-dossier. Si src/components/CLAUDE.md existe et que Claude ouvre un fichier dans src/components/, il charge ce CLAUDE.md à ce moment-là.

Exemple concret : avec cette arborescence...

/projet/
  CLAUDE.md                       ← chargé au démarrage
  src/
    CLAUDE.md                     ← chargé au démarrage (cwd = /projet)
    auth/
      CLAUDE.md                   ← chargé quand Claude lit src/auth/
    payments/
      CLAUDE.md                   ← chargé quand Claude lit src/payments/

...si le cwd est /projet, les deux premiers fichiers sont chargés immédiatement. Les deux autres attendent que Claude entre dans leurs dossiers respectifs.

CLAUDE.md vs settings.json vs .claude/rules/

Ces trois fichiers ont des rôles différents et complémentaires. Voici comment les utiliser.

# Structure complète de la configuration Claude Code
projet/
  CLAUDE.md                    # Contexte projet (commité)
  .claude/
    settings.json             # Config technique (commité ou non)
    commands/                 # Skills de projet
      review-pr.md
      deploy.md
    rules/                    # Règles thématiques (commitées)
      security.md
      testing.md
      performance.md
~/.claude/
  CLAUDE.md                   # Préférences globales
  settings.json              # Config globale
  commands/                  # Skills personnels
  rules/                     # Règles globales

.claude/rules/ : découper les instructions en fichiers thématiques

Quand votre CLAUDE.md commence à dépasser 150 lignes, c'est le signe que certaines sections méritent leur propre fichier. Le dossier .claude/rules/ est fait pour ça : Claude charge automatiquement tous les fichiers qui s'y trouvent au démarrage.

.claude/
  rules/
    code-style.md      ← conventions TypeScript, nommage, structure
    testing.md         ← stratégie de test, couverture requise, mocks
    security.md        ← règles de sécurité, gestion des secrets
    deployment.md      ← process de déploiement, checklist pre-prod

Chaque fichier se concentre sur un seul sujet. Quand vous modifiez les règles de test, vous éditez testing.md sans toucher au reste. C'est plus maintenable, et ça facilite les revues de code.

Directives conditionnelles avec <important>

Certaines règles ne s'appliquent que dans des contextes précis. Le tag <important if="..."> garantit que Claude ne les ignore pas quand la condition est remplie, même si le reste du CLAUDE.md est dense.

<important if="editing auth code">
Toujours vérifier les permissions avant de modifier les fichiers dans src/auth/.
Ne jamais stocker de tokens en clair dans le code.
Toute modification du middleware d'auth doit être accompagnée d'un test.
</important>

<important if="writing database migrations">
Tester la migration sur un dump de production avant de la valider.
Toujours écrire la migration inverse (down migration).
Ne jamais supprimer une colonne sans période de dépréciation.
</important>

C'est plus fort qu'un commentaire Markdown ordinaire : Claude comprend que ces instructions ont une priorité élevée dès que la condition est remplie.

Mémoire des agents

Quand vous utilisez des sous-agents (agents lancés par un agent parent), chacun peut avoir sa propre mémoire persistante, indépendante du CLAUDE.md. Il y a trois niveaux :

Les 200 premières lignes du fichier MEMORY.md correspondant sont injectées automatiquement au démarrage de l'agent. C'est utile pour des agents spécialisés qui ont besoin de se souvenir de décisions passées : un agent de code review qui retient vos préférences, un agent de documentation qui connaît le style éditorial du projet, etc.

Bonnes pratiques

Ce qu'il faut mettre dans le CLAUDE.md

• La stack technique et les versions importantes
• Les commandes de build, test et lint
• L'arborescence du projet (simplifiée)
• Les conventions de code non standard
• Les patterns architecturaux utilisés
• Les règles de nommage

Ce qu'il NE faut PAS mettre

• Des secrets, tokens ou mots de passe (utilisez .env)
• Du code ou des snippets trop longs (utilisez les rules)
• Des instructions contradictoires
• Des informations qui changent souvent (mettez-les dans les rules)
• Plus de 200 lignes de contenu

Mise à jour du CLAUDE.md

Mettez à jour votre CLAUDE.md quand :

• Vous ajoutez une nouvelle technologie à la stack
• Vous changez de convention de code
• Vous ajoutez un nouveau pattern architectural
• Un nouveau membre rejoint l'équipe (ajoutez les conventions de l'équipe)
• Vous constatez que Claude refait les mêmes erreurs (ajoutez la règle correspondante)

Une façon simple de garder le CLAUDE.md à jour : après avoir corrigé une erreur récurrente, demandez directement à Claude de mettre le fichier à jour pour refléter la règle. Il le fait bien, et ça évite de recommencer les mêmes conversations.

Comportements déterministes : settings.json plutôt que CLAUDE.md

Certains comportements ne doivent pas dépendre de l'interprétation du texte. Pour ceux-là, settings.json est plus fiable que le CLAUDE.md :

• Interdire certains outils (ex: Bash pour des raisons de sécurité)
• Configurer les permissions de lecture/écriture
• Forcer un modèle particulier pour un agent
• Gérer l'attribution dans les commits

Le CLAUDE.md est du texte que Claude interprète. settings.json est de la configuration que Claude obéit.

Prochaines étapes

Votre CLAUDE.md est maintenant en place. Explorez les sujets connexes.

• Prompting avancé et multi-agents : Techniques avancées pour exploiter le contexte
• Créer un Skill custom : Transformez vos workflows en slash commands
• Comprendre les agents : Configurez des agents dans votre CLAUDE.md
• Le configurateur Claude Code : Outil interactif pour générer votre configuration