CLAUDE.md : le fichier qui décide de la qualité de Claude Code, Quentin IA Marketing

Tu ouvres Claude Code sur un projet et il comprend tout du premier coup. Tu l'ouvres sur un autre et il réinvente ta structure de dossiers, lance la mauvaise commande de test, et te propose une librairie que tu as bannie il y a six mois. Même outil, même modèle, deux résultats opposés.

La différence ne vient presque jamais du modèle. Elle vient d'un fichier texte à la racine de ton projet.

Ce fichier s'appelle CLAUDE.md. Claude Code le lit automatiquement au démarrage de chaque session, avant que tu aies tapé quoi que ce soit. C'est le seul endroit où tu peux lui donner, une fois pour toutes, ce qu'il ne peut pas deviner en lisant ton code. La plupart des gens le créent une fois, ne le relisent jamais, et se demandent pourquoi l'agent répète les mêmes erreurs.

Claude AI Lab

Le Claude AI Lab, c'est ma communauté Skool où je partage mes systèmes Claude et les modules plus avancés. L'accès est à $67/mois.

Rejoindre le Lab →

✅Ce qu'il te faut

Claude Code installé. La CLI, dans ton terminal, sur un projet qui existe déjà.

Un projet avec un peu de vécu. Le fichier n'a de valeur que s'il y a des conventions à écrire. Sur un dossier vide, il n'y a rien à transmettre.

Dix minutes. C'est le vrai coût de la première version. Le reste se fait au fil des sessions.

Le principe en une phrase

Tout ce que tu répètes à l'agent plus d'une fois devrait être dans ce fichier. Si tu le répètes, c'est qu'il n'y est pas.

Comprendre ce que c'est vraiment

🗺️ Table des matières, pas documentation

L'erreur de départ, c'est de traiter CLAUDE.md comme une documentation technique. Les gens y déversent l'architecture complète, la justification de chaque choix, l'historique du projet. Le fichier gonfle, et sa valeur baisse.

Ce fichier est une table des matières. Son rôle n'est pas de tout contenir, c'est d'indiquer où tout se trouve. Où vit le code, quelles commandes lancer, quelles conventions respecter, et vers quels documents aller pour le détail.

⚙️La bonne façon de le penser

Écris ce que le code ne dit pas. L'agent lit ton code très bien. Il ne peut pas deviner pourquoi vous avez abandonné une approche ni quelle règle non écrite fait consensus dans l'équipe.

Pointe, ne recopie pas. Une ligne qui dit « les specs d'API sont dans docs/api.md » vaut mieux que trois cents lignes de specs recopiées dans le fichier.

Pense au nouvel arrivant. Le bon test est celui du collègue qui débarque : est-ce qu'il peut lire ça en deux minutes et savoir comment travailler dans ton projet ?

Le test à deux minutes

Si un nouveau développeur ne peut pas lire ton CLAUDE.md en deux minutes et se mettre au travail, l'agent non plus.

Laisser Claude écrire le premier jet

⌨️ La commande /init

La page blanche est la vraie raison pour laquelle ce fichier n'existe pas dans la plupart des projets. Personne ne sait par quoi commencer, donc personne ne commence.

Tu n'as pas à écrire la première version toi-même. Depuis la racine de ton projet :

claude

Puis, dans la session :

/init

Claude Code parcourt le projet, repère la stack, les scripts, l'arborescence et les patterns qui reviennent, puis en génère un CLAUDE.md de départ. Tu passes de zéro à une base structurée en une commande.

Pourquoi ça marche

L'agent est très bon pour décrire ce qui est observable dans ton code. C'est exactement la moitié du travail. L'autre moitié, celle qu'il ne peut pas faire, c'est le conseil suivant.

Traiter la sortie comme un brouillon

✏️ L'étape que presque tout le monde saute

C'est ici que la plupart des gens s'arrêtent. Ils lancent /init, voient un fichier apparaître, se disent que c'est fait, et passent à autre chose. Le résultat est un fichier qui décrit correctement la surface du projet et rate tout ce qui compte.

Ce que /init produit est un point de départ, jamais un livrable. Il faut le relire ligne à ligne.

⚙️La passe de relecture

Corrige ce qui est faux. L'agent déduit, donc il se trompe parfois. Une commande de build obsolète dans le fichier, c'est une erreur que tu vas payer à chaque session.

Supprime ce qui est générique. « Ce projet utilise React » n'apprend rien à personne. Tout ce que l'agent peut voir en ouvrant package.json n'a rien à faire là.

Ajoute ce qu'il ne pouvait pas savoir. Les décisions, les interdits, les pièges. « Ne jamais utiliser la lib X, elle casse le build en production. » « Les migrations passent toujours par le script Y, jamais à la main. » C'est là qu'est toute la valeur.

Le réflexe à prendre

Maintiens ce fichier comme du code, pas comme une note. Il se relit, il se corrige, il se commit avec le reste.

Ce qu'il faut vraiment y mettre

🧱 Les quatre blocs qui comptent

Une structure qui tient sur à peu près tous les projets, dans cet ordre.

📌

Le résumé du projet

Trois lignes. Ce que fait le produit, pour qui, et l'état actuel. Ce qui cadre tout le reste.

🌳

L'arborescence utile

Pas l'arbre complet. Les cinq ou six dossiers qui comptent, avec une ligne chacun sur ce qu'ils contiennent.

⌨️

Les commandes

Installer, lancer, tester, builder. Les vraies commandes de ton projet, copiables telles quelles.

🚫

Les règles

Les conventions et les interdits. La section la plus courte à écrire et la plus rentable à l'usage.

Ajoute en fin de fichier les pointeurs vers la documentation profonde : le fichier de specs, le guide de contribution, le schéma de base de données. Une ligne par pointeur, avec le chemin exact.

La section que personne n'écrit assez

Les règles. C'est celle qui change le comportement de l'agent séance après séance, et c'est celle que /init ne peut pas générer pour toi.

Rester court, sans exception

📏 200 lignes, la cible officielle

Le conseil que presque tout le monde ignore, et celui qui a le plus d'effet.

Un CLAUDE.md qui gonfle dilue ses propres instructions. Quand une règle critique est noyée au milieu de six cents lignes de contexte, elle pèse moins lourd dans l'attention de l'agent qu'au milieu de quatre-vingts. Tu n'obtiens pas plus d'obéissance en écrivant plus, tu en obtiens moins.

Deux cents lignes est la cible officiellement recommandée, et la raison avancée est exactement celle-là : un fichier long consomme plus de contexte et fait baisser le respect des consignes. Au-delà, tu as commencé à recopier de la documentation au lieu de pointer vers elle.

⚙️Quand le fichier déborde

Sors le détail dans un fichier dédié. Les specs d'API, les conventions de test, l'historique des décisions vont dans docs/. Le CLAUDE.md garde une ligne qui y renvoie. Tu peux même l'importer explicitement avec la syntaxe @docs/api.md, qui va chercher le contenu du fichier au chargement (les imports s'enchaînent, jusqu'à quatre niveaux de profondeur).

Coupe tout ce qui est déductible. Si l'agent peut l'apprendre en lisant un fichier de config, la ligne ne sert à rien.

Garde les règles, sacrifie les explications. « Ne jamais committer sur main directement » suffit. Le paragraphe qui justifie la règle peut disparaître.

Le vrai arbitrage

Un fichier court que l'agent applique bat un fichier exhaustif qu'il applique mal. Le plus productif est toujours le plus sobre.

Utiliser les trois niveaux de mémoire

🧩 Global, projet, sous-dossier

Voilà le point que les guides sur le sujet oublient presque systématiquement, et il change complètement la façon de tenir le conseil précédent. CLAUDE.md n'est pas un fichier unique, c'est un système à plusieurs niveaux qui se cumulent.

🌍

Niveau global

~/.claude/CLAUDE.md. Chargé sur tous tes projets, sans exception. C'est là que vivent tes préférences personnelles : ta langue, ton style de réponse, tes règles de sécurité.

📁

Niveau projet

./CLAUDE.md à la racine du repo. Committé, partagé avec l'équipe. Tout ce qui concerne ce projet précis.

🔍

Niveau sous-dossier

Un CLAUDE.md dans src/api/ par exemple. Il apporte le contexte spécifique à cette partie du code, sans polluer le fichier racine.

L'intérêt est direct : ton fichier racine n'a plus à porter les règles de chaque sous-partie du projet. Tu descends le détail au niveau où il s'applique, et la racine reste sous ton plafond de deux cents lignes.

Le détail qui rend la chose vraiment rentable : les fichiers des sous-dossiers ne sont pas chargés au démarrage. Ils entrent en contexte seulement quand l'agent touche des fichiers de ce dossier. Autrement dit, tu peux être précis et détaillé dans src/api/CLAUDE.md sans payer une seule ligne de contexte sur les sessions où tu ne travailles pas sur l'API.

⚙️Comment répartir

Ce qui te suit partout va en global. « Réponds-moi en français. » « Ne me colle jamais une valeur de clé API dans le chat. » Ça n'a rien à faire dans le repo d'un client.

Ce qui concerne l'équipe va dans le repo. Conventions, commandes, interdits du projet. Ce fichier se relit en revue de code comme le reste.

Ce qui ne concerne qu'un dossier reste dans ce dossier. Les règles de ton dossier de migrations n'ont aucune raison d'être lues quand tu travailles sur le front.

L'effet secondaire le plus utile

Le niveau global est ce qui rend Claude Code cohérent d'un projet à l'autre. Tu écris tes préférences une fois, elles s'appliquent partout, y compris sur les projets que tu ouvriras dans six mois.

L'entretenir sans y penser

🔄 Le transformer en système vivant

Un CLAUDE.md écrit une fois puis oublié se périme en quelques semaines. Les commandes changent, les conventions évoluent, et le fichier devient une source d'erreurs au lieu d'une source de vérité. Le problème n'est pas la volonté, c'est le moment : personne n'ouvre son éditeur pour documenter une règle en plein milieu d'une tâche.

La solution est de capturer la règle au moment exact où elle apparaît, sans quitter ta session. Tu n'as rien de particulier à apprendre : demande-le en langage naturel, l'agent l'enregistre en mémoire.

Retiens que les tests tournent avec npm run test:unit, jamais avec npx jest directement.

C'est trois secondes au lieu d'un aller-retour dans ton éditeur, et c'est toute la différence entre un fichier vivant et un fichier mort.

⚙️La boucle d'entretien

Chaque correction devient une règle. Le moment où tu reprends l'agent est le meilleur signal qui existe : il vient de faire une chose que ton fichier aurait dû empêcher. Fais-lui enregistrer la règle dans la foulée.

Relis tes fichiers avec /memory. La commande liste tes fichiers de mémoire et les ouvre dans ton éditeur. Une passe de nettoyage toutes les quelques semaines suffit à couper les règles devenues fausses.

Fais-le auditer par l'agent lui-même. Colle ton fichier dans une session et demande : « Qu'est-ce qui est générique, faux ou déductible du code ? Qu'est-ce qui manque pour qu'un nouveau développeur soit autonome ? » Il coupe efficacement.

Le signal qu'il est à jour

Si tu n'as pas eu à répéter la même consigne deux fois dans le mois, ton fichier fait son travail. Si tu la répètes, tu viens de trouver la prochaine ligne à écrire.

Ce que ce fichier ne fera pas pour toi

Deux points d'honnêteté.

Le premier : CLAUDE.md oriente, il ne contraint pas. Une règle écrite est une instruction forte, pas une barrière technique. Pour ce qui ne doit jamais arriver, une règle dans un fichier ne remplace pas une protection réelle du côté de ton projet.

Le second : il ne compense pas un projet illisible. Si ta structure est incohérente et tes commandes cassées, décrire ce désordre proprement ne le range pas. Le fichier accélère un projet sain, il ne sauve pas un projet malade.

Et maintenant

Ouvre ton projet le plus actif, lance /init, et donne-toi dix minutes de relecture sérieuse. Coupe le générique, ajoute les trois interdits que tu répètes le plus souvent, et vérifie que tu tiens sous deux cents lignes.

Puis prends le réflexe qui compte vraiment : la prochaine fois que tu corriges l'agent, ne te contente pas de le corriger. Écris la règle avec #.

À retenir

La qualité de Claude Code sur ton projet n'est pas une propriété du modèle. C'est une propriété de ce que tu lui as écrit avant de commencer.