Sans CLAUDE.md, tu réexpliques ton projet à chaque session. Ici, tu le fais
écrire par Claude en une commande, puis tu apprends quoi y garder.
Le problème
Chaque nouvelle session avec Claude Code ressemble à l'arrivée d'un nouveau collègue le lundi matin. Il ne connaît ni ton projet ni tes habitudes. Il pose des questions, et ses choix changent d'une session à l'autre.
Résultat : tu passes 10 à 15 minutes par session à répéter les mêmes choses. Sur 10 sessions par jour, ça fait 2 heures perdues.
Un fichier de consignes
Un fichier texte rangé dans ton projet. Claude Code le lit tout seul au début de chaque session et le garde sous les yeux jusqu'à la fin. Tu y mets ce qu'il doit toujours savoir : à quoi sert le projet, avec quels outils il est construit, tes règles, les pièges déjà rencontrés.
Il existe à deux endroits :
- Dans ton projet : les consignes de ce projet. C'est lui qu'on construit dans ce chapitre.
- Dans ton dossier personnel (
~/.claude/CLAUDE.md) : tes préférences valables partout, par exemple « réponds-moi en français ».
Compte une demi-heure pour mettre ton CLAUDE.md au point. Ensuite, plus
besoin de rappels en début de session : Claude écrit dans le bon style dès sa
première réponse.
Le créer en une commande
Tu ne l'écris pas toi-même. Dans la conversation, tape :
/init
Claude parcourt ton projet, repère les outils utilisés et les commandes utiles, puis écrit un CLAUDE.md de départ. Tu le relis, et tu ajoutes ce qu'il ne peut pas deviner : à qui s'adresse ton app, ton vocabulaire, tes règles.
Si ton dossier est encore vide, /init n'a rien à lire. Donne-lui le contexte à la place :
"Je vais construire une app de [description] pour [qui]. L'interface sera en français. Écris un
CLAUDE.mdavec les conventions, l'organisation des fichiers, les commandes et les pièges à éviter."
Ce qu'on met dedans
Huit rubriques couvrent l'essentiel. /init en remplit une partie, tu complètes le reste au fil du projet.
| Rubrique | Ce que tu y mets | Exemple |
|---|---|---|
| Description | Ce que fait le projet, pour qui | « App de réservation pour un salon de coiffure » |
| Commandes | Comment lancer l'app et la vérifier | npm run dev lance l'app sur localhost:3000 |
| Stack | Les outils avec lesquels l'app est construite | Next.js, Supabase pour la base de données, Stripe |
| Organisation | Où ranger chaque type de fichier | « Les pages dans src/app, les composants dans src/components » |
| Style | Tes conventions d'écriture | « Noms de fichiers en minuscules avec des tirets » |
| Palette | Tes couleurs et leur usage | « Corail #E8634A pour les boutons, rien hors palette » |
| Vocabulaire | Les mots propres à ton métier | « Une "prestation" = un service réservable » |
| Pièges | Les erreurs déjà rencontrées, pour ne pas les refaire | « Toujours garder les clés d'API côté serveur » |
Les commandes sont indispensables : grâce à elles, Claude sait comment vérifier son propre travail. Sans elles, il ne sait pas quoi lancer.
Les pièges sont la rubrique qui rapporte le plus. Chaque erreur qui t'a coûté une heure, tu l'écris une fois, et Claude ne la refait plus.
Un vrai exemple : Panettone
J'ai construit Panettone, mon SaaS de personal branding pour freelances, en moins d'une semaine. Voici un extrait du CLAUDE.md qui tournait derrière :
# Panettone - SaaS Personal Branding pour Freelances
## Commandes
- npm run dev → Next.js dev sur localhost:3000
- npm run typecheck → Vérification TypeScript
- npx supabase migration up --local → Appliquer les migrations
## Stack
- Next.js 16 App Router, TypeScript strict, React 19
- Supabase (PostgreSQL, Auth, RLS, Storage)
- shadcn/ui + Tailwind CSS 4
- Stripe (Freemium + Pro)
- Anthropic Claude API pour l'IA
- Resend pour les emails
## Palette - "Dolce Vita"
- Primary (Corail doux): #E8634A - CTAs, éléments actifs
- Background (Ivoire): #FFFBF7 - fond de page
- Ne JAMAIS utiliser de couleurs hors palette
## Gotchas
- JAMAIS supabase db reset (détruit les données)
- Claude API : toujours côté serveur
- Interface en français avec accents corrects
Tu n'as pas besoin de comprendre chaque ligne. Retiens la forme : des titres, puis des listes courtes de règles claires.
Le faire évoluer
Le CLAUDE.md grandit avec ton projet. À chaque décision importante, demande à Claude de l'ajouter dans la bonne rubrique :
| Quand | Exemple de demande |
|---|---|
| Tu ajoutes un outil | "Ajoute Resend dans le CLAUDE.md, rubrique Stack" |
| Un bug revient | "Ajoute dans les pièges : ne jamais utiliser redirect() dans un try/catch" |
| Tu fixes une règle | "Ajoute : tous les formulaires affichent leurs erreurs sous le champ" |
| Un mot métier apparaît | "Ajoute la notion de 'Score de marque' dans le CLAUDE.md" |
C'est un simple fichier texte : tu peux aussi l'ouvrir et le modifier toi-même.
Quand la modif s'applique. Ça surprend souvent : tu ajoutes une règle en pleine session, et Claude continue comme avant. Normal, il a lu le fichier au démarrage. La nouvelle règle s'applique à la prochaine session (ou après /clear, qui vide la conversation). Si elle compte tout de suite, rappelle-la dans ton message.
Vise court. La doc officielle recommande de rester sous 200 lignes. Moi je vise 60 à 100. Au-delà, Claude suit moins bien les consignes, même écrites en majuscules. Et tout le fichier est renvoyé au modèle à chaque message, donc il occupe de la place pendant toute la session.
Quand il devient trop long
Quand ton fichier dépasse la centaine de lignes, deux rangements existent :
- Les rules : des fichiers de règles par thème (base de données, design, sécurité), rangés dans
.claude/rules/. Une rule peut ne se charger que quand Claude touche certains fichiers. - Les skills : des procédures longues (déployer, publier une version) que Claude ne charge que quand la tâche le demande. On en crée une au chapitre 8.
Pas besoin de tout faire à la main : « Mon CLAUDE.md est trop long. Déplace ce qui ne concerne que la base de données dans une rule, et propose-moi ce qui pourrait devenir une skill. »
Pour plus tard : les réglages précis
Charger une rule seulement sur certains fichiers. Ajoute un en-tête paths: en haut du fichier de la rule :
---
paths:
- "supabase/**"
- "src/lib/actions/**"
---
# Règles Supabase
- Toujours activer RLS sur une nouvelle table
- Régénérer les types après chaque migration
Ces règles n'entrent dans le contexte que quand Claude touche aux fichiers listés, ici la base de données et le code qui l'appelle. Une session sur le design ne les charge pas. Sans paths:, une rule se charge au démarrage, comme le CLAUDE.md. Les rules existent aussi au niveau global, dans ~/.claude/rules/.
Importer un autre fichier. Une ligne @docs/architecture.md dans le CLAUDE.md inclut ce fichier. Ça range, mais le fichier importé est chargé dès le démarrage, comme le reste.
Les consignes de compaction. Quand une conversation devient longue, Claude Code la résume pour libérer de la place (chapitre 6). Une rubrique Compact instructions lui dit quoi garder :
## Compact instructions
- Garde la liste des fichiers modifiés et les décisions d'architecture
- Garde les commandes de test qui échouent encore
- Jette les sorties de logs et les pistes abandonnées
Faire le ménage. /doctor prompt-audit passe en revue tes CLAUDE.md, rules et skills, et signale les consignes écrites pour d'anciens modèles.
Un AGENTS.md dans le projet ? C'est le fichier d'instructions d'autres agents de code. Claude Code le lit quand il n'y a pas de CLAUDE.md (chapitre 10).
Question
En pleine session, tu demandes à Claude d'ajouter une règle à ton CLAUDE.md. Il le fait. Quand est-ce que la règle s'applique ?
Choisis une réponse pour voir l'explication.
À retenir
- Lance
/initdès le début, puis demande à Claude d'ajouter chaque décision importante. - Sous 200 lignes (moi, je vise 60 à 100). Ce qui ne sert pas à chaque message part dans des rules ou des skills.
- Une règle ajoutée en pleine session s'applique à la session suivante.
Quiz de fin de partie
Partie 1 : Démarrer
6 questions. La partie est validée à partir de 5 bonnes réponses.