Le fichier que Claude lit avant tout le reste

Ce que c'est et pourquoi ça compte

Chaque session de Claude Code démarre avec un contexte vide. Ce que vous lui avez expliqué hier dans le chat n'est plus là aujourd'hui. Alors vous recommencez : « bon, mon app, c'est… ». Et les fois où vous oubliez, il devine : l'outil, le dossier, ce qu'il a le droit de changer.

C'est à ça que sert le CLAUDE.md. C'est un simple fichier texte, dans le dossier du projet, avec les règles que vous voulez voir appliquées à chaque fois. Claude Code le lit au début de chaque session, avant même votre premier message. C'est pour ça que je l'appelle le fichier que Claude lit avant tout le reste.

Ça compte parce que vous écrivez une seule fois ce que vous répéteriez sinon tous les jours. Il démarre en le sachant déjà, et vous allez droit à ce que vous voulez faire.

Une chose à savoir tout de suite : c'est une consigne, pas un cadenas. Claude le lit et essaie de le suivre, et plus les règles sont claires, mieux il les suit. Mais pour bloquer vraiment quelque chose, ça ne suffit pas : j'en parle dans les questions en bas de page.

1. Mon fichier, à copier

Voici mon fichier à copier, sur une app d'exemple : un livre de recettes. Ça fait dix lignes. Remplacez les parties entre < > par celles de votre projet, et enlevez les symboles < >.

# <Livre de recettes> : <app de recettes>
Stack : <Next.js et TypeScript>
Code dans <src/>, tests dans <tests/>
Ne touche ni à <.env> ni au <dossier des paiements>
Demande avant de supprimer des fichiers
Lis avant de modifier
Après chaque modification : <npm test>, et dis-moi le résultat
Une modification à la fois
Parle-moi en français
Écris le code en anglais

Les lignes sans < >, je les garde identiques dans tous les projets. Et celles qui valent partout, comme la langue, je les déplace dans le fichier de mon utilisateur : on y vient tout de suite.

2. Les dix lignes expliquées

Chaque ligne est là parce qu'elle m'a enlevé un problème que j'avais souvent :

1. Ce qu'est l'app. Fini le « bon, mon app, c'est… » à chaque nouvelle session.
2. Avec quoi elle est faite. Il ne vous propose pas d'autres outils que ceux que vous utilisez déjà.
3. Où sont le code et les tests. Il ne les cherche pas à chaque fois.
4. Ce qu'il ne doit pas toucher. Les clés et l'argent restent à vous : les clés secrètes sont en général dans le fichier .env, et les paiements sont la partie où une erreur fait le plus de dégâts. Mais c'est une consigne, pas un blocage : pour le bloquer vraiment, il faut une règle deny ou un hook. J'en parle dans le guide GUARDIA (strikt.fit/guardia).
5. Demande avant de supprimer. Pas de suppressions surprises.
6. Lis avant de modifier. Il comprend ce qui existe avant de le réécrire.
7. La commande des tests. C'est elle qui prouve que l'app marche encore. Et je lui demande le résultat, pas seulement de la lancer.
8. Une modification à la fois. Des petits changements : si quelque chose casse, vous savez où.
9. La langue. Il vous répond dans votre langue.
10. Le code en anglais. Les noms, les fonctions et les commentaires restent en anglais, comme tout le monde peut les lire.

Ce sont toutes des choses qu'on ne voit pas dans le code, ou seulement en cherchant : c'est exactement ce qu'il faut écrire.

3. Où il va

Le nom est toujours CLAUDE.md. Ce qui change, c'est le dossier, et le dossier décide où il s'applique :

• Dans le dossier principal du projet : ./CLAUDE.md, ou ./.claude/CLAUDE.md. Les deux se valent, choisissez-en un. Il contient les règles de ce projet, et si le projet est sur git, les personnes qui y travaillent avec vous les voient aussi.
• Dans le fichier de votre utilisateur : ~/.claude/CLAUDE.md. Les règles qui valent pour tous vos projets, comme la langue, vont ici. Vous seul les voyez.

Claude Code les lit au début de chaque session, tous les deux : ils s'additionnent, ils ne se remplacent pas. Ne répétez donc pas dans le projet ce qui est déjà dans le fichier de votre utilisateur, et veillez à ce qu'ils ne se contredisent pas : si deux lignes disent le contraire, Claude peut suivre l'une ou l'autre.

Quand vous modifiez un fichier, ouvrez une nouvelle session : vous êtes ainsi sûr qu'il travaille avec la version à jour.

4. Comment le créer et le modifier

1. Ouvrez Claude Code dans le dossier du projet et tapez /init. Il regarde votre code et vous écrit un premier CLAUDE.md, avec les commandes pour construire et tester le projet et les conventions qu'il trouve. Si un CLAUDE.md existe déjà, il ne l'écrase pas : il vous propose des améliorations.
2. Ensuite, ajoutez les règles qu'il ne peut pas deviner tout seul : ce qu'il ne doit pas toucher, comment vous voulez qu'il travaille, dans quelle langue vous parler. Ce sont celles de mon fichier plus haut.
3. Pour le modifier, tapez /memory. Vous voyez les fichiers de mémoire du projet et de votre utilisateur. Choisissez le fichier et il s'ouvre dans votre éditeur ; s'il n'existe pas, il est créé.
4. Pour vérifier qu'il est chargé, tapez /context dans une nouvelle session et regardez la liste sous Memory files. Vos CLAUDE.md doivent y être : s'il en manque un, Claude ne le voit pas.

Les nouvelles règles, vous pouvez aussi les lui faire écrire. Quand vous remarquez qu'il en manque une :

Ajoute cette règle au CLAUDE.md du projet : [la règle]. Écris-la en une ligne, courte et précise.

La formulation compte. Avec « ajoute-le au CLAUDE.md », ça finit dans le fichier. Si vous dites seulement « souviens-toi que… », il l'enregistre en général dans sa mémoire automatique, qui est autre chose : je l'explique dans les questions en bas de page.

5. Gardez-le court

Gardez-le court et précis : plus les règles sont claires et peu nombreuses, plus il les suit. La documentation de Claude Code recommande de rester sous les 200 lignes par fichier : au-delà, les règles sont moins bien suivies.

Précis, ça veut dire qu'on peut le vérifier. « Après chaque modification, lance npm test » marche mieux que « teste bien le code ». « Le code est dans src/ » marche mieux que « garde les fichiers en ordre ».

Et ensuite, il faut le faire vivre. Je suis trois règles :

• Si vous lui répétez la même chose deux fois, c'est une ligne qui manque : ajoutez-la.
• Si une ligne n'est plus vraie, supprimez-la.
• Si c'est une chose que Claude voit tout seul en ouvrant le code, inutile de l'écrire.

Les erreurs les plus courantes

• Laisser le fichier de /init tel quel. C'est une base : ajoutez les règles qu'on ne voit pas dans le code, comme ce qu'il ne faut pas toucher et dans quelle langue vous parler.
• Répéter dans chaque projet les règles qui valent partout. Mettez-les une seule fois dans ~/.claude/CLAUDE.md.
• Écrire des règles vagues, du genre « fais attention ». Écrivez des choses qu'on peut vérifier : une commande, un dossier, un fichier.
• Le traiter comme un cadenas. C'est une consigne : pour bloquer vraiment un fichier, il faut une règle deny dans les permissions de Claude Code ou un hook.
• Le modifier et continuer dans la même session en supposant qu'il voit le changement. Ouvrez une nouvelle session et vérifiez avec /context.

Check-list

• Le CLAUDE.md est dans le dossier principal du projet
• Les parties entre < > décrivent maintenant mon projet
• La commande qui lance les tests y est
• La langue est dans ~/.claude/CLAUDE.md, pas dans chaque projet
• Dans une nouvelle session, /context l'affiche sous Memory files
• Il est court, sans lignes répétées ni périmées

Questions fréquentes