CLAUDE.md : le fichier qui pilote Claude Code

Tout le monde installe Claude Code. Presque personne n'écrit son CLAUDE.md. C'est pourtant le seul fichier qui décide si vous travaillez avec un assistant générique ou avec un collègue qui connaît vos conventions, vos interdits et vos pièges.

Le principe est simple : ce fichier est chargé automatiquement au démarrage de chaque session et reste présent dans le contexte du modèle pendant tout l'échange. Ce que vous y écrivez s'applique sans que vous ayez à le répéter. Ce que vous n'y écrivez pas, vous le réexpliquerez à chaque fois.

Après des mois de pratique quotidienne sur nos projets et ceux de nos clients, nous avons vu passer beaucoup de CLAUDE.md. Les fichiers qui fonctionnent se ressemblent tous. Les fichiers inutiles aussi, et pour des raisons précises. Cet article détaille comment le fichier est lu par Claude Code, ce qu'il faut y mettre, ce qu'il faut absolument en retirer, et comment le gérer quand plusieurs personnes y touchent.

Comment Claude Code lit vos fichiers CLAUDE.md

Première chose à comprendre : il n'y a pas un CLAUDE.md, il y en a plusieurs, et ils se cumulent.

Le fichier global, dans ~/.claude/CLAUDE.md, s'applique à toutes vos sessions, tous projets confondus. C'est l'endroit pour ce qui relève de vous : la langue dans laquelle vous voulez qu'on vous réponde, votre style de travail, vos préférences d'outillage, les erreurs que vous ne voulez plus jamais revoir.

Le fichier de projet, à la racine du dépôt, s'applique à toutes les sessions ouvertes dans ce projet. Il est versionné, donc partagé avec toute l'équipe. C'est l'endroit pour ce qui relève du code : la stack, les conventions, les commandes de test, les pièges connus.

Les fichiers de sous-dossier sont chargés quand Claude travaille dans le répertoire concerné. Utile sur un monorepo où le front et le back n'obéissent pas aux mêmes règles.

Les trois niveaux s'empilent, du plus général au plus spécifique. En cas de contradiction, le plus proche du fichier sur lequel vous travaillez l'emporte. Concrètement, votre préférence globale « réponds en français » cohabite sans conflit avec la règle projet « commentaires de code en anglais », et une règle propre au dossier packages/api/ prime sur la règle générale du dépôt.

Les imports, pour éviter le fichier fleuve

Un CLAUDE.md peut en inclure un autre avec la syntaxe @chemin/vers/fichier.md. La ligne est remplacée par le contenu du fichier importé.

## Règles

@rules/typescript.md
@rules/react.md
@rules/git.md

C'est la meilleure réponse au problème du fichier qui gonfle. Plutôt qu'un bloc de 400 lignes que personne ne relit, vous obtenez un index lisible et des modules qu'on peut modifier isolément. C'est aussi ce qui permet de partager un jeu de règles entre plusieurs projets sans copier-coller.

Un cas particulier utile : si votre dépôt contient déjà un AGENTS.md, le format de configuration commun aux assistants de code, votre CLAUDE.md peut se réduire à une seule ligne qui l'importe. Vous maintenez un seul fichier au lieu de deux qui divergent au bout de trois semaines.

Ce qu'il faut y mettre

La question à se poser pour chaque ligne est toujours la même : est-ce que Claude peut le découvrir tout seul en lisant le projet ? Si oui, ça n'a rien à faire dans le CLAUDE.md.

L'arborescence des dossiers, la liste des scripts du package.json, les dépendances installées, la description de ce que fait le produit : tout ça est déjà dans le dépôt, et un agent le lit en quelques secondes. L'écrire dans le CLAUDE.md, c'est payer un coût de contexte à chaque session pour une information qu'il aurait obtenue gratuitement, et prendre le risque qu'elle devienne fausse sans que personne s'en aperçoive.

Ce qui mérite d'y être, c'est ce que le code ne dit pas :

Les interdits. « Jamais de any, utiliser unknown si le type est réellement inconnu. » « Jamais --force sur main. » Une interdiction explicite est le type de règle qui change le plus visiblement le comportement du modèle.
Les arbitrages non évidents. Quand deux approches sont défendables et que votre équipe en a tranché une, écrivez laquelle et pourquoi. Sans ça, l'agent choisira celle qui domine dans ses données d'entraînement, qui n'est pas forcément la vôtre.
Les pièges du projet. Le test qui échoue si on ne lance pas le conteneur avant. Le fichier généré qu'il ne faut pas éditer à la main. La migration qui casse si on la joue dans le mauvais ordre. Ce sont les informations les plus rentables du fichier : elles évitent une erreur coûteuse, elles ne sont écrites nulle part ailleurs, et un nouvel arrivant humain en profite autant que l'agent.
Le workflow attendu. Faut-il lancer le typecheck avant de proposer un diff ? Faut-il un plan validé avant de toucher à plusieurs fichiers ? Ce sont des attentes de processus qu'aucune lecture du code ne révèle.
Le vocabulaire maison. Si « livrable », « campagne » ou « compte » ont un sens précis chez vous, dites-le. Une ambiguïté de vocabulaire produit du code correct qui répond à la mauvaise question.

Écrivez des règles vérifiables, pas des intentions

C'est le point qui sépare les fichiers qui marchent des autres.

« Écris du code propre et maintenable » ne change strictement rien. C'est une intention, elle n'est pas vérifiable, et le modèle pensait déjà bien faire. « Un composant par fichier, nom du fichier identique au composant » est une contrainte : elle se vérifie en regardant le résultat, et elle produit un comportement différent.

Le test est mécanique : si vous ne pouvez pas dire, en regardant un diff, si la règle a été respectée ou non, la règle est inutile. Reformulez-la ou supprimez-la.

Ajoutez le « pourquoi » uniquement quand la règle est contre-intuitive. « Pas de useEffect pour dériver un state, calculer directement pendant le rendu » se suffit à elle-même. En revanche « ne jamais lancer un build pendant qu'un serveur de dev tourne » mérite sa justification, sinon la règle sera perçue comme arbitraire et contournée à la première occasion.

Ce qu'il faut en retirer

Un CLAUDE.md est rechargé à chaque session et occupe du contexte en permanence. Ce coût est réel mais modeste. Le vrai problème est ailleurs : plus le fichier est long, moins chaque règle pèse.

Un fichier de 60 lignes tendues est suivi. Un fichier de 600 lignes où l'essentiel est noyé entre trois paragraphes de description produit et une liste de dépendances obsolètes est suivi de manière erratique, et vous en conclurez à tort que « le CLAUDE.md ne sert à rien ».

Trois choses à couper sans hésiter :

Ce qui décrit au lieu de contraindre. Un CLAUDE.md n'est pas un README. Le README explique à un humain comment démarrer le projet. Le CLAUDE.md empêche un agent de faire des bêtises. Ce ne sont pas les mêmes contenus, et fusionner les deux dégrade les deux.
Ce qui est périmé. Une règle qui référence un fichier supprimé ou une commande qui n'existe plus fait pire que rien : elle envoie l'agent sur une piste morte. Le CLAUDE.md doit être relu à chaque refonte, comme le reste du code.
Ce qui n'a jamais rien changé. C'est le point le plus difficile, parce qu'il faut accepter de supprimer des lignes qu'on a écrites avec conviction.

Comment savoir si une règle sert à quelque chose

La méthode tient en une manipulation : prenez une tâche représentative, lancez-la dans une session avec la règle, puis dans une session neuve sans elle. Comparez les deux résultats.

Si le comportement est identique, la règle n'apporte rien : soit le modèle le faisait déjà spontanément, soit la formulation est trop vague pour mordre. Dans les deux cas, elle occupe de la place et dilue les règles voisines. Supprimez-la.

Nous faisons cet exercice tous les deux ou trois mois sur nos propres fichiers. À chaque passage, entre un quart et un tiers des lignes disparaissent, et le fichier devient plus efficace en devenant plus court.

Créer le vôtre en pratique

Partez de /init. Lancée dans un projet existant, cette commande analyse le dépôt et génère un premier CLAUDE.md. Ne le considérez pas comme un livrable : c'est un brouillon, souvent trop descriptif, qui a le mérite de vous donner une structure et de repérer les commandes principales. Le vrai travail commence en coupant les deux tiers.

Enrichissez-le à chaud avec #. Un message qui commence par # ajoute son contenu au CLAUDE.md sans quitter la session. C'est le bon réflexe au moment exact où vous corrigez Claude pour la deuxième fois sur la même chose : plutôt que de le recorriger une troisième, écrivez # toujours utiliser pnpm, jamais npm et le problème est réglé pour toutes les sessions suivantes.

C'est de loin la meilleure méthode d'écriture. Un CLAUDE.md rédigé d'un bloc un lundi matin contient ce que vous imaginez être vos règles. Un CLAUDE.md construit correction après correction contient vos règles réelles, celles dont l'absence vous a effectivement coûté quelque chose.

Rangez au fil de l'eau. Quand une section dépasse une dizaine de lignes, sortez-la dans un fichier dédié et importez-la. Quand une règle ne concerne qu'un sous-dossier, déplacez-la dans un CLAUDE.md local plutôt que de la laisser peser sur tout le projet.

Le CLAUDE.md en équipe

À partir de deux personnes, le fichier devient un objet de gouvernance, et les questions changent de nature.

Qui écrit quoi. La ligne de partage la plus saine passe entre le projet et la personne. Ce qui engage le code va dans le fichier versionné du dépôt : conventions, interdits techniques, pièges, workflow de validation. Ce qui relève des habitudes individuelles reste dans le ~/.claude/CLAUDE.md de chacun. Un développeur qui veut ses réponses en anglais ne doit pas imposer ce choix au dépôt.

Le fichier se revoit comme du code. Une modification du CLAUDE.md passe en pull request et se discute. C'est contre-intuitif pour un fichier Markdown, mais une règle mal formulée se propage immédiatement à tout le travail de toute l'équipe. L'impact d'une ligne y est plus large que celui d'une ligne de code applicatif.

L'anti-pattern à surveiller. Chacun ajoute sa règle après chaque incident, personne ne supprime jamais rien, le fichier atteint 400 lignes en six mois, les règles se contredisent, et l'équipe conclut que l'outil n'est pas fiable. Le remède est une revue périodique inscrite au calendrier, avec un objectif de suppression explicite. Un CLAUDE.md d'équipe en bonne santé rétrécit régulièrement.

Le bénéfice caché. Un CLAUDE.md bien tenu est la documentation la plus à jour du projet, parce que c'est la seule que quelqu'un a intérêt à corriger : quand elle est fausse, l'agent produit du travail faux, et ça se voit tout de suite. Les nouveaux arrivants humains le lisent souvent en premier, et ils ont raison.

Là où le CLAUDE.md s'arrête

Le fichier définit un cadre permanent. Il n'est pas le bon endroit pour tout.

Les procédures longues et occasionnelles, une recette de déploiement, un protocole de revue, un enchaînement d'étapes à suivre, gagnent à devenir des skills réutilisables chargés à la demande plutôt que du texte présent en permanence dans chaque session. Les accès aux systèmes externes, CRM, base de données, outils internes, relèvent du Model Context Protocol et non d'instructions écrites. Les permissions, les hooks et l'affichage se règlent dans le settings.json, détaillé dans notre guide de configuration complète de Claude Code.

Le CLAUDE.md répond à une seule question : que doit savoir l'agent avant même que je lui parle ? Tout le reste appartient à une autre brique de la configuration.

L'essentiel en cinq points

Trois niveaux qui se cumulent : global pour vous, projet pour l'équipe, sous-dossier pour les exceptions.
N'y écrivez que ce que le code ne dit pas : interdits, arbitrages, pièges, vocabulaire.
Une règle vérifiable dans un diff, sinon supprimez-la.
Construisez le fichier par corrections successives avec #, pas d'un bloc.
Purgez tous les deux mois : un bon CLAUDE.md rétrécit.

Déployer ça sur toute une équipe

Écrire son propre CLAUDE.md prend une après-midi. Faire converger dix développeurs sur un jeu de règles partagé, décider ce qui est versionné, installer la revue périodique et éviter la dérive à 400 lignes, c'est un travail d'équipe qui demande une méthode.

C'est ce que nous faisons chez Kairia : nous formons vos équipes à Claude Code et construisons avec elles la configuration adaptée à votre code et à vos conventions, directement dans votre environnement.

Pour en discuter, réservez 30 minutes : nous regardons ensemble votre contexte et ce qui vous ferait gagner le plus de temps.