J'utilise Claude Code quotidiennement depuis début 2025, et je peux vous dire que le facteur déterminant pour obtenir des résultats utiles n'est pas l'ingénierie des prompts ou les astuces astucieuses. C'est le contexte. Plus précisément, c'est un fichier CLAUDE.md bien rédigé situé à la racine de votre projet. Ce seul fichier fait la différence entre un assistant IA qui se bat contre votre base de code et celui qui ressemble à un développeur senior qui travaille dans votre équipe depuis des mois.

Si vous avez lancé des prompts à Claude Code et reçu des résultats génériques, incorrects ou frustrants, ce guide est pour vous. Je vais vous expliquer exactement comment structurer votre CLAUDE.md, ce qu'il faut inclure, ce qu'il faut laisser de côté, et partager des exemples réels de projets en production que nous avons livrés chez Social Animal.

Table des matières

Qu'est-ce que CLAUDE.md et pourquoi c'est important

CLAUDE.md est un fichier markdown que vous placez à la racine de votre dépôt et que Claude Code lit automatiquement à chaque démarrage d'une session. Pensez-y comme à une documentation d'intégration pour votre programmeur en pair IA. Quand un nouveau développeur rejoint votre équipe, vous ne lui donnez pas simplement un ordinateur et ne lui dites pas « débrouille-toi ». Vous le guidez à travers l'architecture, vous expliquez les parties bizarres, vous pointez les pièges. CLAUDE.md fait la même chose pour Claude.

Sans lui, Claude Code doit tout déduire de votre structure de fichiers, package.json, et les fichiers qu'il se trouve à lire. C'est comme demander à une nouvelle embauche de comprendre votre système entier en lisant des fichiers source aléatoires. Ils auront raison sur certaines choses, mais ils feront aussi des suppositions qui gaspilleront le temps de tout le monde.

Avec un CLAUDE.md solide, j'ai vu la précision d'exécution des tâches passer d'environ 60% à plus de 90% aux premières tentatives. Ce n'est pas une petite amélioration — c'est la différence entre le développement assisté par IA qui est un multiplicateur de productivité et celui qui est un puits de temps frustrant.

Comment Claude Code lit le contexte de votre projet

Claude Code a une hiérarchie spécifique pour charger le contexte. Comprendre cela est important car cela affecte la façon dont vous organisez votre mémoire de projet.

L'ordre de chargement du contexte

  1. ~/.claude/CLAUDE.md — Vos préférences globales (appliquées à chaque projet)
  2. ./CLAUDE.md — Le fichier au niveau du projet à la racine de votre dépôt
  3. ./subdirectory/CLAUDE.md — Les remplacements spécifiques au répertoire
  4. .claude/settings.json — Les permissions et paramètres des outils spécifiques au projet
  5. Session context — Ce que vous dites à Claude dans la conversation actuelle

Le CLAUDE.md au niveau du projet est celui sur lequel vous passerez le plus de temps. Le fichier global est utile pour les préférences personnelles (« Je préfère les composants fonctionnels » ou « toujours utiliser le mode strict TypeScript »), mais la vraie valeur réside dans le contexte par projet.

Voici ce qui est crucial : Claude Code lit le CLAUDE.md au début de chaque session, mais il a aussi un espace de fenêtre contextuelle limité. Si votre CLAUDE.md contient 5 000 mots de documentation bavarde, vous brûlez des tokens qui auraient pu être utilisés pour le raisonnement du code. Soyez concis. Soyez spécifique. Chaque ligne doit mériter sa place.

L'anatomie d'un excellent fichier CLAUDE.md

Après avoir écrit et affiné des fichiers CLAUDE.md dans des dizaines de projets — applications Next.js, sites Astro, intégrations de CMS headless, services API — j'en suis arrivé à une structure cohérente qui fonctionne.

La structure idéale

# Nom du Projet

## Aperçu
Un paragraphe expliquant ce que ce projet fait et pour qui.

## Stack Technologique
Versions exactes et frameworks.

## Architecture
Comment les pièces s'assemblent.

## Conventions Clés
Normes de codage, motifs de nommage, règles d'organisation des fichiers.

## Commandes Courantes
Commandes de build, test, déploiement et dev.

## Contexte Important
Trucs qui ne sont pas évidents dans le code.

## Problèmes Connus / Pièges
Les pièges à éviter.

## À NE PAS FAIRE
Des choses explicites que l'IA ne devrait jamais faire.

Examinons chaque section.

Analyse section par section

Aperçu

Limitez-vous à 2-3 phrases maximum. Claude n'a pas besoin de votre roadmap de produit — il a besoin de comprendre le domaine pour prendre des décisions contextuellemet appropriées.

## Aperçu
C'est le site marketing d'Acme Corp, une plateforme SaaS B2B pour la gestion de la chaîne d'approvisionnement. Le site est généré statiquement avec des routes API dynamiques pour la gestion des formulaires et la capture de leads. Le contenu est géré par l'équipe marketing via Sanity CMS.

Stack Technologique

Soyez exact. Ne dites pas simplement « React » — spécifiez la version, le framework, la stratégie de rendu. Cela empêche Claude de suggérer des motifs qui fonctionnent dans React 18 mais cassent dans React 19, ou de recommander Pages Router quand vous utilisez App Router.

## Stack Technologique
- **Framework**: Next.js 15.1 (App Router, RSC par défaut)
- **Langage**: TypeScript 5.7 (mode strict)
- **Styling**: Tailwind CSS v4 avec configuration CSS-first
- **CMS**: Sanity v3 avec aperçu en direct
- **Déploiement**: Vercel (environnements Production + Preview)
- **Gestionnaire de paquets**: pnpm 9.x
- **Node**: v22 LTS
- **Tests**: Vitest + Playwright
- **Gestion d'état**: Zustand (minimal, seulement pour l'état UI côté client)

Architecture

C'est là où la plupart des gens écrivent soit trop peu, soit beaucoup trop. Vous n'écrivez pas un document de conception de système. Vous donnez à Claude un modèle mental.

## Architecture
- `app/` — Pages et layouts Next.js App Router
- `app/api/` — Routes API (soumissions de formulaires, webhooks)
- `components/` — Composants UI partagés (atomic design: atoms/, molecules/, organisms/)
- `lib/` — Fonctions utilitaires, clients API, définitions de types
- `lib/sanity/` — Client Sanity, requêtes (GROQ), et génération de types
- `content/` — Fichiers MDX pour les articles de blog (co-localisés avec frontmatter)
- `public/` — Ressources statiques (préférer next/image pour toutes les images)

Flux de données: Sanity CMS → requêtes GROQ dans lib/sanity/queries.ts → Server Components → Client Components (seulement quand l'interactivité est nécessaire)

Toutes les pages sont générées statiquement au moment de la construction sauf /blog/[slug]/preview qui utilise le mode brouillon.

Conventions Clés

Cette section économise le plus de temps. Sans elle, Claude suivra les meilleures pratiques générales qui peuvent entrer en conflit avec les choix de votre équipe.

## Conventions Clés
- Les composants sont nommés PascalCase, un composant par fichier
- Utilisez les exports nommés, jamais les exports par défaut (sauf pages/layouts)
- Toute récupération de données se fait dans les Server Components — ne jamais utiliser useEffect pour la récupération de données
- Les types de réponse API vivent dans lib/types/ et sont auto-générés à partir du schéma Sanity
- Utilisez l'utilitaire `cn()` (lib/utils.ts) pour la fusion de classes conditionnelles, pas les littéraux de modèle
- Les limites d'erreurs encadrent chaque section de page majeure, pas la page entière
- Toute gestion de formulaire utilise react-hook-form + schémas de validation zod
- Les messages de commit suivent Conventional Commits (feat:, fix:, chore:)

Commandes Courantes

Cela semble basique, mais Claude Code exécute réellement ces commandes. S'il ne connaît pas les bonnes, il devinera, et il deviner souvent mal.

## Commandes Courantes
- `pnpm dev` — Démarrer le serveur de développement (port 3000)
- `pnpm build` — Build de production
- `pnpm lint` — Vérification ESLint + Prettier
- `pnpm test` — Exécuter les tests unitaires Vitest
- `pnpm test:e2e` — Exécuter les tests E2E Playwright
- `pnpm sanity:typegen` — Régénérer les types Sanity après les modifications du schéma
- `pnpm db:migrate` — Exécuter les migrations Drizzle ORM

Contexte Important

Ceci est pour le trucs que Claude ne peut pas découvrir en lisant votre code. La logique métier, les contraintes externes, les choses qui prendraient 30 minutes à un examinateur humain à expliquer.

## Contexte Important
- Nous utilisons ISR (revalidate: 3600) pour toutes les pages CMS. Ne jamais utiliser `force-dynamic` sauf si absolument nécessaire.
- Le webhook Sanity à /api/revalidate gère la revalidation à la demande — ne pas ajouter de logique de revalidation manuelle.
- L'optimisation des images passe par le CDN Sanity (cdn.sanity.io), pas next/image pour le contenu CMS.
- L'authentification est gérée par Clerk — ne jamais construire de flux d'authentification personnalisés.
- Le point de terminaison /api/leads a une limitation de débit via Upstash Redis. Ne pas supprimer le middleware de limitation de débit.

Pièges Connus

Chaque projet a des trucs bizarres. Mettez-les ici pour que Claude ne trébuche pas dessus.

## Pièges Connus
- Le rendu du texte portable de Sanity a un bug avec les listes imbriquées en v3.2. Nous utilisons un sérialiseur personnalisé dans components/portable-text/list-fix.tsx
- Tailwind v4 ne supporte pas la directive `@apply` dans les fichiers CSS de module — utilisez les classes en ligne à la place
- Les rewrites vercel.json pour /docs/* font un proxy vers notre site de documentation Mintlify. Ne modifiez pas ceux-ci sans vérifier avec l'équipe.
- Les variables d'environnement préfixées par NEXT_PUBLIC_ sont les seules disponibles côté client. Ne jamais exposer les secrets API de cette façon.

La section « À NE PAS FAIRE »

Cette section est probablement la plus importante. Les instructions négatives sont incroyablement efficaces avec les modèles IA.

## À NE PAS FAIRE
- Ne pas installer de nouvelles dépendances sans demander d'abord
- Ne pas utiliser le type `any` — trouvez ou créez des types appropriés
- Ne pas créer de nouvelles routes API pour des choses qui peuvent être faites dans les Server Components
- Ne pas modifier les fichiers du schéma Sanity sans confirmer le plan de migration
- Ne pas utiliser `"use client"` à moins que le composant n'ait vraiment besoin d'API navigateur ou de gestionnaires d'événements
- Ne pas écrire de fichiers CSS — tout est des classes utilitaires Tailwind
- Ne pas coder en dur des chaînes qui devraient provenir du CMS

Exemples réels de CLAUDE.md

Exemple: Site Marketing Next.js

C'est une version allégée d'un CLAUDE.md que nous utilisons sur les projets clients, particulièrement lors de la construction de sites Next.js avec des backends CMS headless.

# Site Marketing Acme

## Aperçu
Site marketing pour Acme (acme.com). Construit avec Next.js 15, stylisé avec Tailwind v4, contenu de Sanity CMS. Cible: LCP sub-2s sur toutes les pages.

## Stack Technologique
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## Architecture
App Router avec RSC. Toute récupération de données dans les composants serveur via requêtes GROQ dans lib/sanity/queries.ts. Composants clients seulement pour les éléments interactifs (modales, formulaires, carrousels).

Pages: / (accueil), /about, /pricing, /blog, /blog/[slug], /contact

## Conventions
- Exports nommés uniquement (sauf page.tsx/layout.tsx)
- Composants: PascalCase, un par fichier
- cn() pour la fusion de classes
- Schémas Zod pour toute validation de formulaire
- Pas de useEffect pour la récupération de données. Jamais.

## Commandes
pnpm dev | pnpm build | pnpm lint | pnpm test

## À NE PAS FAIRE
- Ajouter "use client" sans justification
- Installer des paquets sans demander
- Utiliser les exports par défaut pour les composants
- Modifier les fichiers sanity/schema/ sans confirmer la migration
- Utiliser le type any

Exemple: Site de Contenu Astro

Pour les projets Astro, le CLAUDE.md ressemble un peu différent car le paradigme architectural est différent.

# Blog Tech — Astro

## Aperçu
Blog pour développeurs avec 500+ articles. Static-first, zéro JS par défaut. MDX pour le contenu avec des composants personnalisés.

## Stack Technologique
Astro 5.x | MDX | Tailwind v4 | Déployé sur Cloudflare Pages | Content Collections v2

## Architecture
src/content/ — Articles MDX avec frontmatter validé Zod
src/components/ — Composants Astro (zéro JS) et îles React (interactifs)
src/layouts/ — Layouts de base
src/pages/ — Routage basé sur fichiers

## Règles Clés
- Préférer les composants Astro (.astro). Utiliser React seulement pour les îles qui ont besoin d'interactivité.
- client:visible pour les composants interactifs sous le pli
- client:idle pour les composants interactifs non critiques
- Ne jamais utiliser client:load à moins que absolument nécessaire
- Toutes les images utilisent le composant Image d'Astro avec width/height appropriés
- Le flux RSS auto-génère depuis la collection de contenu — ne pas construire de logique de flux manuelle

## À NE PAS FAIRE
- Ajouter des composants React quand un composant Astro ferait l'affaire
- Utiliser la directive client:load
- Ignorer les dimensions d'image (cause CLS)
- Modifier le schéma de collection de contenu sans mettre à jour le frontmatter existant

Les erreurs courantes qui ruinent votre contexte IA

J'ai revu beaucoup de fichiers CLAUDE.md à ce stade. Voici les motifs qui mènent systématiquement à de mauvais résultats.

Erreur Pourquoi c'est nuisible Correction
Trop long (2000+ mots) Brûle des tokens de fenêtre contextuelle, les infos clés se perdent Garder moins de 800 mots. Lier vers docs externes pour les approfondissements.
Trop vague (« nous utilisons React ») Claude remplit les lacunes avec des suppositions Être spécifique: versions, motifs, outils exacts
Aucune instruction négative Claude fait les choses « raisonnables » qui cassent vos conventions Toujours inclure une section « À NE PAS FAIRE »
Copy-paste du README.md Les README sont pour les humains, pas le contexte IA Écrire CLAUDE.md de zéro avec un cadrage spécifique à l'IA
Inclure des données sensibles Clés API, secrets dans les fichiers de contexte Ne jamais mettre les secrets dans CLAUDE.md. Référencer .env.example à la place
Ne jamais le mettre à jour Le projet évolue, le fichier de contexte ne change pas Revoir CLAUDE.md à chaque sprint ou grand refactoring
Instructions contradictoires « Utiliser les server components » + exemples avec useEffect fetching Avoir une personne propriétaire du fichier, revoir pour la cohérence

CLAUDE.md vs autres fichiers de contexte IA

Claude Code n'est pas le seul outil IA qui lit les fichiers de contexte de projet. Voici comment le paysage se présente en 2025:

Fichier Outil Auto-lecture Portée
CLAUDE.md Claude Code Oui, au démarrage de la session À l'échelle du projet
.cursorrules Cursor Oui, à l'ouverture du fichier À l'échelle du projet
.github/copilot-instructions.md GitHub Copilot Oui, dans Copilot Chat À l'échelle du dépôt
.windsurfrules Windsurf (Codeium) Oui À l'échelle du projet
AGENTS.md OpenAI Codex CLI Oui À l'échelle du projet
.ai/context.md Convention personnalisée Non (référence manuelle) Varie

Bonne nouvelle: la plupart du contenu est transférable. Si vous écrivez un solide CLAUDE.md, le convertir en .cursorrules ou copilot-instructions.md prend environ 5 minutes. La structure et les informations sont les mêmes — seul le nom de fichier et le formatage mineur diffèrent.

Si votre équipe utilise plusieurs outils IA (et beaucoup le font en 2025), envisagez de maintenir une seule source de vérité et de générer les fichiers spécifiques à l'outil à partir de celle-ci. Un simple script de construction peut copier votre fichier de contexte principal aux bons endroits.

Motifs avancés pour les grands projets

Fichiers CLAUDE.md imbriqués

Pour les monorepos ou les grandes bases de code, vous pouvez placer des fichiers CLAUDE.md dans les sous-répertoires. Claude Code lira le plus spécifique pour le répertoire dans lequel vous travaillez.

projet/
├── CLAUDE.md              # Contexte global du projet
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Contexte spécifique à l'appli web
│   └── api/
│       └── CLAUDE.md      # Contexte spécifique à l'API
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Contexte du système de conception

Le CLAUDE.md racine couvre l'architecture partagée et les conventions. Chaque fichier imbriqué ajoute des spécificités pour ce paquet.

Contexte dynamique avec /compact

La commande /compact de Claude Code résume la conversation actuelle et libère de l'espace de contexte. Pour les sessions longues, j'ai trouvé un motif qui fonctionne bien:

  1. Démarrer avec CLAUDE.md chargé automatiquement
  2. Travailler sur une fonctionnalité
  3. Exécuter /compact quand le contexte devient lourd
  4. Continuer — Claude conserve le contexte CLAUDE.md plus un résumé compressé

Contexte partagé par l'équipe vs personnel

Nous gardons CLAUDE.md dans le contrôle de version (il doit être commité). Mais les développeurs individuels utilisent également ~/.claude/CLAUDE.md pour les préférences personnelles:

# Préférences Personnelles
- Je préfère les noms de variables verbeux aux abréviations
- Montrez-moi le raisonnement avant d'écrire le code
- Quand vous suggérez des changements, montrez le diff complet du fichier
- J'utilise VS Code avec les keybindings Vim (ne suggérez pas de raccourcis spécifiques à l'IDE)

Cette séparation garde le fichier d'équipe propre et concentré sur les faits du projet tout en permettant aux individus de personnaliser leur expérience.

Mesurer l'impact

Comment savez-vous que votre CLAUDE.md fonctionne? Voici les métriques que nous suivons en interne:

  • Précision à la première tentative: À quelle fréquence la première réponse de Claude a-t-elle besoin de zéro corrections? Un bon CLAUDE.md obtient cela au-dessus de 80%.
  • Violations de convention: Comptez combien de fois Claude viole vos normes de codage. Devrait tendre vers zéro.
  • Questions de contexte: Si Claude continue à demander « quel framework c'est? » ou « devrais-je utiliser App Router? », votre CLAUDE.md manque d'information.
  • Fréquence d'annulation: À quelle fréquence vous devez rejeter ou annuler les changements de Claude. Moins c'est mieux.

Une équipe d'une startup de taille moyenne a signalé réduire leur temps moyen de tâche assistée par IA de 12 minutes à 4 minutes après avoir investi une heure dans leur CLAUDE.md. C'est une amélioration 3x d'un seul fichier.

Si vous construisez un projet avec nous via nos services de développement CMS headless, nous incluons un CLAUDE.md sur mesure dans chaque remise de projet. C'est tellement important pour la vélocité de développement continue.

FAQ

Qu'est-ce que CLAUDE.md et où le mettre? CLAUDE.md est un fichier markdown placé à la racine de votre dépôt de projet. Claude Code le lit automatiquement au début de chaque session pour comprendre l'architecture de votre projet, les conventions, la stack technologique, et les contraintes. Pensez à cela comme un document d'intégration écrit spécifiquement pour votre assistant de codage IA.

Quelle devrait être la longueur d'un fichier CLAUDE.md? Viser pour 300-800 mots. Les fichiers plus courts manquent de contexte critique, mais tout ce qui dépasse 1 000 mots commence à consommer votre fenêtre contextuelle — de l'espace mieux utilisé pour le raisonnement du code réel. Soyez concis et spécifique. Chaque phrase doit mériter sa place. Si vous avez besoin de plus de profondeur, lien vers la documentation externe plutôt que de l'intégrer.

Devrais-je commiter CLAUDE.md au contrôle de version? Absolument. CLAUDE.md devrait être traité comme n'importe quelle autre documentation de projet — versionné, examiné, et tenu à jour. Toute votre équipe bénéficie du comportement IA cohérent. Les préférences personnelles vont dans ~/.claude/CLAUDE.md à la place, qui reste local à la machine de chaque développeur.

En quoi CLAUDE.md diffère de .cursorrules? Le contenu est presque identique — les deux fournissent le contexte du projet à un outil de codage IA. La différence est quel outil les lit. CLAUDE.md est pour Claude Code (outil CLI d'Anthropic), tandis que .cursorrules est pour Cursor IDE. Si vous utilisez les deux outils, maintenez une seule source de vérité et copiez-la aux deux fichiers, en ajustant pour tout formatage spécifique à l'outil.

Quelle est la section la plus importante d'un CLAUDE.md? La section « À NE PAS FAIRE ». Les instructions négatives sont disproportionnément efficaces avec les modèles IA. Dire à Claude ce qu'il faut éviter — ne pas utiliser les types any, ne pas ajouter inutilement « use client », ne pas installer de nouveaux paquets sans demander — prévient les erreurs les plus courantes et frustrantes. Une bonne liste de bannissement économise plus de temps que des pages d'instructions positives.

Puis-je utiliser CLAUDE.md pour des projets non-code? Oui. CLAUDE.md fonctionne pour n'importe quel projet où vous interagissez avec Claude Code. J'ai vu des projets efficaces pour les dépôts de documentation, les projets infrastructure-as-code, et même les pipelines d'analyse de données. Le principe est le même: donnez à Claude le contexte qu'il faut pour prendre de bonnes décisions sur votre projet spécifique.

À quelle fréquence devrais-je mettre à jour mon CLAUDE.md? L'examiner à chaque grand refactoring et au moins une fois par sprint. Si vous mettez à niveau une version de framework, changez une dépendance clé, ou adoptez une nouvelle convention, mettez à jour le fichier immédiatement. Un contexte obsolète est pire que pas de contexte parce qu'il trompe activement l'IA. Certaines équipes ajoutent une révision CLAUDE.md à leur liste de vérification PR pour les changements d'infrastructure.

Est-ce que CLAUDE.md fonctionne avec Claude sur le web (claude.ai)? Non. CLAUDE.md est spécifiquement lu par Claude Code, l'outil de codage basé sur CLI. Si vous utilisez Claude via l'interface web ou l'API, vous devriez coller le contexte manuellement ou utiliser la fonctionnalité Projects pour l'attacher comme fichier de connaissances. Le chargement automatique de Claude Code est ce qui rend le fichier si puissant — zéro friction, chaque session.