Le fichier CLAUDE.md qui a changé ma productivité de 300%

3 mois à me battre avec Claude Code

Pendant 3 mois, chaque session Claude Code commençait pareil. J'ouvrais le terminal, je collais ma demande, et je passais les 15 premières minutes à tout réexpliquer. "Voilà la structure du projet. Voilà ma stack. Voilà comment je nomme les fichiers. Non, mets pas ça là. Non, utilise Provider, pas setState."

C'était comme embaucher un développeur brillant qui avait une amnésie totale chaque matin.

Puis j'ai découvert CLAUDE.md.

Qu'est-ce qu'un CLAUDE.md ?

Un fichier markdown à la racine de ton projet. C'est tout. Claude Code le lit automatiquement au début de chaque session.

Pense à ça comme un briefing permanent. Sans ce fichier, Claude Code est un junior brillant mais amnésique. Avec, c'est un senior qui connaît ton code par cœur.

Pas de plugin. Pas de config. Pas d'API. Juste un fichier nommé CLAUDE.md à la racine de ton projet.

Avant / Après (chiffres réels)

• Temps par feature : 2-3 heures → 30-45 minutes
• Erreurs de structure : Constantes → quasi zéro
• Refactoring majeur : Toutes les 2 semaines → 1 fois en 3 mois
• Frustration : 8/10 → 2/10

La première session après avoir mis le fichier en place, j'ai demandé "ajoute un écran settings avec dark mode toggle". Claude a créé le fichier dans lib/features/settings/, utilisé Provider, suivi ma convention de nommage, ajouté la route. Sans que je précise quoi que ce soit.

Les 3 sections critiques

1. Structure du projet (non-négociable)

Pas juste "il y a un dossier features/". Chaque sous-dossier avec son rôle. Chaque type de fichier avec sa localisation.

Mon erreur initiale : Une description de structure vague. Résultat : Claude mettait les fichiers n'importe où. Un service dans widgets/, un modèle dans screens/. Le chaos.

La solution : Un arbre complet avec commentaires. Maintenant Claude sait que les services API vont dans lib/core/services/, les écrans dans lib/features/{name}/screens/, et les modèles dans lib/features/{name}/models/.

2. Règles strictes (des ordres, pas des suggestions)

Pas "essaie d'utiliser const quand possible". Mais : "TOUJOURS const. JAMAIS var."

Mon erreur initiale : Des règles polies et flexibles. Résultat : Du code incohérent. Parfois const, parfois let. Parfois camelCase, parfois snake_case.

La solution : Des ordres directs sans ambiguïté. Claude suit les règles strictes parfaitement.

3. Patterns avec exemples (montre, n'explique pas)

Un snippet de 5 lignes montrant TON pattern d'appel API vaut plus que 3 paragraphes d'explication. Claude réplique les exemples parfaitement.

Mon erreur initiale : Pas d'exemples. Résultat : Claude improvisait un pattern différent à chaque fois.

La solution : 2-3 snippets de code réels de mon projet. Maintenant chaque nouveau service, chaque nouvel écran suit le même pattern.

Le vrai ROI (pas juste la vitesse)

• Cohérence : 47 fichiers, même pattern. Chaque écran, chaque service, chaque modèle suit la même architecture.
• Maintenabilité : J'ai laissé un projet pendant 2 mois. Au retour, tout était clair parce que le CLAUDE.md documentait chaque convention.
• Confiance : Plus peur des gros changements. Le CLAUDE.md est un garde-fou. Claude ne cassera pas ton architecture si les règles sont claires.

Comment créer le tien en 15 minutes

1. Ouvre ton projet, regarde la structure des dossiers
2. Liste ta stack (langage, framework, packages)
3. Définis la structure (chaque dossier, chaque type de fichier)
4. Écris 5-7 règles strictes (utilise l'impératif : "TOUJOURS", "JAMAIS")
5. Ajoute 2-3 patterns avec du code de ton vrai projet
6. Sauvegarde en CLAUDE.md à la racine

C'est tout. 15 minutes de travail pour des mois de temps gagné.

Les templates battle-tested

Les 4 variantes de mon CLAUDE.md (Flutter, Next.js, Python/FastAPI, Universel) sont dans le ByNeel Starter Kit — avec le guide complet, 15 prompts, et la checklist App Store.