Guide · le réglage qui compte le plus

Les trois niveaux de CLAUDE.md. Lequel écrire en premier.

C'est le seul réglage qui change la qualité de tout ce qui sort, pas juste le confort. Sans lui, Claude redémarre de zéro chaque matin. Avec lui, il arrive en sachant déjà comment tu travailles.

Pour chaque niveau tu as le chemin exact du fichier, quoi mettre dedans, puis l'erreur qui rend le fichier inutile. Les tailles citées viennent d'une installation réelle, mesurées le 26/08/2026.

Tu débutes vraiment ? Commence iciL'app Claude ou Claude Code ? Ce n'est pas la même chose →

Avant tout : regarde si tu en as déjà un

Beaucoup de gens en ont un sans le savoir, parce que /init l'a créé un jour. Autant le vérifier avant d'en écrire un deuxième.

$ ls ~/.claude/CLAUDE.md
$ ls CLAUDE.md
→ le premier vaut partout, le second seulement dans ce projet

Le piège

Croire qu'un fichier généré par /init suffit. Il décrit ton projet, ce que Claude sait déjà lire. La valeur arrive quand tu l'édites toi-même, ce qui prend dix minutes.

Le niveau projet, à écrire en premier

Un fichier CLAUDE.md à la racine de ton projet, versionné avec le reste du code. C'est celui qui porte 90 % de la valeur, donc c'est par lui qu'on commence, toujours.

Les tailles sont réelles, relevées sur une installation en production.

Où ça

CLAUDE.md à la racine, à côté de ton README. Versionné, pas ignoré : il doit suivre le projet.

Le piège

Le mettre dans le .gitignore parce que « c'est un truc perso ». C'est l'inverse : c'est de la documentation d'équipe. Même seul, tu es ta propre équipe dans six mois.

Le niveau global, qui doit rester minuscule

Celui-là s'applique à tous tes projets, sans exception. C'est puissant, donc c'est dangereux. Sur la machine qui a servi à écrire ce guide, il fait trois lignes, face à cent vingt pour le fichier de projet.

Où ça

~/.claude/CLAUDE.md dans les deux cas. Le raccourci ~ désigne ton dossier personnel : C:\Users\toi\ sur Windows, /Users/toi/ sur Mac.

Ce ratio n'est pas un accident. Ce qui est vrai partout est rare : une règle de style que tu tiens dans tous tes projets, un outil que tu veux qu'il connaisse toujours. Tout le reste appartient à un projet précis.

Le piège

Le gonfler parce que c'est pratique de tout mettre au même endroit. Chaque ligne ajoutée là est relue à chaque session de chaque projet, y compris ceux où elle n'a aucun sens. Une règle sur ton style de code Python appliquée à ton site vitrine, c'est du bruit qui coûte à chaque démarrage.

Le niveau dossier, pour plus tard

Sur un gros projet, tu peux poser un CLAUDE.md dans un sous-dossier. Il vient s'ajouter au fichier racine quand Claude travaille dans cette partie du projet.

Où ça

Par exemple mon-projet/api/CLAUDE.md pour les règles qui ne concernent que l'API.

Le piège

Le faire trop tôt. Sur le projet réel qui a servi d'exemple ici, cent vingt lignes à la racine et aucun fichier de sous-dossier, après un an. Découper avant d'en avoir besoin te donne trois fichiers à maintenir au lieu d'un. Et personne ne sait plus lequel dit quoi.

Le seul test qui décide de ce qu'on écrit

C'est ici que se joue la différence entre un fichier décoratif et un fichier utile. Une seule question à poser pour chaque ligne :

Est-ce qu'il pourrait le deviner en lisant le code ?

Si oui, ne l'écris pas. Il sait lire.

Ça élimine d'un coup l'arborescence des dossiers, la liste des dépendances, la description de ce que fait chaque fichier. Tout ça, il le trouve seul en quinze secondes.

## Structure                    ← inutile, il sait lire
- src/ contient le code
- tests/ contient les tests

## Commandes                    ← utile, il ne peut pas deviner
- Tests : npm run test:unit (PAS npm test, qui lance tout)
- Deploiement : bash deploy.sh

## Interdits
- Ne jamais toucher a config/prod.json
- Jamais de `except: pass`, toujours logger

## Ce qui a deja casse
- Modifier .env sans redemarrer : aucun effet, on a
  cherche deux heures le 12 mars

La dernière section est la plus précieuse et c'est celle que personne n'écrit. Une erreur que tu as payée une fois est une information que le code ne contient nulle part.

Le piège

Écrire des règles polies et vagues, du genre « privilégier un code lisible ». Ça ne change rien parce que ça ne se vérifie pas. Une bonne règle se teste : soit elle est respectée, soit elle ne l'est pas.

Le faire vivre sans qu'il gonfle

Un CLAUDE.md n'est pas écrit une fois. Le geste qui rapporte le plus : à chaque fois que tu corriges Claude sur la même chose deux fois, tu ajoutes une ligne. Deux minutes, puis l'erreur ne revient plus.

Tu viens de refaire l'erreur que je t'ai deja signalee.
Ajoute la regle correspondante dans CLAUDE.md, en une
ligne, avec le chemin du fichier concerne entre backticks.

Le piège

Laisser le fichier grossir sans fin. À cent vingt lignes tout va bien. À deux mille, il ne rentre plus dans une fenêtre de contexte, donc il est tronqué sans que tu le saches. Le jour où il devient trop gros, il faut le découper, ce qui demande un vrai système.

Premium

Le système qui empêche Claude de refaire la même erreur

Quoi faire quand le fichier de règles devient trop gros pour être lu
Le hook qui ressort la bonne leçon au moment du geste, pas au démarrage
173 leçons réelles, tirées d'un an de production

Voir ce qu'il y a dedans →

Si tu ne retiens qu'une chose

N'y écris que ce qu'il ne peut pas deviner. Le code, il le lit. Ce qu'il ne lira jamais nulle part, ce sont tes interdits, tes commandes exactes, les erreurs que tu as déjà payées. Un fichier de quinze lignes qui ne contient que ça vaut dix fois un fichier de deux cents lignes qui décrit ton arborescence.

Le guide suivantLes 5 réglages à faire avant d'écrire une ligne →

Un guide par semaine, tous ouverts.

Sans e-mail à donner. La formation complète ouvre bientôt à 39 € par mois ou 199 € l'année. Les inscrits ont l'accès en premier et gardent ce tarif.

Accès anticipé