CLAUDE.md, le cerveau de ton projet

Le problème qu'il résout

Sans CLAUDE.md, chaque nouvelle conversation avec Claude Code est comme embaucher un nouveau développeur le lundi matin :

• Il ne connaît rien de ton projet
• Il ne sait pas quelles technologies tu utilises
• Il ne connaît pas tes conventions de code
• Il ne sait pas où ranger les fichiers
• Il va te poser 50 questions avant de commencer
• Il va faire des choix aléatoires qui seront incohérents d'une session à l'autre

Résultat : tu passes 10-15 minutes par session à re-expliquer les mêmes choses. Multiplie par 10 sessions par jour, et tu perds 2 heures de productivité pure.

La solution

Le CLAUDE.md est un fichier texte placé à la racine de ton projet que Claude Code lit automatiquement au début de chaque conversation. C'est ton brief permanent.

Imagine un document d'onboarding pour un nouveau développeur qui contiendrait : la stack technique, les conventions de code, l'architecture du projet, les commandes utiles, les pièges à éviter, le vocabulaire métier. Sauf qu'au lieu de le lire une fois et de l'oublier, Claude le relit instantanément à chaque session.

Comment le créer

Tu ne l'écris pas toi-même de zéro. Tu demandes à Claude de le générer, puis tu l'enrichis.

Étape 1, génération initiale

Si tu démarres un nouveau projet, donne le contexte à Claude :

"Je vais construire un SaaS de [description]. La stack sera Next.js + Supabase + Stripe. L'interface sera en français. Génère un CLAUDE.md complet avec les conventions, l'architecture, les commandes, et les pièges à éviter."

Si tu as déjà un projet existant :

"Analyse ce projet et génère un CLAUDE.md complet. Explore l'architecture, les conventions utilisées, la stack technique, et documente tout ce qu'un développeur devrait savoir pour être productif immédiatement."

Claude va explorer tous tes fichiers et produire un CLAUDE.md sur mesure.

Étape 2, enrichissement au fil du temps

À chaque décision importante, ajoute-la au CLAUDE.md :

• Nouvelle convention → ajoute-la dans "Style de code"
• Piège rencontré → ajoute-le dans "Gotchas"
• Nouvelle technologie → ajoute-la dans "Stack"
• Nouveau concept métier → ajoute-le dans "Concepts"

"Ajoute au CLAUDE.md qu'on utilise maintenant Resend pour les emails, et qu'on ne doit jamais envoyer plus de 3 000 emails par mois sur le plan gratuit."

Les 8 sections essentielles

1. Description du projet

Une phrase qui dit ce que c'est et pour qui.

# MonApp - SaaS de gestion de projets pour freelances

Claude utilise cette ligne pour comprendre le contexte métier de chaque décision.

2. Commandes

Comment lancer l'app, les tests, la base de données. Claude s'en sert pour vérifier automatiquement son travail.

## Commandes
- npm run dev → Lance l'app sur localhost:3000
- npm run build → Build de production
- npm run typecheck → Vérification des types TypeScript
- npm run lint → Vérification du style de code
- npm run test → Lancer les tests
- npx supabase migration up --local → Appliquer les migrations

3. Stack technique

Les technologies utilisées. Claude adapte son code en fonction.

## Stack
- Next.js 16 App Router, TypeScript strict, React 19
- Supabase (PostgreSQL, Auth, RLS, Storage)
- shadcn/ui + Tailwind CSS
- Stripe pour les paiements
- Resend pour les emails

4. Architecture des fichiers

Où ranger chaque type de fichier. Sans ça, Claude crée des fichiers n'importe où et ton projet devient un bazar.

## Architecture
- src/app/ → Pages et layouts (App Router)
- src/components/ → Composants réutilisables
- src/lib/actions/ → Logique métier serveur (Server Actions)
- src/lib/validators/ → Schémas de validation (Zod)
- supabase/migrations/ → Migrations SQL

5. Style de code

Les conventions de nommage et d'écriture. Garantit la cohérence entre toutes les sessions.

## Style de code
- Fichiers en kebab-case (ex: brand-profile.tsx)
- Pas de default export
- Server Components par défaut, 'use client' seulement si nécessaire
- Préférer les Server Actions aux API routes pour les mutations

6. Palette graphique

Si ton app a une identité visuelle définie, documente-la. Sinon, Claude utilisera des couleurs aléatoires.

## Palette
- Primary: #E8634A (corail) - boutons, liens actifs
- Background: #FFFBF7 (ivoire) - fond de page
- Ne JAMAIS utiliser de couleurs hors palette

7. Concepts métier

Le vocabulaire spécifique de ton app. Claude l'intègre dans le code, les noms de variables, et l'interface.

## Concepts
- "Streak" : nombre de semaines consécutives de publication
- "Capsule" : enregistrement vidéo/audio décliné en multi-format
- "Boussole" : matrice piliers x catégories x objectifs de contenu

8. Gotchas (pièges à éviter)

Les erreurs qui font perdre du temps. Claude les évite proactivement.

## Gotchas
- JAMAIS utiliser `supabase db reset` (détruit toutes les données)
- API keys IA : toujours côté serveur, JAMAIS exposer côté client
- Interface en français avec accents corrects (é, è, ê, à, ç)
- Le client Supabase server utilise cookies() - ne pas mettre en cache

Exemple réel, extrait du CLAUDE.md de Panettone

Voici un extrait réel du CLAUDE.md utilisé pour construire un SaaS complet de personal branding en moins d'une semaine :

# 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

Comment le faire évoluer

Le CLAUDE.md n'est pas figé. Il doit évoluer avec ton projet :

Splitter avec .claude/rules/ (pour les gros projets)

Quand ton CLAUDE.md grossit trop, la solution n'est pas de tout mettre dans docs/. Claude Code a un mécanisme dédié : le dossier .claude/rules/.

Le principe

Chaque fichier .md dans .claude/rules/ est une règle spécialisée que Claude charge automatiquement selon le contexte. C'est comme découper ton CLAUDE.md en chapitres thématiques.

.claude/rules/
  safety.md       → Ce qui est INTERDIT (rm -rf, sudo, db reset)
  supabase.md     → Patterns Supabase obligatoires
  nextjs.md       → Conventions Next.js
  changelog.md    → Mise à jour du CHANGELOG après chaque modification

Pourquoi c'est mieux qu'un gros CLAUDE.md

• Chargement contextuel : Claude charge les règles pertinentes au moment où il en a besoin, pas tout d'un coup
• Maintenance facile : chaque règle est indépendante, tu peux en ajouter ou modifier une sans toucher aux autres
• Pas de limite de lignes : le CLAUDE.md reste court (60-100 lignes), les détails sont dans les rules

Niveaux global et projet

Les rules existent à deux niveaux :

• ~/.claude/rules/ (global) : chargé dans TOUS tes projets. Idéal pour tes préférences personnelles (sécurité, style, outils)
• .claude/rules/ (projet) : chargé uniquement dans ce projet. Idéal pour les conventions spécifiques (schéma DB, roadmap, patterns métier)