Claude Code CLAUDE.md : La documentation qui code avec vous

Chaque projet a sa spécificité. Ses conventions. Ses pièges. Ses “on a toujours fait comme ça” que personne n’a jamais documentés.

Le fichier CLAUDE.md est l’endroit où tu captures tout ça pour que Claude Code travaille comme toi — pas comme un développeur générique qui découvre le projet.

CLAUDE.md vs README.md

README.md	CLAUDE.md
Pour les humains	Pour Claude Code
Comment installer le projet	Comment travailler dans le projet
Stack technique générale	Conventions et patterns spécifiques
Une fois lu, on n’y revient pas	Chargé automatiquement à chaque session

Le README explique ce qu’est le projet. Le CLAUDE.md explique comment y contribuer.

Où placer CLAUDE.md

Deux options :

1. À la racine du projet : ./CLAUDE.md — pour les conventions spécifiques au repo
2. Global : ~/.claude/CLAUDE.md — pour tes préférences personnelles (langue, outils, workflow)

Les deux sont chargés automatiquement. Le local override le global en cas de conflit.

La structure qui fonctionne

Après avoir testé différentes configurations sur plusieurs projets, voici la structure optimale :

# CLAUDE.md — Project Name

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Framework: Next.js 15
- Database: PostgreSQL + Prisma
- Testing: Vitest + Playwright
- Styling: Tailwind CSS

## Commands
- Dev: `bun dev`
- Test: `bun test`
- Build: `bun run build`
- Lint: `bun run lint`

## Conventions

### Code Style
- Imports: triés alphabétiquement
- Components: un fichier = un composant exporté par défaut
- Types: interfaces préférées aux types

### Naming
- Components: PascalCase
- Functions: camelCase
- Files: kebab-case
- Constants: SCREAMING_SNAKE_CASE

### Git
- Branches: feat/fix/refactor/docs/test/chore
- Commits: conventional commits

## Architecture

### Key Files
- `src/app/` — App Router pages
- `src/components/` — Composants réutilisables
- `src/lib/` — Utilitaires et helpers
- `src/types/` — Types TypeScript partagés

### Patterns
- Server Components par défaut
- Client Components uniquement si nécessaire (useState, useEffect)
- Actions dans `src/actions/`

## Known Pitfalls
- Ne pas modifier `src/lib/db.ts` directement
- Toujours utiliser `cn()` pour les classes conditionnelles
- Les tests E2E ont besoin de la DB running

## Context Métier
Ce projet est un SaaS de facturation pour les freelances.
Terms:
- "Invoice" = Facture client
- "Quote" = Devis
- "Expense" = Dépense professionnelle

Les sections essentielles

1. Language — OBLIGATOIRE

## Language
- Conversations: French
- Code & Commits: English

Claude Code parle la langue de tes conversations mais écrit le code et les commits en anglais. C’est le setup optimal pour les équipes francophones.

2. Stack — Pour les décisions techniques

## Stack
- Runtime: Bun
- Framework: Hono.js
- ORM: Drizzle
- Auth: Better Auth

Claude utilise cette info pour proposer des solutions cohérentes avec ta stack.

3. Commands — Pour ne pas chercher

## Commands
- Dev: `bun dev`
- Test: `bun test`
- DB Push: `bunx prisma db push`
- DB Generate: `bunx prisma generate`

Quand tu demandes “lance les tests”, Claude sait exactement quoi exécuter.

4. Conventions — Pour la cohérence

## Conventions

### Code Style
- Pas de `console.log` en production
- Imports triés par type (React, externe, interne)
- Composants: arrow functions

### Git
- Jamais de force push sur main
- Toujours créer une branche pour les features
- Commits: feat/fix/refactor/docs/test/chore

5. Known Pitfalls — Pour éviter les erreurs classiques

## Known Pitfalls
- Le middleware d'auth casse si pas dans l'ordre spécifique
- `useSearchParams()` nécessite Suspense boundary
- Les tests ont besoin de `DATABASE_URL` en env
- Ne pas utiliser `fetch()` côté serveur, utiliser `serverFetch()`

C’est la section la plus précieuse. Tu captures les heures de debugging en 5 lignes.

6. Context Métier — Pour les termes spécifiques

## Context Métier
Application de gestion pour restaurants.

Terms:
- "Table" = Table physique (pas DB table)
- "Service" = Service du midi/soir
- "Couvert" = Nombre de convives
- "Ticket" = Commande en cours

Business Rules:
- Un service fermé ne peut plus recevoir de commandes
- Les tickets doivent être clôturés avant la fermeture

Anti-patterns à éviter

Trop verbeux

## Architecture

Notre architecture est basée sur les principes de Clean Architecture
popularisés par Robert C. Martin. Nous utilisons une séparation en
couches avec la règle de dépendance qui stipule que les dépendances
ne peuvent pointer que vers l'intérieur...

Claude n’a pas besoin d’un cours d’architecture. Donne-lui les faits.

Trop générique

## Conventions
- Write clean code
- Follow best practices
- Use meaningful variable names

Ça n’apporte rien. Sois spécifique à ton projet.

Pas maintenu à jour

Un CLAUDE.md obsolète est pire que pas de CLAUDE.md. Si tu changes de convention, mets-le à jour.

Exemples réels

Projet Next.js + Prisma

# CLAUDE.md — SaaS Dashboard

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Next.js 15 (App Router)
- PostgreSQL + Prisma
- Auth: Better Auth
- UI: shadcn/ui + Tailwind

## Commands
- Dev: `bun dev`
- Test: `bun test`
- DB: `bunx prisma db push && bunx prisma generate`
- Build: `bun run build` (demander confirmation)

## Conventions
- Server Components par défaut
- 'use client' uniquement si nécessaire
- Actions dans `src/actions/`
- Types dans `src/types/`

## Known Pitfalls
- Ne pas modifier `prisma/schema.prisma` sans `bunx prisma generate`
- Les Server Actions doivent être async
- Middleware doit matcher les routes publiques

Projet Symfony + Vue

# CLAUDE.md — E-commerce Platform

## Language
- Conversations: French
- Code & Commits: English

## Stack
- Backend: Symfony 7 + API Platform
- Frontend: Vue 3 + Inertia.js
- Database: PostgreSQL
- Queue: RabbitMQ

## Commands
- Backend: `symfony server:start`
- Frontend: `bun dev`
- Tests: `php bin/phpunit`
- Queue: `php bin/console messenger:consume`

## Conventions
- API Platform resources dans `src/Entity/`
- Vue components dans `resources/js/components/`
- Tests: une classe = un fichier de test

## Known Pitfalls
- Cache Redis à vider après modif API Platform
- Inertia partage les props via middleware
- Les tests fonctionnels ont besoin de la DB de test

Règles automatiques (Auto-Loaded)

Claude Code charge automatiquement certains fichiers de règles :

Fichier	Trigger
rules/glm-delegator/glm-delegator.md	Expert routing
rules/planning/planning.md	Tâches complexes
rules/agent-teams/agent-teams.md	2+ agents parallèles

Tu peux créer tes propres règles auto-chargées dans ~/.claude/rules/.

Workflow de maintenance

1. Démarrage de projet : Créer un CLAUDE.md minimal
2. Après un piège rencontré : L’ajouter à “Known Pitfalls”
3. Après un changement de convention : Mettre à jour “Conventions”
4. Révision mensuelle : Supprimer ce qui n’est plus pertinent

Ce que ça change concrètement

Sans CLAUDE.md :

• Claude propose des solutions génériques
• Tu répètes les mêmes corrections
• Les erreurs classiques se répètent

Avec CLAUDE.md :

• Claude suit tes conventions du premier coup
• Les décisions d’architecture sont respectées
• Les pièges connus sont évités automatiquement

Le temps investit dans un bon CLAUDE.md est récupéré après 2-3 sessions de travail. C’est le ROI le plus élevé de tout ce que tu peux configurer dans Claude Code.