CLAUDE.md : le fichier qui décuple Claude (quoi y mettre et quoi éviter)

Il y a une question qui sépare celui qui tire parti de Claude de celui qui se bat avec lui : lui réexpliques-tu ton projet chaque fois que tu ouvres une session ? Si la réponse est oui, tu laisses la moitié de la valeur sur la table. L'astuce, ce n'est pas d'écrire de meilleurs prompts. C'est d'écrire un fichier, une seule fois, que Claude lit automatiquement à chaque démarrage : le CLAUDE.md.

C'est le changement le moins cher et le plus rentable que tu puisses faire. Quatre lignes bien placées, et tu arrêtes de te répéter pour toujours. Ce guide parle de ce qu'il faut y mettre, de ce qu'il faut laisser dehors et de comment le structurer pour qu'il fonctionne vraiment.

Qu'est-ce que CLAUDE.md et pourquoi il décuple Claude

C'est un fichier texte au format Markdown que tu poses dans le dossier de ton projet. Rien de plus : du texte brut. Ce qui le rend spécial, c'est que Claude le lit automatiquement au démarrage de chaque session et traite son contenu comme des instructions de tête.

La différence avec un chat normal est brutale. Sans CLAUDE.md, chaque conversation repart de zéro : Claude ne sait pas ce qu'est ton projet, quel stack tu utilises, comment tu aimes qu'il écrive ni quels fichiers sont intouchables. C'est toi qui combles ce vide à la main, encore et encore, en gaspillant ton temps et son attention. Avec CLAUDE.md, ce contexte est déjà chargé avant que tu écrives un seul mot.

Voilà pourquoi il « décuple » : il ne rend pas Claude plus intelligent, il le rend plus à toi. Il arrête de deviner et démarre aligné sur ta façon de travailler. La première réponse de chaque session est déjà la bonne, pas la troisième.

Quoi y mettre (et quoi laisser dehors)

Voici l'erreur la plus courante : traiter le CLAUDE.md comme un fourre-tout où l'on entasse tout ce qu'on sait du projet. Mauvais réflexe. Tout ce que tu écris là-dedans occupe du contexte à chaque session et se dispute l'attention du modèle. Un fichier énorme dilue les instructions qui comptent vraiment.

La règle mentale est simple : des instructions opérationnelles et stables, pas de la documentation. Si quelque chose est stable (s'applique toujours) et opérationnel (change la façon dont Claude travaille), ça rentre. Si ça change chaque semaine ou ne sert que pour une tâche d'aujourd'hui, ça va dans le chat.

Ce qui va DEDANS :

• Ce qu'est le projet en une ou deux phrases. Le pour quoi, pas l'histoire.
• Comment tu veux qu'il travaille : ton, langue, niveau de détail, s'il doit demander l'autorisation avant de gros changements.
• Conventions : stack et commandes (projets de code), structure des dossiers, nomenclature, format de sortie.
• Interdictions explicites : quels fichiers ou zones il ne doit jamais toucher. C'est la section qui évite le plus d'erreurs et que presque tout le monde oublie.
• Raccourcis : commandes ou flux que tu répètes souvent (« pour déployer, on utilise X »).

Ce qui NE va PAS dedans :

• L'historique du projet ou des décisions déjà tranchées qui n'affectent pas le travail d'aujourd'hui.
• Une longue documentation qui vit déjà ailleurs (mieux : mets un lien ou dis où elle se trouve).
• Des instructions pour une seule tâche (« aujourd'hui, corrige ce bug ») : ça, c'est un prompt.
• Des secrets, des clés ou des mots de passe. Jamais.

Une structure recommandée

Il n'y a pas de format obligatoire, mais cette structure fonctionne parce qu'elle va du général au spécifique et place les règles dures là où Claude les voit. Quatre blocs :

1. À propos du projet — ce qu'il est et pour quoi, en quelques phrases.
2. Comment travailler — ton, langue, flux de validation, niveau de détail.
3. Conventions — stack, structure, commandes, format. Le concret.
4. Ne pas toucher — les interdictions explicites, bien visibles.

Garde chaque bloc court et en listes. Claude lit mieux cinq puces claires qu'un paragraphe dense. Et si ton projet grandit, divise : un CLAUDE.md général avec tes préférences globales et un par sous-projet avec ses détails. Les spécifiques s'ajoutent aux généraux, alors ne te répète pas : dans celui de la marque tu mets le ton, dans celui de chaque projet seulement ce qui change.

Modèle copiable

Voici le modèle de base. Copie-le, supprime ce qui ne s'applique pas et remplis les crochets. En deux minutes, tu as un CLAUDE.md meilleur que 95 % de ceux qui existent.

# [Nom du projet]

## À propos du projet
[Ce que c'est, en 1-2 phrases.] Je l'utilise pour [objectif principal].
Audience / contexte : [qui l'utilise ou pour qui c'est].

## Comment je veux que tu travailles
- Parle-moi en français, direct et sans détour.
- Avant tout changement important ou irréversible, montre-moi le plan et attends mon feu vert.
- Par défaut, des tâches petites et réversibles.
- Si quelque chose n'est pas clair, demande avant de supposer.

## Conventions
- Stack / outils : [langage, framework, apps].
- Structure : [où vit chaque chose].
- Commandes clés : [build / test / déploiement le cas échéant].
- Format de sortie : [comment tu veux les réponses].

## NE PAS toucher (important)
- [fichiers, dossiers ou zones intouchables].
- Ne supprime ni n'écrase jamais [X] sans prévenir d'abord.
- N'inclus aucun secret, aucune clé ni donnée sensible.

Trois exemples selon ton cas

Le modèle est le même ; ce qui change, c'est le remplissage. Trois cas réels.

Projet de code. Ici, la valeur est dans les conventions techniques. Stack et versions, commande de build et de tests, structure des dossiers, style de code (« utilise TypeScript strict, sans any »), et les interdictions critiques (« ne touche pas à migrations/, ne fais pas de push direct sur main »). Claude arrête d'inventer des commandes et respecte ton architecture dès le premier message.

Marque ou entreprise. Ici, ce qui compte, c'est la voix. Ton (« direct, pratique, sans remplissage, sans emojis »), quels mots employer et lesquels éviter, format des textes, langue, et règles de style (« ne promets jamais de résultats garantis »). Ce qui, en code, sont des conventions techniques, en marque ce sont des conventions de voix. Le résultat : tout ce qu'écrit Claude te ressemble, au lieu de sonner comme une IA générique.

Usage non technique. Organiser des documents, planifier, rédiger des courriels. Pas besoin de savoir programmer. Tu mets comment tu travailles (« range-moi toujours par date », « les résumés en puces, cinq points maximum »), tes dossiers habituels et ce qu'il ne faut pas toucher (« ne déplace rien du dossier Important sans me montrer d'abord ce que tu vas faire »). Même fichier, même effet : tu arrêtes d'expliquer l'évidence à chaque session.

L'erreur qui ruine un bon CLAUDE.md

L'écrire et l'oublier. Un CLAUDE.md est un document vivant : quand tu remarques que tu répètes une instruction dans le chat deux ou trois fois, cette instruction appartient au fichier. Ajoute-la. Et à l'inverse : si une règle ne s'applique plus, supprime-la, parce que le fatras accumulé pèse lui aussi.

Traite-le pour ce qu'il est : le contrat de travail entre toi et Claude. Plus il est clair et à jour, mieux il travaille. La différence entre celui qui se bat avec l'outil et celui qui en tire parti se résume presque toujours à ça : le second a écrit ses règles une seule fois, dans un fichier, et a cessé de les répéter pour toujours.

Ouvre ton projet, crée un CLAUDE.md avec le modèle ci-dessus et remplis les quatre blocs. C'est la chose la plus rentable que tu feras aujourd'hui avec Claude.