CLAUDE.md : bonnes pratiques pour configurer Claude Code
Comment écrire un bon fichier CLAUDE.md pour Claude Code. Exemples concrets, structure recommandée et erreurs à éviter.
Le fichier CLAUDE.md, c’est quoi ?
Le fichier CLAUDE.md est le fichier d’instructions que Claude Code lit automatiquement au démarrage de chaque session. C’est l’équivalent d’un briefing que vous donneriez à un nouveau développeur qui rejoint votre projet : contexte, conventions, pièges à éviter, commandes utiles.
Sans CLAUDE.md, Claude Code fonctionne quand même. Mais avec un bon fichier d’instructions, la différence est énorme : moins de questions, des réponses plus précises, du code qui respecte vos conventions dès le premier essai.
Où placer le fichier
Claude Code cherche les fichiers d’instructions à plusieurs endroits, dans cet ordre de priorité :
~/.claude/CLAUDE.md- instructions globales, valables pour tous vos projets (votre style de code, préférences générales)CLAUDE.mdà la racine du projet - instructions spécifiques au projet (stack, conventions, structure)CLAUDE.mddans les sous-répertoires - instructions spécifiques à un module (utile pour les monorepos)
Les instructions se cumulent. Le fichier global définit vos préférences générales, le fichier projet les affine.
~/.claude/CLAUDE.md → "Je préfère les fonctions fléchées et TypeScript strict"
mon-projet/CLAUDE.md → "Ce projet utilise Next.js 15, Prisma, et PostgreSQL"
mon-projet/packages/api/CLAUDE.md → "Cette API suit le pattern controller/service/repository"Structure recommandée
Un bon CLAUDE.md couvre ces sections, dans cet ordre :
1. Contexte du projet
Décrivez le projet en deux à trois phrases. Ce qu’il fait, pour qui, et dans quel état il est (MVP, production, en refactoring).
# Mon Projet
Application SaaS de gestion de factures pour les freelances.
Stack : Next.js 15, Prisma, PostgreSQL, Stripe.
En production depuis janvier 2026, environ 500 utilisateurs actifs.2. Commandes essentielles
Les commandes que Claude Code doit connaître pour travailler sur le projet :
## Commandes
- `npm run dev` - serveur de développement
- `npm run build` - build de production
- `npm run test` - lance tous les tests (vitest)
- `npm run test:unit` - tests unitaires uniquement
- `npm run lint` - vérification du code
- `npm run db:migrate` - appliquer les migrations Prisma3. Structure du projet
Expliquez l’arborescence, surtout si elle n’est pas standard :
## Structure
src/
├── app/ # Routes Next.js (App Router)
├── components/ # Composants React réutilisables
├── lib/ # Logique métier et utilitaires
│ ├── db/ # Prisma client et queries
│ ├── stripe/ # Intégration Stripe
│ └── auth/ # NextAuth configuration
├── hooks/ # Custom React hooks
└── types/ # Types TypeScript partagés4. Conventions de code
Soyez spécifique. “Écrire du code propre” ne veut rien dire. “Les composants utilisent des named exports, pas de default export” est actionnable.
## Conventions
- TypeScript strict, pas de `any`
- Composants React : named exports, pas de default export
- Fichiers de test : `nom-du-fichier.test.ts` dans le même répertoire
- Noms de variables et fonctions en anglais, commentaires en français
- Prisma : une query par fonction, nommée `getXxx`, `createXxx`, `updateXxx`
- Pas de console.log en production, utiliser le logger (`lib/logger.ts`)5. Règles strictes
Les choses à ne jamais faire. Claude Code respecte bien les interdictions explicites :
## Règles
- NE JAMAIS modifier les fichiers de migration Prisma existants
- NE JAMAIS commit les fichiers .env
- Toujours ajouter des tests pour les nouvelles fonctions dans lib/
- Les changements d'API nécessitent une mise à jour du fichier openapi.yamlExemples concrets par type de projet
Projet Next.js
# Invoicr - SaaS Facturation
App de facturation pour freelances. Next.js 15 (App Router), Prisma, PostgreSQL, Stripe.
## Commandes
- `npm run dev` - dev server (port 3000)
- `npm run build` - build prod
- `npm run test` - vitest
- `npm run lint` - eslint + prettier check
- `npx prisma studio` - UI base de données
## Conventions
- App Router uniquement, pas de Pages Router
- Server Components par défaut, "use client" seulement quand nécessaire
- Fetching de données dans les Server Components, pas de useEffect pour les données initiales
- Validation des inputs avec Zod dans les Server Actions
- Styles avec Tailwind CSS, pas de CSS modules
## Structure importante
- `src/app/(auth)/` - routes authentifiées (layout avec sidebar)
- `src/app/(public)/` - routes publiques (landing, pricing)
- `src/lib/db/queries/` - toutes les requêtes Prisma
- `src/lib/stripe/` - webhooks et helpers Stripe
## Règles
- Les Server Actions sont dans des fichiers séparés (`actions.ts`)
- Chaque route API retourne un type `ApiResponse<T>`
- Pas de fetch côté client pour les données qui peuvent être en Server ComponentProjet Python / FastAPI
# DataPipeline API
API de traitement de données pour clients B2B. FastAPI, SQLAlchemy, Celery, Redis.
## Commandes
- `uv run fastapi dev` - serveur de dev
- `uv run pytest` - tous les tests
- `uv run pytest -x` - arrêter au premier échec
- `uv run ruff check .` - linter
- `uv run alembic upgrade head` - migrations
## Conventions
- Python 3.12+, type hints obligatoires partout
- Architecture : router -> service -> repository
- Un fichier par router dans `app/routers/`
- Les modèles SQLAlchemy dans `app/models/`, un fichier par table
- Les schémas Pydantic dans `app/schemas/`, miroir des models
- Docstrings en français pour les fonctions publiques
- Tests : un fichier test par module, fixtures dans `conftest.py`
## Règles
- NE PAS utiliser `from sqlalchemy import *`
- Les tâches longues passent par Celery, jamais en synchrone dans un endpoint
- Chaque endpoint a un test d'intégration minimum
- Les secrets sont dans les variables d'environnement, jamais en durMonorepo
# Plateforme Acme
Monorepo turborepo. Frontend React + API Node + packages partagés.
## Structure
packages/
├── web/ # Frontend React (Vite)
├── api/ # Backend Express
├── shared/ # Types et utilitaires partagés
├── ui/ # Design system (composants React)
└── config/ # Configs partagées (ESLint, TypeScript)
## Commandes
- `turbo dev` - lance web + api en parallèle
- `turbo build` - build tous les packages
- `turbo test` - lance tous les tests
- `cd packages/web && npm run dev` - frontend seul
- `cd packages/api && npm run dev` - API seule
## Conventions
- Les types partagés sont dans `packages/shared/src/types/`
- Les imports entre packages utilisent les alias workspace (`@acme/shared`)
- Chaque package a son propre `tsconfig.json` qui étend `packages/config/`
- Les composants UI sont dans `packages/ui/`, documentés avec Storybook
## Règles
- NE PAS importer directement depuis un autre package (utiliser l'alias)
- Les changements dans `shared` nécessitent de vérifier les consumers
- Un changement d'API doit être rétrocompatible ou versionnéErreurs courantes à éviter
Le CLAUDE.md trop long
Au-delà de 200 lignes, l’efficacité diminue. Claude Code a une fenêtre de contexte limitée, et un fichier d’instructions trop volumineux réduit la place disponible pour votre conversation. Soyez concis, chaque ligne doit apporter de l’information utile.
Le CLAUDE.md trop vague
“Écrire du bon code” ou “Suivre les bonnes pratiques” n’aide pas. Claude Code sait déjà écrire du code correct. Ce qui l’aide, ce sont les instructions spécifiques à votre projet : vos conventions, vos patterns, vos outils.
Mauvais :
- Écrire du code propre et maintenable
- Suivre les bonnes pratiques ReactBon :
- Composants < 150 lignes, sinon découper
- État local avec useState, état partagé avec Zustand (pas de Redux)
- Les formulaires utilisent react-hook-form + zodLes instructions contradictoires
Si votre CLAUDE.md dit “utiliser des named exports” et que votre ESLint impose des default exports, Claude Code va produire du code qui échoue au lint. Alignez vos instructions avec votre configuration réelle.
Dupliquer ce qui est déjà dans le code
Pas besoin de lister toutes vos dépendances - elles sont dans package.json. Pas besoin de décrire votre schéma de base - il est dans vos migrations. Concentrez-vous sur ce que le code ne dit pas : le pourquoi, les conventions implicites, les décisions d’architecture.
Le répertoire .claude/
Au-delà du fichier CLAUDE.md, Claude Code reconnaît un répertoire .claude/ à la racine du projet :
.claude/
├── commands/ # Commandes slash personnalisées
│ ├── deploy.md # Accessible via /project:deploy
│ └── review.md # Accessible via /project:review
└── agents/ # Agents spécialisés
└── reviewer.md # Agent de review de codeCommandes personnalisées
Chaque fichier .md dans commands/ devient une commande slash. Par exemple, commands/deploy.md :
Déploie l'application en production :
1. Lance les tests avec `npm run test`
2. Si les tests passent, lance `npm run build`
3. Si le build réussit, lance `npm run deploy`
4. Vérifie que le healthcheck répond sur l'URL de productionUtilisable ensuite avec /project:deploy dans Claude Code.
Agents
Les fichiers dans agents/ définissent des agents spécialisés avec un rôle et des instructions précises. Utile pour des tâches récurrentes comme la review de code ou la génération de documentation.
Conseils avancés
Mettez à jour le CLAUDE.md régulièrement. Votre projet évolue, vos conventions aussi. Un CLAUDE.md obsolète fait plus de mal que de bien. Prenez 5 minutes chaque semaine pour le synchroniser avec la réalité du projet.
Utilisez /init comme point de départ. La commande génère un CLAUDE.md basique en analysant votre projet. C’est toujours mieux que de partir de zéro, même si vous allez le réécrire à 80%.
Testez vos instructions. Après avoir modifié votre CLAUDE.md, posez une question qui devrait être influencée par vos nouvelles instructions. Vérifiez que Claude Code les applique correctement.
Gardez un ton direct. Claude Code n’a pas besoin de politesse ni de contexte émotionnel. “Pas de console.log” est plus efficace que “Merci de ne pas utiliser console.log dans le code de production s’il te plaît”.
Priorisez les règles critiques. Mettez les interdictions et les règles les plus importantes en haut du fichier. Si le contexte est tronqué, ce sont ces règles qui seront préservées en priorité.