ouvrir guide/chapitre-03 --brief
Chapitre 3 · Acte I · Changer de regard
Le dossier
de brief
11 min · espace pour avancer, flèches pour revenir
L'onboarding
On le fait à toute recrue. On l'oublie systématiquement pour celui qui code le plus.
Le produit, les conventions, les pièges, comment lancer les tests : personne ne dit à une recrue « débrouille-toi ». Claude, si. Et il prend son poste chaque matin sans souvenir de la veille.
CLAUDE.md · ce qu'on y met, et rien d'autre
Un fichier Markdown à la racine, que Claude Code charge automatiquement au début de chaque session.
- 01 · Les commandesLancer le serveur, 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 : ce qu'un ancien dirait à une recrue autour d'un café. « Ce fichier est généré, ne l'édite jamais à la main. »
Et on ne part pas de la page blanche : /init lit votre dépôt et vous rend un premier brouillon concret.
Où le poser
- CLAUDE.md→à la racine, versionné : le brief de l'équipe, dont le bénéfice se multiplie par le nombre de personnes.
- CLAUDE.local.md→hors de git : ce qui n'appartient qu'à vous, le chemin de votre base locale, un raccourci.
- ~/.claude/CLAUDE.md→toutes vos sessions, tous projets : vos préférences durables, jamais les règles d'un projet.
L'erreur classique : ranger une règle d'équipe dans le fichier personnel, où personne d'autre ne la lira jamais.
Le cabinet de Talia · une tâche banale
Sans brief
Il redécouvre le monde
- 14 fichiers lus pour comprendre
- Un quart du carnet dépensé
- styled-components : mauvaise convention
- Il faudra défaire
Avec brief
Il travaille
- 40 lignes lues au démarrage
- Le module CSS existant, comme la maison
- Libellé ajouté au fichier de textes
- Bonne convention du premier coup
Le modèle est identique dans les deux cas. Ce qui change, c'est ce que la session dépense à reconstituer ce que le projet savait déjà.
Comment l'alimenter
Vous ne rédigez pas une documentation. Vous cicatrisez des erreurs.
Mauvaise bibliothèque deux fois ? Une ligne. Oubli du fichier de textes centralisé ? Une ligne. Au bout d'un mois, votre brief contient exactement ce qui fait trébucher une IA sur votre projet, et rien d'autre.
Le point contre-intuitif
400lignes de brief
Un CLAUDE.md de quatre cents lignes n'est pas quatre fois plus suivi qu'un CLAUDE.md de cent lignes : il est ignoré.
Ce fichier a un budget. Chaque règle ajoutée dilue l'attention portée à toutes les autres.
La même énergie, éclatée en trop de règles, n'atteint plus rien.
Un brief est fini quand il n'y a plus rien à enlever.
À vous
Votre CLAUDE.md fait 400 lignes. Vous venez de repérer un nouveau piège. Que faites-vous ?
Choisissez : la scène vous répond.
Un fichier par regard sur le projet
- PRODUCT.mdCe que le produit est, et ce qu'il refuse d'être.
- DESIGN.mdLes principes visuels, et surtout les interdits.
- USER.mdQui arrive, pour faire quoi, avec quelle patience.
- ARCHITECTURE.mdLes décisions structurantes et le pourquoi qui les protège.
Le site que vous lisez est cadré exactement comme ça. La partie « refus » du PRODUCT.md travaille plus que le reste.
« Je ne saurai pas quoi écrire »
Parfait : ce n'est pas vous qui allez les écrire. Demandez à Claude de vous interviewer, puis de rédiger.
Vous répondez en langage courant, comme à quelqu'un qui s'intéresse vraiment à votre projet. Il pose les questions d'un product owner, y compris celles que vous évitiez.
Vingt minutes de conversation
❯ 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é.
Votre vrai travail se déplace vers la relecture. Critiquer un texte existant est dix fois plus facile que d'affronter une page blanche.
Un document de travail, pas un monument
- Élaguer→à chaque ligne ajoutée, en chercher une à supprimer.
- Dater→une décision datée dit « ceci a été pesé », et se juge six mois plus tard.
- Versionner→ces fichiers pilotent ce que Claude produit : revue en pull request comprise.
- Déléguer→écrivez une fois que Claude doit mettre le brief à jour dès qu'il découvre un piège.
Le brief est un capital qui se compose : chaque erreur transformée en ligne rend meilleures toutes les sessions futures. Pour vous, et pour toute l'équipe.
Fin du chapitre 3
Reste la question que ce chapitre laisse ouverte : où ranger tout cela quand le projet grossit, et pourquoi un brief unique finit toujours par étouffer.
La version article garde tout : la FAQ, les détails, les liens. Cette traversée en est la bande-annonce habitée.