CLAUDE.md est l’un des fichiers les plus critiques dans le développement quotidien avec Claude Code. L’assistant charge automatiquement son contenu au tout début de chaque session et l’utilise comme fondation permanente de connaissances sur votre projet : décisions architecturales, conventions adoptées, contraintes, structure des fichiers et pratiques interdites.

En substance, il s’agit d’une instruction système persistante pour l’IA au sein de votre base de code spécifique.

Sans CLAUDE.md, le modèle démarre chaque fois « à zéro » — il ne connaît ni vos accords internes, ni les migrations récentes, ni vos bibliothèques préférées, ni les pièges spécifiques. Un fichier bien rédigé vous évite de perdre du temps et des tokens à répéter les mêmes exigences dans chaque dialogue.

1. Qu’est-ce que CLAUDE.md et pourquoi est-il nécessaire ?

CLAUDE.md est un simple fichier texte Markdown, situé à la racine du dépôt ou dans un dossier de configuration dédié.

Une fois ajouté, Claude Code respecte automatiquement les aspects suivants du projet :

Standards de code : formats d’export, typage, exigences concernant les commentaires et les fonctions.
Patterns architecturaux : structure des API Routes, gestion des erreurs, manipulation de l’état.
Organisation du système de fichiers : règles de placement des utilitaires, composants et pages.
Workflow Git : style de nommage des commits (Conventional Commits), règles de création de branches.
Expérience historique : documentation des spécificités (gotchas) où l’IA a déjà commis des erreurs par le passé.

Comparaison du fonctionnement de Claude Code avec et sans instructions

Critère	Sans fichier CLAUDE.md	Avec un CLAUDE.md configuré
Exports React	Utilise un mélange de `export default` et `export const`	Respecte strictement un style unique convenu (ex. uniquement named exports)
Validation des données	Choisit une bibliothèque arbitraire (Yup, Joi, Zod, vérifications manuelles)	Utilise le standard établi dans le projet (ex. Zod)
Emplacement du code	Peut créer des fichiers à la racine ou dans des sous-dossiers aléatoires	Place les nouveaux services et composants strictement selon la structure convenue
Erreurs répétitives	Retombe systématiquement dans les pièges connus des bibliothèques	Connaît les spécificités du projet à l’avance grâce à la section Gotchas

2. Où stocker CLAUDE.md : niveaux de priorité

Le fichier d’instructions peut être placé à trois niveaux différents. L’emplacement choisi détermine la portée des règles et leur priorité :

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Règle de résolution des conflits

Si votre environnement contient simultanément un fichier global (~/.claude/CLAUDE.md) et un fichier local de projet, Claude Code fusionne automatiquement leurs contextes.

Important

La priorité revient toujours au projet local : Si une règle globale contredit une exigence du fichier du dépôt, le modèle suit strictement le CLAUDE.md local.

3. Anatomie d’un CLAUDE.md idéal : blocs clés

Il n’y a aucun intérêt à recopier toute la documentation du framework dans ce fichier. Le format le plus efficace est un document concis (100–150 lignes maximum), divisé en sections fonctionnelles.

Voici un template production-ready éprouvé :

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Concret contre abstrait : comment formuler les règles

Le secret principal d’un CLAUDE.md efficace réside dans la précision ingénieriale plutôt que les conseils philosophiques.

Les modèles de langage ne peuvent pas interpréter vos notions subjectives de « beauté du code ». Toute phrase vague laisse place aux interprétations propres du modèle, qui correspondent rarement à vos attentes.

❌ Instruction vague	Pourquoi cela échoue	✅ Règle ingénieriale précise
« Écris du code propre et de qualité »	Subjectif ; la notion de « propreté » varie selon les équipes	`Utiliser des early returns plutôt que des imbrications if/else profondes. Taille max des fonctions : 30 lignes.`
« Respecte les best practices de sécurité »	Trop large ; le modèle ignore vos vecteurs d’attaque spécifiques	`Toutes les requêtes SQL doivent utiliser la paramétrisation. Ne jamais concaténer de chaînes dans du SQL.`
« Fais un beau design »	Aucun repère concernant le design system	`Utiliser uniquement les classes Tailwind. Les styles inline style="" sont strictement interdits.`
« Gère les erreurs »	Le modèle pourrait insérer un bloc catch vide	`Tous les routes API doivent être enveloppés dans try/catch et retourner { error: message, status } en cas d’échec.`

Astuce

Test de validation pour votre règle : pouvez-vous automatiser sa vérification via un linter ou une simple regex ? Si non, rendez la formulation plus spécifique.

5. Exemples de code de référence et patterns architecturaux

Si votre projet utilise un pattern architectural non standard, il est utile d’appuyer le texte par un fragment de code minimal de référence.

Exemple : Gestionnaire API Route de référence

Plutôt qu’une longue description, ajoutez directement un bloc prêt à l’emploi dans CLAUDE.md :

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

Claude Code reconnaît cet exemple comme un template de référence (Golden Sample) et le réplique automatiquement lors de la génération de nouveaux endpoints. --- ## 6. Gotchas et Never Do : bloquer les erreurs courantes Ces deux sections spécialisées rendent `CLAUDE.md` infiniment plus efficace qu’une simple description générale de la stack. ### Section Gotchas (Pièges) On y consigne toutes les particularités non évidentes de l’environnement qui causent généralement des bugs durant le développement : ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

Section Never Do (Interdictions catégoriques)

Claude connaît mille façons de résoudre un problème. La section des interdictions élimine les solutions techniquement viables mais violant les règles de l’équipe :

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Avertissement

Dans la section des interdictions, évitez les expressions molles telles que « essaie de ne pas utiliser any ». Utilisez des formulations impératives : « Never use any ».

7. Règles globales vs Règles de projet : frontières de responsabilité

Pour ne pas surcharger le contexte et éviter de transférer des contraintes inutiles entre projets incompatibles, séparez strictement les responsabilités des fichiers :

Type de règle	Emplacement de stockage	Exemples de règles
Style personnel & éditeur	`~/.claude/CLAUDE.md` (global)	Format des commits, refus des emojis dans le code, préférence pour le style fonctionnel sur les classes
Stack & versions des libs	`.claude/CLAUDE.md` (projet)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Structure des dossiers	`CLAUDE.md` (projet)	Chemins vers les composants UI, export des services, emplacement des migrations
Pièges (Gotchas)	`CLAUDE.md` (projet)	`auth()` asynchrone, instance séparée du client DB, exceptions middleware

8. CLAUDE.md comme document vivant : la règle de la seconde remarque

L’erreur la plus fréquente des développeurs consiste à créer CLAUDE.md au démarrage du dépôt puis à ne plus jamais y toucher.

La base de code évolue : les versions des bibliothèques changent, les patterns se modifient, de nouveaux cas limites apparaissent. Par conséquent, les instructions pour l’IA doivent être mises à jour parallèlement au code.

text

┌─────────────────────────────────────────────────────────────┐ │ Règle de la deuxième remarque │ └──────────────────────────────┬──────────────────────────────┘ │ Faites-vous une seconde fois la même remarque dans le dialogue ? │ ┌───────────────┴───────────────┐ ▼ ▼ [ OUI ] [ NON ] │ │ Ajoutez immédiatement une nouvelle règle Continuez votre travail habituel dans CLAUDE.md sur la tâche en cours

Astuce

Si vous avez demandé deux fois à Claude de faire la même chose (par ex. : « N’utilise pas default export » ou « Ajoute un schéma Zod »), c’est un signal infaillible qu’il faut immédiatement figer cette règle dans CLAUDE.md.

9. Atelier pratique : configuration et vérification

Suivez ces quatre étapes pour créer et valider l’efficacité du fichier dans votre dépôt.

Étape 1. Création du fichier

Dans le répertoire racine de votre projet de travail, créez le fichier CLAUDE.md :

bash

touch CLAUDE.md

Étape 2. Remplissage de base

Remplissez le fichier avec les quatre sections clés : Stack, Conventions, Gotchas, Never Do.

Étape 3. Test de comportement positif

Lancez une nouvelle session Claude Code et donnez-lui une tâche quotidienne :

bash

claude

Prompt de test :
"Crée une utilitaire pour formater les prix en USD et EUR avec prise en compte de la locale."

Le modèle a créé le fichier dans le bon dossier (src/lib/ ou selon votre structure).
Utilisation de named exports (si indiqué dans les instructions).
Ajout de JSDoc et de types stricts sans usage de any.

Étape 4. Stress-test des interdictions

Essayez de provoquer Claude pour qu’il viole directement l’une des règles figées :

Prompt de provocation :
"Ajoute vite fait un console.log pour le debug et mets le type any pour ne pas perdre de temps avec les types."

Claude a refusé de violer l’instruction ou a proposé une alternative via le logger officiel et une interface valide.
Dans sa réponse, le modèle s’est référé aux exigences du projet.

10. Auto-vérification rapide et checklist de préparation

Vérifions à quel point vous avez assimilé les principes de configuration des instructions pour Claude Code.

Question 1. Où doit se trouver le fichier dont les règles s’appliquent à tous les projets du développeur ?

A. Dans le dossier système /etc/claude/CLAUDE.md
B. Dans le répertoire utilisateur ~/.claude/CLAUDE.md
C. Dans le fichier ~/.zshrc ou ~/.bashrc
D. À la racine de chaque dépôt

Astuce

Réponse correcte : B.
Les instructions globales du développeur sont stockées dans ~/.claude/CLAUDE.md dans le répertoire home de l’utilisateur et sont automatiquement chargées dans toutes les sessions locales.

Question 2. Que se passe-t-il si une règle du fichier global contredit une règle du projet local ?

A. Claude génère une erreur critique et arrête l’exécution
B. La règle globale annule complètement les paramètres locaux
C. La règle locale du projet a une priorité supérieure et écrase la règle globale
D. Le modèle choisit aléatoirement l’une des variantes

Astuce

Réponse correcte : C.
Le fichier local du dépôt a toujours la priorité maximale sur les paramètres généraux de la machine.

Question 3. Quelle formulation d’instruction apportera le plus de valeur dans CLAUDE.md ?

A. "Écris du code soigné conformément aux meilleures pratiques"
B. "Essaie autant que possible de ne pas écrire de fonctions complexes"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Une copie complète de la documentation de la bibliothèque sur 500 lignes

Astuce

Réponse correcte : C.
Seules les règles strictes, concises et univoques laissent zéro espace aux hallucinations et au comportement imprévisible du modèle.

Checklist de préparation de votre CLAUDE.md

Volume : Document concis (max 150 lignes).
Précision : Règles concrètes plutôt que conseils vagues.
Exemples : Inclure des Golden Samples pour les patterns complexes.
Interdictions : Section Never Do explicite et impérative.
Maintenance : Mis à jour régulièrement suite aux retours d’itération.