Bonnes Pratiques CLAUDE.md : Configurez Claude Code pour N'importe Quel Projet
CLAUDE.md est la configuration la plus impactante pour Claude Code. Un fichier bien rédigé transforme une assistance IA générique en expertise spécifique au projet.
CLAUDE.md est un fichier markdown à la racine de votre projet. Claude Code le lit au début de chaque session avant que vous ne tapiez quoi que ce soit. Un bon CLAUDE.md transforme une IA générique en un outil qui comprend les conventions, la stack technique et les limites de votre projet.
Que devez-vous inclure dans CLAUDE.md ?
Concentrez-vous sur les informations dont un développeur compétent rejoignant votre équipe aurait besoin dès le premier jour. Restez pratique : stack technique, commandes, conventions et choses à éviter.
Modèle CLAUDE.md minimal
# Contexte du Projet
App Next.js 14 avec TypeScript, Tailwind CSS et Prisma.
Base de données : PostgreSQL. Auth : NextAuth.js.
## Commandes
- `npm run dev` — démarrer le serveur de dev (port 3000)
- `npm run test` — lancer les tests Jest
- `npm run lint` — lancer ESLint
- `npm run db:migrate` — lancer les migrations Prisma
## Architecture
- Server components par défaut, client components dans /components/client/
- Routes API dans /app/api/ avec validation Zod
- Requêtes base de données dans /lib/db/ (jamais dans les composants)
## Conventions
- TypeScript mode strict, ne jamais utiliser `any`
- Tailwind pour le style, pas de CSS modules
- Conventional commits : feat:, fix:, chore:
## NE PAS
- Modifier les fichiers dans /legacy/ ou /vendor/
- Changer la configuration auth sans approbation explicite
- Ajouter de nouvelles dépendances sans demander d'abordQuelles sont les erreurs CLAUDE.md les plus courantes ?
| Erreur | Pourquoi c'est problématique | Solution |
|---|---|---|
| Trop long (500+ lignes) | Gaspille la fenêtre de contexte à chaque session | Garder sous 200 lignes, lier vers la doc pour les détails |
| Trop vague ("écrire du code propre") | Ne donne aucune guidance actionnable | Être spécifique : "Utiliser les server components par défaut" |
| Commandes manquantes | Claude devine comment lancer/tester/builder | Lister chaque script npm pertinent |
| Pas de restrictions | Claude peut modifier des fichiers sensibles | Ajouter une section "NE PAS" claire |
| Doublon du README | Le README est pour les humains, CLAUDE.md est pour l'IA | Se concentrer sur les conventions et règles, pas la description du projet |
Comment structurer CLAUDE.md pour les grands projets ?
Pour les grandes bases de code, utilisez la syntaxe @import pour répartir la configuration dans les répertoires. Claude Code suit les imports et construit une image complète.
# CLAUDE.md racine
## Conventions globales
- TypeScript strict, pas de `any`
- Toutes les routes API valident les entrées avec Zod
@import packages/api/CLAUDE.md
@import packages/web/CLAUDE.md
@import packages/shared/CLAUDE.mdChaque sous-CLAUDE.md contient les règles spécifiques à ce package. Cela garde le fichier racine court tout en donnant à Claude Code un contexte approfondi sur chaque zone de la base de code.
Comment générer CLAUDE.md automatiquement ?
Claude Code peut générer un CLAUDE.md de départ en analysant votre projet :
# Générer CLAUDE.md automatiquement
claude /init
# Cela crée un CLAUDE.md basé sur :
# - Les scripts package.json
# - La structure du projet
# - Les fichiers de configuration existants
# - Les patterns de l'historique gitCommencez avec /init, puis affinez manuellement. Le fichier auto-généré est un bon point de départ, mais il ne connaîtra pas les conventions non écrites de votre équipe. Ajoutez-les vous-même.
Qu'en est-il de la hiérarchie mémoire CLAUDE.md ?
Claude Code lit les fichiers CLAUDE.md depuis plusieurs emplacements, par ordre de priorité :
- +CLAUDE.md à la racine du projet (partagé par toute l'équipe)
- +Fichiers CLAUDE.md dans les sous-répertoires (via @import)
- +~/.claude/CLAUDE.md (vos préférences personnelles globales)
- +Auto Memory (MEMORY.md, géré par la commande /memory)
Les paramètres au niveau du projet ont la priorité sur les paramètres personnels. Cela signifie que les conventions d'équipe l'emportent toujours sur les préférences individuelles.