Le guide complet pour rédiger un CLAUDE.md : Bonnes pratiques de configuration de projet

Qu’est-ce que CLAUDE.md ?

CLAUDE.md est un fichier de contexte qui aide Claude Code à comprendre votre projet. Placez-le à la racine de votre projet, et Claude Code le lit automatiquement au début de chaque session. Un CLAUDE.md bien rédigé peut considérablement améliorer la qualité des réponses de Claude Code.

Emplacements du fichier et priorité

Vous pouvez placer des fichiers CLAUDE.md à plusieurs endroits, et tous sont chargés :

~/.claude/CLAUDE.md          # Paramètres globaux (partagés entre tous les projets)
./CLAUDE.md                   # Racine du projet (partagé avec l'équipe)
./CLAUDE.local.md             # Paramètres locaux (à ajouter au .gitignore)
./src/CLAUDE.md               # Paramètres au niveau d'un sous-répertoire

• Global : Vos préférences personnelles de style de code
• Racine du projet : Règles partagées de l’équipe et stack technologique
• Local : Paramètres personnels non versionnés dans Git
• Sous-répertoire : Contexte supplémentaire pour des modules spécifiques

Modèle de départ

Voici un modèle pratique de CLAUDE.md :

# Présentation du projet

API backend e-commerce. Gère les commandes, l'inventaire et l'authentification des utilisateurs.

## Stack technologique

- Langage : TypeScript 5.x
- Runtime : Node.js 22
- Framework : Fastify
- BDD : PostgreSQL 16 + Prisma ORM
- Tests : Vitest
- CI : GitHub Actions

## Structure des répertoires

src/
  routes/       # Définitions des endpoints d'API
  services/     # Logique métier
  repositories/ # Couche d'accès aux données
  middleware/   # Authentification, logging, gestion des erreurs
  utils/        # Fonctions utilitaires
  types/        # Définitions de types

## Conventions de code

- Utiliser les fonctions fléchées
- Toujours utiliser try-catch pour la gestion des erreurs avec des classes d'erreur personnalisées
- Nommage : camelCase (variables/fonctions), PascalCase (types/classes)
- Noms de fichiers : kebab-case
- Utiliser l'alias de chemin `@/` au lieu des imports relatifs

## Commandes courantes

- Lancer les tests : `npm test`
- Vérifier les types : `npx tsc --noEmit`
- Lint : `npm run lint`
- Migration BDD : `npx prisma migrate dev`
- Serveur de développement : `npm run dev`

## Règles importantes

- Toujours créer une migration après avoir modifié prisma/schema.prisma
- Chaque endpoint d'API doit avoir un schéma de validation Zod
- Enregistrer les nouvelles routes dans routes/index.ts

Conseils pour rédiger des fichiers CLAUDE.md efficaces

1. Restez concis

CLAUDE.md consomme des tokens de la fenêtre de contexte. Évitez les explications verbeuses et privilégiez les listes à puces.

# Mauvais exemple
Ce projet utilise TypeScript. TypeScript est un langage développé
par Microsoft qui ajoute des types à JavaScript...

# Bon exemple
- Langage : TypeScript 5.x (mode strict)

2. Documentez ce que vous ne voulez pas

Lister explicitement les anti-patterns est étonnamment efficace.

## Interdit

- Pas de types `any`
- Pas d'exports par défaut (exports nommés uniquement)
- Pas de console.log pour le débogage (utiliser le logger)
- Ne jamais supprimer ni ignorer les tests existants

3. Définissez des workflows

Guidez Claude Code sur la manière d’aborder les tâches.

## Ajouter une nouvelle fonctionnalité

1. Créer les définitions de types dans `src/types/`
2. Implémenter la couche d'accès aux données dans `src/repositories/`
3. Implémenter la logique métier dans `src/services/`
4. Définir les endpoints dans `src/routes/`
5. Écrire des tests unitaires pour chaque couche
6. Vérifier que tous les tests passent avec `npm test`

4. Capturez le savoir tribal

Documentez les informations importantes qui ne sont écrites nulle part ailleurs.

## Notes spécifiques au projet

- `user_id` utilise UUID v7 (pour un tri chronologique)
- Tous les calculs de prix doivent utiliser `Decimal.js` (pour éviter les erreurs de virgule flottante)
- Les variables d'environnement sont centralisées dans `src/config.ts` — ne jamais accéder directement à process.env

Utilisation en équipe

Configuration du .gitignore

Gardez les paramètres personnels hors du contrôle de version :

# .gitignore
CLAUDE.local.md

Inclure dans les revues de code

Traitez CLAUDE.md comme un document de projet important. Incluez-le dans les revues de PR et tenez-le à jour en équipe.

Quand mettre à jour CLAUDE.md

• Lors de l’ajout d’une nouvelle bibliothèque
• Lors d’un changement de conventions de code
• Lors d’une restructuration des répertoires
• Lorsque vous remarquez que Claude Code commet la même erreur de façon répétée

Conclusion

CLAUDE.md transforme Claude Code en expert de votre projet spécifique. Commencez par générer une structure de base avec /init, puis affinez-la au fil du temps. Partagez-la avec votre équipe pour que tout le monde bénéficie d’interactions optimisées avec Claude Code.