Votre assistant IA de codage ouvre votre repo pour la première fois. Il scanne la structure des fichiers, les dépendances, peut-être un README. Puis il suggère une config de routeur qui casse votre système de layout existant, importe un package que vous avez déprécié il y a trois sprints, et écrit des tests dans un style que votre équipe a abandonné l'année dernière. L'assistant n'est pas idiot — il est aveugle. Claude Code, Cursor, Copilot, Cody — chaque AI pair-programmer heurte le même mur : ils ne peuvent pas lire le contexte de votre équipe à partir de l'historique des commits seul. Un seul fichier CLAUDE.md à la racine de votre projet change cela. C'est la différence entre un assistant qui combat vos conventions et un qui les étend comme un dev senior qui livre avec vous depuis des mois. Mais la plupart des équipes écrivent des fichiers CLAUDE.md que l'IA ne peut pas réellement utiliser.

Si vous avez lancé des prompts à Claude Code et récupéré des résultats génériques, faux ou frustrantes, ce guide est pour vous. Je vais détailler exactement comment structurer votre CLAUDE.md, quoi inclure, quoi omettre, et partager des exemples réels issus de projets en production que nous avons lancé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 référentiel et que Claude Code lit automatiquement chaque fois qu'il démarre une session. Pensez-y comme de la documentation d'intégration pour votre AI pair programmer. Quand un nouveau développeur rejoint votre équipe, vous ne lui donnez pas simplement un ordinateur portable et ne dites pas « débrouille-toi ». Vous les guidez à travers l'architecture, expliquez les parties bizarres, 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 de quels fichiers il se trouve à lire. C'est comme demander à un nouvel embaucheur de comprendre l'intégralité de votre système en lisant des fichiers source aléatoires. Ils vont bien comprendre certaines choses, mais ils vont aussi faire des suppositions qui perdent à tout le monde du temps.

Avec un solide CLAUDE.md, j'ai vu la précision de réalisation des tâches passer d'environ 60% à plus de 90% à la première tentative. Ce n'est pas une petite amélioration — c'est la différence entre la programmation assistée par l'IA étant un multiplicateur de productivité et étant 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 importe car cela affecte comment 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 repo
  3. ./subdirectory/CLAUDE.md — Remplacements spécifiques au répertoire
  4. .claude/settings.json — Autorisations des outils spécifiques au projet et paramètres
  5. Contexte de session — Ce que vous dites à Claude dans la conversation actuelle

Le CLAUDE.md au niveau du projet est où vous passerez la plupart de votre temps. Le fichier global est bon pour les préférences personnelles (« Je préfère les composants fonctionnels » ou « toujours utiliser le mode strict TypeScript »), mais la vraie valeur est 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 de contexte limité. Si votre CLAUDE.md fait 5 000 mots de documentation bavarde, vous brûlez les tokens qui pourraient être utilisés pour le raisonnement du code réel. 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 — des apps Next.js, des sites Astro, des intégrations de CMS headless, des services API — j'ai atterri sur une structure cohérente qui fonctionne.

La structure idéale

# Nom du projet

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

## Stack technologique
Versions exactes et frameworks.

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

## Conventions clés
Normes de codage, modèles de nommage, règles d'organisation des fichiers.

## Commandes courantes
Commandes build, test, déploiement et dev.

## Contexte important
Stuff qui n'est pas évident dans le code.

## Problèmes connus / Pièges
Pièges à éviter.

## NE PAS
Choses explicites que l'IA ne devrait jamais faire.

Approfondissons chaque section.

Analyse section par section

Aperçu

Gardez cela à 2-3 phrases max. Claude n'a pas besoin de votre feuille de route produit — il a besoin de comprendre le domaine pour pouvoir prendre des décisions contextuellement appropriées.

## Aperçu
Ceci est le site marketing pour 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 juste « React » — spécifiez la version, le framework, la stratégie de rendu. Cela empêche Claude de suggérer des modèles qui fonctionnent en React 18 mais qui cassent en React 19, ou de recommander Pages Router quand vous êtes sur 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, uniquement 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 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 (conception atomique : 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 (colocalisés avec frontmatter)
- `public/` — Assets statiques (préférez next/image pour toutes les images)

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

Toutes les pages sont générées statiquement au moment du build sauf /blog/[slug]/preview qui utilise le mode draft.

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 named exports, jamais les default exports (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 générés automatiquement à partir du schéma Sanity
- Utilisez l'utilitaire `cn()` (lib/utils.ts) pour la fusion conditionnelle de classes, pas les template literals
- Les error boundaries enveloppent chaque section majeure de page, pas la page entière
- Toute gestion de formulaires 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 va deviner, et il va souvent deviner 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 changements de schéma
- `pnpm db:migrate` — Exécuter les migrations Drizzle ORM

Contexte important

C'est pour les stuff que Claude ne peut pas comprendre en lisant votre code. Logique métier, contraintes externes, choses qui prendraient 30 minutes à un relecteur humain à expliquer.

## Contexte important
- Nous utilisons ISR (revalidate: 3600) pour toutes les pages CMS. N'utilisez jamais `force-dynamic` sauf si c'est absolument nécessaire.
- Le webhook Sanity à /api/revalidate gère la revalidation à la demande — n'ajoutez pas 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'auth est géré par Clerk — ne construisez jamais de flux auth personnalisés.
- Le endpoint /api/leads a un rate limiting via Upstash Redis. Ne supprimez pas le middleware de rate limit.

Problèmes connus / Pièges

Chaque projet a du stuff bizarre. Mettez-le ici pour que Claude n'y trébuche pas.

## Problèmes connus / Pièges
- Le renderer de texte portable 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 inline à la place
- Les rewrites vercel.json pour /docs/* proxifient vers notre site de docs Mintlify. Ne modifiez pas ces derniers sans vérifier auprès de l'équipe.
- Les variables d'environnement préfixées avec NEXT_PUBLIC_ sont les seules disponibles côté client. Ne jamais exposer les secrets API de cette façon.

La section « NE PAS »

Cela pourrait être le plus important. Les instructions négatives sont incroyablement efficaces avec les modèles IA.

## NE PAS
- 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 les choses qui peuvent être faites dans les Server Components
- Ne pas modifier les fichiers de schéma Sanity sans confirmer le plan de migration
- Ne pas utiliser `"use client"` à moins que le composant ait réellement besoin d'APIs du navigateur ou de handlers d'événements
- Ne pas écrire de fichiers CSS — tout c'est les classes utilitaires Tailwind
- Ne pas hardcoder les chaînes qui devraient venir du CMS

Exemples réels de CLAUDE.md

Exemple : Site Marketing Next.js

Ceci 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 la récupération de données dans les server components via requêtes GROQ dans lib/sanity/queries.ts. Les client components uniquement pour les éléments interactifs (modales, formulaires, carousels).

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

## Conventions
- Named exports 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
- Ajouter "use client" sans justification
- Installer des paquets sans demander
- Utiliser les default exports 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.

# Tech Blog — Astro

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

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

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

## Règles clés
- Défaut sur les composants Astro (.astro). Utilisez React uniquement pour les îles qui ont besoin d'interactivité.
- client:visible pour les composants interactifs below-fold
- client:idle pour les composants interactifs non critiques
- N'utilisez jamais la directive client:load à moins que ce soit absolument nécessaire
- Toutes les images utilisent le composant Image d'Astro avec les dimensions appropriées
- Le flux RSS se génère automatiquement à partir de la collection de contenu — ne construisez pas de logique de flux manuelle

## NE PAS
- Ajouter des composants React quand un composant Astro suffirait
- Utiliser la directive client:load
- Oublier les dimensions des images (cause du CLS)
- Modifier le schéma de collection de contenu sans mettre à jour le frontmatter existant

Erreurs courantes qui détruisent votre contexte IA

J'ai examiné beaucoup de fichiers CLAUDE.md à ce stade. Voici les modèles qui conduisent régulièrement à de mauvais résultats.

Erreur Pourquoi ça nuit Correction
Trop long (2000+ mots) Brûle les tokens de fenêtre de contexte, l'info clé se perd Gardez moins de 800 mots. Liez vers la documentation externe pour les approfondissements.
Trop vague (« nous utilisons React ») Claude comble les lacunes avec des suppositions Soyez spécifique : versions, modèles, outils exacts
Pas d'instructions négatives Claude fait des choses « raisonnables » qui cassent vos conventions Toujours inclure une section « NE PAS »
Copy-paster du README.md Les READMEs sont pour les humains, pas le contexte IA Écrivez 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 N'mettez jamais les secrets dans CLAUDE.md. Référencez .env.example à la place
Ne jamais le mettre à jour Le projet évolue, le fichier de contexte ne l'est pas Examinez CLAUDE.md à chaque sprint ou refactorisation majeure
Instructions contradictoires « Utilisez les server components » + exemples avec useEffect fetching Une personne possède le fichier, examinez 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 du projet. Voici comment le paysage ressemble en 2026 :

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

La 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 l'information sont les mêmes — seul le nom du fichier et la mise en forme mineure diffèrent.

Si votre équipe utilise plusieurs outils IA (et beaucoup le font en 2026), 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 build peut copier votre fichier de contexte maître aux bons emplacements.

Modèles 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 sur lequel vous travaillez.

project/
├── CLAUDE.md              # Contexte global du projet
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Contexte spécifique à l'app web
│   └── api/
│       └── CLAUDE.md      # Contexte spécifique à l'API
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Contexte du design system

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

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 modèle qui fonctionne bien :

  1. Commencez avec CLAUDE.md chargé automatiquement
  2. Travaillez sur une fonctionnalité
  3. Exécutez /compact quand le contexte devient lourd
  4. Continuez — Claude garde 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 devrait être commité). Mais les développeurs individuels utilisent aussi ~/.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 du fichier complet
- J'utilise VS Code avec les keybindings Vim (ne suggérez pas de raccourcis spécifiques à l'IDE)

Cette séparation garde le fichier de l'équipe propre et axé 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 besoin de zéro corrections ? Un bon CLAUDE.md l'obtient au-dessus de 80%.
  • Violations de convention : Comptez combien de fois Claude casse vos normes de codage. Devrait tendre vers zéro.
  • Questions de contexte : Si Claude continue de demander « quel framework c'est ? » ou « devrais-je utiliser l'App Router ? », votre CLAUDE.md manque d'information.
  • Fréquence d'annulation : À quelle fréquence devez-vous rejeter ou rétablir les changements de Claude. Moins c'est mieux.

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

FAQ

Qu'est-ce que CLAUDE.md et où va-t-il ?

CLAUDE.md est un fichier markdown placé à la racine du référentiel de votre projet. Claude Code le lit automatiquement au début de chaque session pour comprendre l'architecture, les conventions, la stack technologique, et les contraintes de votre projet. Pensez-y comme un document d'intégration écrit spécifiquement pour votre assistant IA de codage.

Quelle longueur devrait avoir un fichier CLAUDE.md ?

Visez 300-800 mots. Les fichiers plus courts manquent le contexte critique, mais tout ce qui dépasse 1 000 mots commence à manger votre fenêtre de contexte — 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, liez vers la documentation externe plutôt que de l'incorporer.

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ée, examinée, et maintenue à jour. Toute votre équipe bénéficie d'un 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 est-il différent 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 (l'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 toute mise en forme spécifique à l'outil.

Quelle est la section la plus importante d'un CLAUDE.md ?

La section « NE PAS ». 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 "use client" inutilement, ne pas installer de nouveaux packages sans demander — empêche les erreurs les plus courantes et frustrantes. Une bonne liste d'interdictions économise plus de temps que des pages d'instructions positives.

Puis-je utiliser CLAUDE.md pour les projets non-code ?

Oui. CLAUDE.md fonctionne pour tout projet où vous interagissez avec Claude Code. J'ai vu des projets efficaces pour les repos de documentation, les projets d'infrastructure-as-code, et même les pipelines d'analyse de données. Le principe est le même : donner à Claude le contexte dont il a besoin pour prendre de bonnes décisions à propos de votre projet spécifique.

À quelle fréquence devrais-je mettre à jour mon CLAUDE.md ?

Examinez-le à chaque refactorisation majeure et au moins une fois par sprint. Si vous upgradez une version de framework, changez une dépendance clé, ou adoptez une nouvelle convention, mettez à jour le fichier immédiatement. Le contexte périmé est pire que pas de contexte parce qu'il induit activement l'IA en erreur. Certaines équipes ajoutent un examen CLAUDE.md à leur liste de vérification PR pour les changements d'infrastructure.

CLAUDE.md fonctionne-t-il 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 auriez besoin de coller le contexte manuellement ou d'utiliser la fonctionnalité Projects pour l'attacher en tant que fichier de connaissance. Le chargement automatique de Claude Code c'est ce qui rend le fichier si puissant — zéro friction, chaque session.