Quand un développeur rejoint une équipe, personne ne le pousse vers le code en lui disant « vas-y, débrouille-toi ». On lui fait un onboarding : voilà le produit, voilà nos conventions, voilà les pièges du projet, voilà comment on lance les tests. Puis on oublie systématiquement d'offrir la même chose à Claude, qui en a pourtant davantage besoin que n'importe quelle recrue : le chapitre 2 vous l'a montré, il prend son poste chaque matin sans aucun souvenir de la veille.
Le premier geste professionnel du développement avec une IA n'est donc pas un geste de code. C'est un geste d'écriture : préparer le dossier de brief que Claude relira à chaque prise de poste. Bonne nouvelle, ce dossier est court, il s'écrit en grande partie tout seul, et il transforme la qualité de tout ce qui suit.
CLAUDE.md : la note que Claude relit chaque matin
La pièce maîtresse du dossier s'appelle CLAUDE.md. C'est un simple fichier Markdown à la racine du projet, avec une propriété qui change tout : Claude Code le charge automatiquement au début de chaque session. C'est la mémoire de projet, la note épinglée sur le carnet du collaborateur amnésique. Ce que vous y écrivez une fois, Claude le sait tous les matins.
Qu'est-ce qu'on y met ? Trois familles de choses, et rien d'autre.
- 01 · Les commandes du projetComment lancer le serveur de développement, les tests, le lint, le build, avec leurs subtilités locales.
- 02 · Les conventionsLa structure des dossiers, les patterns maison, la façon de nommer et de ranger.
- 03 · Les pièges du repoLa famille la plus précieuse : tout ce qui n'est pas évident en lisant le code, tout ce qu'un ancien de l'équipe dirait à une recrue autour d'un café. « Le build et les tests partagent le même dossier de sortie, ne les lance pas en même temps que le serveur de dev. » « Ce fichier est généré, ne l'édite jamais à la main. »
Si le fichier grossit, les imports @fichier permettent de le découper : une ligne @docs/conventions.md tire le contenu d'un autre document dans le contexte, et le brief reste rangé.
Par où commencer ? Pas par la page blanche. La commande /init lit votre dépôt, y repère le système de build, le lanceur de tests et les patterns dominants, et vous rend un premier CLAUDE.md. Il ne sera pas excellent, et ce n'est pas grave : il sera concret, et corriger un brouillon concret va infiniment plus vite que d'affronter une page vide. Vous partez de là, vous élaguez, et vous ajoutez ce que le code ne pouvait pas dire.
Un mot sur l'endroit où ce fichier se pose, car il y en a trois et ils ne rendent pas le même service. À la racine du projet, CLAUDE.md est versionné dans git : c'est le brief de l'équipe, celui dont le bénéfice se multiplie par le nombre de personnes. À côté, CLAUDE.local.md, laissé hors de git, porte ce qui n'appartient qu'à vous : le chemin de votre base locale, un raccourci personnel. Et dans votre dossier personnel, ~/.claude/CLAUDE.md s'applique à toutes vos sessions, tous projets confondus : c'est là que vivent vos préférences durables, jamais les règles d'un projet. L'erreur classique consiste justement à ranger une règle d'équipe dans le fichier personnel, où personne d'autre ne la lira jamais. Claude va aussi chercher les CLAUDE.md des sous-dossiers quand il y travaille, et c'est cette propriété que le chapitre 4 transforme en méthode.
Ma règle préférée pour l'alimenter ne demande aucune discipline particulière : chaque erreur récurrente de Claude devient une ligne. Il a utilisé la mauvaise bibliothèque deux fois ? Une ligne. Il a encore oublié que les textes du site sont dans un fichier centralisé ? Une ligne. Au bout d'un mois, votre CLAUDE.md contient exactement ce qui fait trébucher une IA sur votre projet, et rien d'autre : c'est la définition d'un bon brief.
Vous ne rédigez pas une documentation, vous cicatrisez des erreurs.
Car voici le point contre-intuitif, celui qui distingue les CLAUDE.md utiles des CLAUDE.md décoratifs : ce fichier a un budget. Chaque règle que vous ajoutez dilue l'attention portée à toutes les autres. Un CLAUDE.md de quatre cents lignes n'est pas quatre fois plus suivi qu'un CLAUDE.md de cent lignes : il est ignoré. Trop de règles, plus rien n'est suivi.
Il faut donc élaguer sans pitié : sortir les évidences (« écris du code propre » ne sert à rien), sortir ce que le code dit déjà, sortir les règles mortes dont le piège a disparu. Un bon CLAUDE.md se relit en une minute et chaque ligne a mérité sa place.
La même tâche, avec et sans brief
Rien ne vaut la démonstration, et reprenons pour cela le cabinet de Talia, la kiné du chapitre 1, dont la reconstruction commence ici. Une tâche banale, confiée à Claude sur le projet sans CLAUDE.md : il doit d'abord redécouvrir le monde.
❯ Ajoute un badge « Complet » sur les créneaux pleins. · Claude explore le projet... Lecture de package.json, app/, components/... 14 fichiers. · Claude génère... J'ai ajouté le badge avec styled-components. ❯ Stop : ici tout est en CSS modules, pas styled-components. Un quart du carnet dépensé à redécouvrir le projet, pour aboutir à une convention fausse qu'il faudra défaire.
Même projet, même tâche, mais un CLAUDE.md de quarante lignes attend Claude au démarrage.
❯ claude CLAUDE.md chargé. ❯ Ajoute un badge « Complet » sur les créneaux pleins. · Claude travaille... Badge ajouté dans CreneauCard, styles dans le module CSS existant, libellé ajouté au fichier de textes centralisé. npm run lint : ✓ Bonne convention du premier coup. Le brief a fait le travail avant même votre premier prompt.
L'écart ne tient pas au talent du modèle, identique dans les deux cas. Il tient à ce que la session sans brief dépense son contexte à reconstituer ce que le projet savait déjà, et le reconstitue mal. Multipliez cet écart par toutes les sessions d'un projet, et vous comprenez pourquoi c'est la première chose que je regarde quand j'audite l'usage de l'IA dans une équipe.
Montrez-moi votre CLAUDE.md, je vous dirai comment Claude travaille chez vous.
Les fichiers de cadrage : un par regard sur le projet
CLAUDE.md répond à la question « comment on travaille ici ». Mais un projet, c'est aussi un quoi, un pour qui, un comment c'est construit. Plutôt que de tout entasser dans un fichier obèse (on vient de voir pourquoi c'est une mauvaise idée), je range ces réponses dans des fichiers de cadrage séparés, un par regard sur le projet, que Claude lit quand la tâche le justifie. Quatre me suffisent sur la plupart des projets.
- PRODUCT.mdLe quoi et le pourquoi : ce que le produit est, ce qu'il refuse d'être, les décisions de positionnement.
- DESIGN.mdLa charte : les principes visuels, et surtout les interdits.
- USER.mdLes personas et leurs parcours : qui arrive sur le produit, pour faire quoi, avec quelle patience.
- ARCHITECTURE.mdLes choix structurants et leurs raisons : pas la liste des dossiers (le code la donne), mais les décisions qu'il ne faut pas défaire par inadvertance et le pourquoi qui les protège.
Ce ne sont pas des documents théoriques : le site sur lequel vous lisez ce guide est cadré exactement comme ça. Mon PRODUCT.md est un registre de marque et de refus, et la partie refus travaille plus que le reste : les types de contenus que le site ne publiera pas, le ton qu'il ne prendra jamais. Quand je demande une nouvelle page, Claude propose d'emblée dans les limites, sans que j'aie à les répéter.
Mon DESIGN.md est un journal de design daté : chaque décision visuelle y est consignée avec sa date et sa raison. Quand une session propose de « moderniser » un choix, une ligne datée lui répond déjà : ce choix a été pesé, voilà pourquoi, n'y touche pas sans me demander.
En quinze ans de développement mobile, chez Mappy, WeMoms, Accor ou sur mes propres produits, j'ai vu mourir bien des documents de spécification. Ceux-là survivent pour une raison simple : ils sont relus tous les jours par le membre le plus actif de l'équipe.
L'interview inversée : faites écrire le brief par Claude
À ce stade, une objection monte toujours : « je ne saurai pas quoi écrire dans ces fichiers ». Parfait, car ce n'est pas vous qui allez les écrire. La technique la plus efficace que je connaisse consiste à inverser les rôles : demandez à Claude de vous interviewer, puis de rédiger.
Vous ne rédigez rien, vous répondez à des questions, en langage courant, comme vous parleriez de votre projet à quelqu'un qui s'y intéresse vraiment. Harper Reed a popularisé cette façon de travailler avec les modèles, et elle est redoutable : Claude pose des questions de product owner, y compris celles que vous évitiez.
❯ Tu vas rédiger le PRODUCT.md de ce projet. Avant ça, ❯ interviewe-moi : tes questions une par une, creuse mes ❯ réponses, et rédige seulement quand tu en sais assez. · Claude réfléchit... Première question : qui est l'utilisateur principal, et qu'est-ce qui l'amène chez vous la première fois ? Répondez comme à un ami. C'est Claude qui transformera vos réponses en document structuré.
Vingt minutes de conversation, et vous obtenez un premier PRODUCT.md à relire et amender : corriger une nuance, durcir un refus, couper une généralité. La relecture est votre vrai travail, et elle est agréable : critiquer un document existant est dix fois plus facile que d'affronter une page blanche. La même technique produit vos specs de fonctionnalités, et le chapitre 5 la pousse plus loin avec le travail dirigé par la spec.
Entretenir : élaguer, dater, versionner
Un dossier de brief n'est pas un monument, c'est un document de travail, et il ne vaut que s'il est entretenu. Trois habitudes suffisent.
Et une quatrième, qui les rend presque automatiques : déléguez l'entretien à Claude lui-même. Écrivez une fois dans le brief qu'à la fin de chaque tâche, s'il a découvert un piège, changé une convention ou tranché une décision, il doit mettre à jour le fichier concerné avant de rendre la main. La mémoire du projet cesse alors de dépendre de votre discipline du vendredi soir : elle se met à jour au moment exact où l'information est fraîche. Le chapitre 6 en fait une règle complète, le done élargi.
- ÉlaguerÀ chaque fois que vous ajoutez une ligne, cherchez-en une à supprimer ; le budget d'instructions ne se négocie pas.
- DaterAu moins pour les décisions : une décision datée dit « ceci a été pesé, et voilà quand », ce qui la protège des remises en cause accidentelles et vous permet, six mois plus tard, de juger si elle a encore cours.
- VersionnerEn git, comme du code, parce que c'en est : ces fichiers pilotent ce que Claude produit, une modification du brief mérite le même sérieux qu'une modification du code, revue en pull request comprise.
Dans une équipe, c'est même là que l'effet se multiplie : le piège découvert par l'un cicatrise pour tous, dès la prochaine session de chacun.
Questions fréquentes sur CLAUDE.md
Qu'est-ce que le fichier CLAUDE.md ?
CLAUDE.md est un fichier Markdown placé à la racine d'un projet, que Claude Code charge automatiquement au début de chaque session. Il sert de mémoire de projet : commandes à utiliser, conventions du code, pièges connus du repo. Comme la fenêtre de contexte de Claude repart vide à chaque session, ce fichier est le moyen de lui transmettre une bonne fois ce qu'il doit savoir tous les jours. Il peut importer d'autres documents avec la syntaxe @fichier.
Que mettre dans un CLAUDE.md ?
Trois choses : les commandes du projet (dev, test, lint, build), les conventions maison, et les pièges non évidents du repo. La meilleure source est l'usage : chaque erreur que Claude commet deux fois devient une ligne. À l'inverse, il faut en exclure les évidences, ce que le code montre déjà et les règles périmées, car le fichier a un budget d'attention : trop de règles, et plus aucune n'est suivie. Un bon CLAUDE.md se relit en une minute.
Où placer le fichier CLAUDE.md ?
À trois endroits, qui ne rendent pas le même service. À la racine du projet, CLAUDE.md est versionné dans git : c'est le brief partagé par toute l'équipe. À côté, CLAUDE.local.md reste hors de git et porte ce qui n'appartient qu'à vous, comme le chemin de votre base locale. Dans votre dossier personnel enfin, ~/.claude/CLAUDE.md s'applique à toutes vos sessions, tous projets confondus : réservez-le à vos préférences durables. Claude lit aussi les CLAUDE.md des sous-dossiers quand il y travaille, ce qui permet de donner un brief court à chaque module. Pour démarrer, la commande /init génère un premier fichier à partir de votre dépôt.
CLAUDE.md ou README : quelle différence ?
Les deux cohabitent, car ils n'ont ni le même lecteur ni le même contenu. Le README s'adresse aux humains qui découvrent le projet : présentation, installation, liens. CLAUDE.md s'adresse à un agent qui va modifier le code dans la minute : conventions à respecter, commandes exactes, pièges à éviter, interdits. Il est chargé automatiquement à chaque session, doit rester court pour préserver le contexte, et contient des consignes opérationnelles qu'un README n'a pas vocation à porter.
Comment créer ces fichiers sans savoir quoi écrire ?
Par l'interview inversée : demandez à Claude de vous poser des questions sur votre projet, une par une, puis de rédiger le document à partir de vos réponses. Vous parlez de votre produit en langage courant, il structure. Votre travail se déplace vers la relecture : corriger, préciser, durcir les refus. C'est plus rapide et plus complet que la page blanche, car Claude pose les questions d'un product owner, y compris celles auxquelles vous n'auriez pas pensé.
La suiteVotre collaborateur a maintenant son dossier de brief : il connaît le projet, les conventions, les pièges. Reste la question que ce chapitre a laissée ouverte : où ranger tout cela quand le projet grossit, et pourquoi un brief unique finit toujours par étouffer. Au chapitre 4, la décision qui commande votre facture, vos régressions et votre droit d'ouvrir plusieurs chantiers à la fois : le plan de la maison.
David Silvera
Développeur mobile & web freelance · 15 ans · Android, iOS, React Native, Next.js
Ce guide est tiré de ma pratique quotidienne : ce site lui-même est développé avec Claude, selon la méthode qu'il enseigne. J'accompagne aussi les équipes qui veulent monter en compétence : audit de pratique, formation, mise en place d'outillage.
Discutons de votre équipe