CLAUDE.md est un simple fichier markdown à la racine de ton projet. Claude le lit automatiquement à chaque session. Au niveau du projet : ./CLAUDE.md. Global (tous les projets) : ~/.claude/CLAUDE.md. Le projet remplace le global : le fichier global contient tes valeurs par défaut, le fichier projet contient les spécificités de ce dépôt.
Pense-y comme au document d'intégration que tu donnes à un contractant hautement qualifié qui ne sait rien de ton projet. Sans cela, chaque session commence avec Claude qui devine ta pile, tes conventions de nommage et tes décisions passées. Les suppositions deviennent du code, le code devient des bugs. CLAUDE.md court-circuite cette chaîne. Un fichier est plus efficace qu'une invite intelligente car il fonctionne que tu t'en souviennes ou non.
Cinq sections qui valent le coup. Trois à six lignes de puces chacune :
1. Pile : frameworks, DB, authentification, e-mail, avec les versions. "Next.js 16, Postgres sur Neon, Resend pour les e-mails, Stripe pour les paiements, Supabase pour l'authentification."
2. Routes : où se trouvent les choses. "App dans /app, actions serveur dans /actions, API sous /app/api/v2, composants partagés dans /components/ui."
3. Conventions : règles évidentes pour toi, invisibles pour Claude. "Argent en cents (int), dates UTC, noms de fichiers en kebab-case, IDs en UUID v4."
4. Règles de sécurité : choses qui ne doivent jamais arriver. "Ne jamais loguer les clés API. Paramétrer toutes les requêtes SQL. Limiter le débit de tous les points de terminaison publics."
5. Ne fais pas ça : pièges dans lesquels tu es déjà tombé. "N'ajoute pas de dépendances sans demander. Ne lance pas de migrations depuis le local vers la production."
Un modèle travaillé. Remplace par les détails de ton projet réel :
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)Remarque la spécificité. "10/min par IP" est actionnable. "Utilise la limitation de débit" ne l'est pas.
L'erreur la plus coûteuse : des règles vagues qui semblent spécifiques.
Faible : "Gère l'argent avec soin." Claude gérera l'argent de la manière qu'il jugera la meilleure, ce qui pourrait ne pas correspondre à ton système.
Fort : "Tous les montants monétaires sont des entiers en cents. Jamais des flottants. N'affiche jamais les cents bruts ; divise par 100 et formate avec un symbole monétaire." Type de stockage, règle de traitement, règle d'affichage. Aucune ambiguïté.
La deuxième erreur : écrire des aspirations au lieu de contraintes. "Nous valorisons un code propre et lisible" est une aspiration. "Les fichiers de plus de 200 lignes sont divisés en modules" est une contrainte. Les aspirations nécessitent un jugement ; les contraintes produisent un comportement cohérent. Remplis ton CLAUDE.md de contraintes.
CLAUDE.md est un document vivant. Trois signaux qu'il a besoin d'être mis à jour :
Tu colles le même contexte dans une invite pour la deuxième fois. Si tu le répètes, il doit figurer dans CLAUDE.md.
Claude fait une erreur qu'une règle aurait pu empêcher. L'erreur est la règle. Écris-la avant la prochaine session.
Tu expliques une convention à un collègue. Si cela valait la peine d'être dit à voix haute, cela vaut la peine d'être chargé automatiquement.
Discipline de la longueur : trois à six puces par section ; au-delà de huit, divise la section. Un CLAUDE.md trop long pour être parcouru cesse de fonctionner car les règles importantes sont enfouies. Six lignes qui sont les bonnes six valent mieux que soixante lignes de remplissage.
Mise à l'échelle au-delà d'environ 300 lignes : divise en fichiers thématiques avec des inclusions @filename :
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdChaque fichier thématique reste ciblé ; la racine reste courte.
Commite CLAUDE.md dans le contrôle de version. Les règles deviennent révisables dans les PRs, et un nouveau coéquipier clone le dépôt avec Claude déjà configuré. Ajoute chaque règle "Ne fais pas ça" dans le même commit que le correctif de bug qui l'a enseignée. Une mise en garde : généralise les chemins spécifiques à la machine avant de commiter.
Qu'est-ce qui appartient à CLAUDE.md et qu'est-ce qui appartient à une invite ? Le rayon d'action. Si une règle empêche une classe d'erreurs qui coûte une heure ou plus à corriger, elle va dans CLAUDE.md. Les instructions spécifiques à la session restent dans les invites.
Crée ton premier CLAUDE.md en dix minutes. Donne cette invite à Claude :
"Je configure Claude Code pour un projet avec cette pile : [pile]. Conventions clés que quelqu'un de nouveau ne connaîtrait pas : [conventions]. Règles de sécurité qui ne doivent jamais être violées : [règles]. Choses qui ont déjà causé des bugs : [pièges]. Rédige un CLAUDE.md avec cinq sections : Pile, Routes, Conventions, Règles de sécurité, Ne fais pas ça."
Le premier brouillon te donne 80 pour cent. Affine-le avec ce que Claude a manqué ; les 20 pour cent restants sont ce qui est spécifique à ton expérience réelle avec le projet.
CLAUDE.md à la racine du projet charge ta pile, tes routes, tes conventions, tes règles de sécurité et tes pièges dans chaque session. Fichier global pour les valeurs par défaut inter-projets, fichier projet pour les remplacements. Des contraintes, pas des aspirations. Six bonnes lignes valent mieux que soixante. Mets-le à jour chaque fois que Claude fait une erreur qu'une règle écrite aurait pu empêcher.