CLAUDE.md : le fichier secret qui transforme Claude Code

Vous utilisez Claude Code mais vous avez l’impression de devoir tout ré-expliquer à chaque conversation ? Il y a un fichier magique pour ça : CLAUDE.md.

C’est quoi CLAUDE.md ?

CLAUDE.md est un fichier markdown que Claude Code lit automatiquement au démarrage de chaque conversation. Pensez-y comme la mémoire persistante de votre assistant IA.

Placez-le à la racine de votre projet, et Claude saura immédiatement :

• Quelle est l’architecture de votre projet
• Quelles conventions de code vous utilisez
• Quels sont les pièges à éviter
• Comment lancer les tests, builder, déployer

# Emplacement type
mon-projet/
├── CLAUDE.md    ← lu automatiquement
├── src/
├── package.json
└── ...

Que mettre dedans ?

Voici les sections les plus utiles, testées sur des dizaines de projets :

1. Contexte du projet

Donnez à Claude le “big picture” en 3-4 lignes. Pas besoin d’un roman.

## Contexte
Application SaaS de gestion immobilière.
Stack : Symfony 7 + React 18 + TypeScript.
API REST avec API Platform.

2. Conventions de code

Claude respectera vos conventions si vous les décrivez explicitement.

## Conventions
- Noms de variables en camelCase
- Composants React en PascalCase
- Un composant par fichier
- Tests unitaires avec Vitest

3. Commandes utiles

Évitez de retaper “lance les tests avec…” à chaque fois.

## Commandes
- Tests : `npm run test`
- Build : `npm run build`
- Lint : `npm run lint`
- Dev : `npm run dev`

4. Architecture et fichiers clés

Indiquez où se trouvent les choses importantes.

## Architecture
- API : `src/Controller/` (Symfony)
- Frontend : `src/components/` (React)
- Base de données : `src/Entity/` (Doctrine)
- Config : `.env.local`

Astuce avancée : les instructions négatives

Les instructions “ne fais PAS ça” sont souvent plus efficaces que les instructions positives :

## À ne pas faire
- Ne jamais modifier les fichiers dans `vendor/`
- Ne pas ajouter de commentaires JSDoc sauf si demandé
- Ne pas créer de fichiers README automatiquement
- Ne pas utiliser `any` en TypeScript

Pourquoi ça marche ? Claude a tendance à être proactif. Les instructions négatives canalisent cette énergie dans la bonne direction.

Taille idéale

Un bon CLAUDE.md fait entre 50 et 200 lignes. Au-delà, il y a un risque de dilution de l’attention (oui, même les IA ont ce problème).

Si vous avez beaucoup de contexte, créez des fichiers séparés et référencez-les :

## Documentation détaillée
- Architecture : voir `docs/ARCHITECTURE.md`
- API : voir `docs/API.md`
- Déploiement : voir `docs/DEPLOY.md`

L’erreur numéro 1

Ne mettez pas de contenu éphémère dans CLAUDE.md (tâches en cours, bugs du moment, etc.). Ce fichier doit contenir des vérités stables sur votre projet.

Pour les tâches temporaires, utilisez plutôt les conversations directement ou un fichier TODO.md séparé.

---

En résumé : CLAUDE.md, c’est le briefing que vous donneriez à un nouveau développeur qui rejoint votre équipe. Sauf que ce développeur le relit à chaque conversation et ne l’oublie jamais. Pas mal, non ?