Le fichier CLAUDE.md expliqué, avec un modèle à copier

CLAUDE.md est un simple fichier texte que Claude Code lit au début de chaque session. Tu le places à la racine de ton projet, ou dans ton dossier personnel ~/.claude/ pour qu’il vaille dans tous tes projets. Tu y écris ce que tu devrais sinon répéter à chaque fois : les commandes du projet, tes conventions et tes règles de travail.

Plus bas, tu trouveras un modèle à copier et trois règles tirées de mon propre CLAUDE.md. Si Claude Code n’est pas encore installé chez toi, commence par l’installer.

Pourquoi un fichier plutôt que la conversation

Une session, c’est une conversation avec Claude Code dans un dossier, du lancement jusqu’à la fermeture. Chaque nouvelle session démarre avec un contexte vierge : Claude ne garde pas en tête ce que tu lui as expliqué hier. Le fichier CLAUDE.md sert de pont. Il est relu à chaque session, sans que tu aies à le demander.

Il a un autre avantage. Quand une conversation devient longue, Claude Code la résume pour libérer de la place (c’est la commande /compact, qui se déclenche aussi toute seule). Une consigne donnée seulement dans la conversation peut se perdre à ce moment-là. Le CLAUDE.md à la racine du projet, lui, est relu depuis le disque après le résumé.

Le fichier est écrit en Markdown : du texte normal, avec # devant un titre et - devant chaque point d’une liste. Aucun format n’est imposé.

Claude Code a aussi une mémoire automatique : des notes que Claude prend lui-même à partir de tes corrections, rangées sur ta machine. Les deux se complètent. La mémoire automatique, c’est Claude qui décide ce qu’il retient. Le CLAUDE.md, c’est toi qui décides ce qu’il sait. Retiens une nuance pratique : si tu dis « retiens que… », Claude l’enregistre dans sa mémoire automatique. Pour que ça aille dans le fichier, dis « ajoute ça au CLAUDE.md ».

Où placer le fichier CLAUDE.md

Il peut vivre à plusieurs endroits. Chaque emplacement a sa portée.

Deux mots de vocabulaire. Le dépôt, c’est le dossier du projet suivi par git, l’outil qui garde l’historique des versions. Le .gitignore, c’est la liste des fichiers que git ne doit jamais enregistrer.

Ces fichiers ne se remplacent pas : ils s’additionnent. Claude Code les met bout à bout, du plus large au plus précis : le fichier personnel d’abord, celui du projet ensuite, le fichier local en dernier. Ne compte donc pas sur un ordre de priorité si deux fichiers se contredisent (on y revient plus bas).

Pour vérifier ce qui a été chargé, tape /context dans une session et regarde la liste Memory files.

Créer ton CLAUDE.md

Avec /init

Ouvre Claude Code dans le dossier de ton projet et tape /init. Claude analyse ton code et crée un premier fichier avec les commandes de construction, les instructions de test et les conventions qu’il repère. Si un CLAUDE.md existe déjà, /init propose des améliorations au lieu de l’écraser.

Ce premier jet est une base. Complète-le ensuite avec ce que Claude ne peut pas deviner seul : tes habitudes, les exigences du client, ce qui a déjà coincé.

Avec /memory

La commande /memory liste tes fichiers CLAUDE.md, personnels et projet. Choisis-en un : il s’ouvre dans ton éditeur. S’il n’existe pas encore, il est créé. C’est le plus simple pour ton fichier personnel.

Ce que tu y mets

La documentation d’Anthropic donne une liste claire. Garde :

• les commandes que Claude ne peut pas deviner (lancer, construire, tester) ;
• les règles de style qui diffèrent des usages courants ;
• la façon de tester et l’outil de test préféré ;
• les conventions du dépôt : noms des branches, messages de commit ;
• les choix d’architecture propres à ton projet ;
• les particularités de ton environnement, comme les variables d’environnement nécessaires ;
• les pièges qui ne sautent pas aux yeux.

Quand ajouter une ligne ? Quand Claude fait deux fois la même erreur, ou quand tu tapes une correction que tu avais déjà tapée à la session précédente.

Ce que tu n’y mets jamais

Laisse de côté ce que Claude trouve seul en lisant le code, les conventions qu’il connaît déjà, les longs tutoriels, les informations qui changent souvent, et les évidences du genre « écris du code propre ». Pour chaque ligne, la documentation propose une question : « Si je l’enlève, Claude fera-t-il des erreurs ? » Si la réponse est non, supprime-la.

Et surtout : aucun secret. Pas de clé d’API, pas de mot de passe, pas de jeton. Le CLAUDE.md du projet est fait pour être partagé avec le dépôt : ce que tu y écris voyage avec lui, chez le client ou chez un autre développeur. Écris le nom de la variable et son rôle. La valeur reste dans ton fichier .env, ignoré par git.

Un modèle de CLAUDE.md à copier

Voici une base pour le CLAUDE.md d’un projet client, par exemple un site vitrine. Remplace ce qui est entre crochets et supprime ce qui ne te concerne pas.

# Projet : [nom du projet]

Site vitrine pour [client], [métier] à [ville].
Stack : [ex. Astro + Tailwind]. Hébergement : [ex. Vercel].

## Commandes
- Installer : `npm install`
- Lancer en local : `npm run dev`
- Construire : `npm run build`
- Tester : `npm test`

## Organisation
- Pages : `src/pages/`. Composants : `src/components/`.
- Images du client : `public/images/`, déjà optimisées.

## Conventions
- Textes du site en français, [vouvoiement] du visiteur.
- Code, noms de fichiers et messages de commit en anglais.
- Un commit par modification, avec un message qui dit pourquoi.

## Façon de travailler
- Pour une modification qui touche plusieurs fichiers, montre-moi ton plan avant de commencer.
- Après chaque modification, lance `npm run build` et corrige les erreurs avant de me répondre.
- Ne modifie pas les textes validés par le client sans me demander.

## Variables d’environnement
- `FORM_API_KEY` : clé du service d’envoi du formulaire de contact.
  La valeur est dans `.env`, jamais ailleurs.

Ce modèle vise le fichier du projet. Tes habitudes personnelles, valables partout, iront dans ~/.claude/CLAUDE.md.

Trois règles de mon CLAUDE.md, expliquées

De mon CLAUDE.md, j’ai tiré sept règles : celles que Claude Code lit à chaque session sur mes projets clients. La plupart sont arrivées après un vrai problème, sur un vrai projet. En voici trois, celles qui servent le plus quand on débute.

Rien n’est « fini » sans preuve

## Rien n’est « fini » sans preuve

Tests lancés, résultat montré.

- Avant d’écrire « c’est fait » : lance les tests, démarre l’application, ouvre les pages, essaie le formulaire.
- Montre la preuve : nombre de tests passés, page affichée, réponse obtenue.
- Ce que tu n’as pas pu vérifier, dis-le clairement au lieu de le déclarer fini.
- Si quelque chose échoue, dis-le, avec le message d’erreur.

Elle a fait ses preuves en octobre 2026, pendant que je construisais la page d’inscription de ma newsletter. La compilation affichait « Complete! ». Zéro erreur de types. 69 tests au vert. Tout disait « c’est fini ». Au premier vrai lancement du serveur, 7 pages sur 9 répondaient « erreur 500 ». La cause : un réglage de compilation incompatible avec l’hébergement, qu’aucun contrôle précédent ne pouvait voir. Claude l’a trouvé parce que la règle l’oblige à ouvrir les pages, pas seulement à compiler.

Anthropic fait le même constat dans ses bonnes pratiques : Claude s’arrête quand le travail a l’air terminé. Donne-lui un moyen de vérifier, et demande-lui de montrer la preuve plutôt que d’affirmer que c’est réussi.

La doc du projet se tient à jour

## Documentation : PROJET.md tenu à jour

- En début de session, lis PROJET.md pour reprendre le contexte.
- Après chaque changement significatif (fonction ajoutée, bug corrigé, refonte, variable d’environnement), mets à jour les sections concernées et ajoute une ligne datée au journal (AAAA-MM-JJ).
- Ne réécris pas tout le fichier quand une seule section change.
- Sections : description en une phrase, stack, démarrage rapide, architecture, variables d’environnement (noms seulement), feuille de route, journal, problèmes connus.

Le CLAUDE.md dit à Claude comment travailler. Il ne dit pas où en est le projet. Sans carnet de bord, chaque session commence par la même question : où en était-on ? Claude relit le code, devine ce qui avait été décidé, et repose des questions déjà tranchées.

Avec un PROJET.md, il relit le carnet : ce qui est fait, ce qui reste, les décisions prises et pourquoi. Je peux laisser un projet de côté plusieurs semaines et le reprendre sans tout réexpliquer. Contrairement à la mémoire automatique, ce carnet vit dans le projet : tu le lis, tu le corriges, tu peux l’envoyer au client.

Aucune preuve inventée

## Preuves : rien d’inventé

- N’écris jamais un chiffre, un avis, un témoignage ou une référence client que tu n’as pas lu dans une source que je t’ai donnée.
- S’il manque une donnée, écris [À CONFIRMER : …] au lieu d’une valeur plausible.
- Pas de faux avis, de fausse capture d’écran, de faux client ni de personne générée par IA présentée comme réelle.

En août, je préparais une page de vente avec Claude. Dans le bloc de preuve, en gros chiffres : « 310 vidéos » et « 1 500+ abonnés ». Un relevé direct sur ma chaîne YouTube a donné 53 vidéos et 1 460 abonnés. Le nombre de vidéos était multiplié par six. Il venait d’une note interne, pas d’un relevé, et il est resté une journée sur la page. Personne ne l’avait vérifié : il avait l’air juste.

L’IA écrit du plausible, et plausible n’est pas vrai. Sur le site d’un client, un faux chiffre ou un faux avis, c’est sa crédibilité qui saute, et la tienne avec.

Les sept règles, avec l’histoire de chacune. Les quatre autres touchent aux choix structurels, aux livrables, aux secrets et aux chiffres. Je les donne toutes, commentées, avec le fichier CLAUDE.md prêt à copier, quand tu t’inscris à « La Ligne de commande », ma newsletter gratuite du mardi. Recevoir les sept règles commentées

Les erreurs fréquentes

Un fichier trop long. Vise moins de 200 lignes par fichier. Un CLAUDE.md surchargé fait que Claude ignore la moitié des consignes, parce que les règles importantes se perdent dans le bruit. Si Claude continue de faire ce qu’une règle interdit, le fichier est sans doute trop long.

Des règles vagues. « Formate bien le code » ne se vérifie pas. « Utilise une indentation de 2 espaces », si. De même, « Lance npm test avant chaque commit » vaut mieux que « Teste tes changements ».

Des instructions contradictoires. Une règle dans ton fichier personnel, la règle inverse dans celui du projet : la documentation prévient que Claude peut alors choisir l’une ou l’autre, au hasard. Relis tes fichiers de temps en temps et supprime ce qui est dépassé.

Tout marquer comme important. Si Claude oublie une consigne précise, tu peux ajouter « IMPORTANT » sur cette ligne. Sur cette ligne seulement : si tout est important, plus rien ne ressort.

Le prendre pour un verrou. Claude lit le CLAUDE.md comme du contexte, pas comme une configuration imposée. Il essaie de le suivre, sans garantie. Pour une action qui doit se produire à chaque fois, sans exception, la documentation conseille un hook : un script que Claude Code exécute à un moment précis, quoi que Claude décide.

Pour aller plus loin

Les sept règles, sans leurs histoires, sont aussi publiques sur GitHub, en français et en anglais : cltconcept/claude-md-7-regles.

Quand ton fichier grossit, deux outils aident à le ranger. Une ligne @chemin/vers/fichier.md importe un autre fichier, chargé avec le CLAUDE.md : plus lisible, mais pas plus léger. Le dossier .claude/rules/ range des règles par thème, et une règle peut ne se charger que pour les fichiers qu’elle vise.

Pour démarrer, pas besoin de tout ça. Lance /init sur ton prochain projet, ajoute trois lignes qui comptent pour toi, puis une de plus chaque fois que Claude te fait perdre du temps. Si tu hésites encore sur l’abonnement, j’ai détaillé le prix de Claude Code dans un autre article. Et si tu veux mes sept règles pour partir d’un fichier déjà rodé, elles t’attendent ici.