CLAUDE.md est le nouveau .env — Et la plupart des développeurs le traitent comme un README
J'ai ensuite regardé ce que Boris Cherny — le type qui a créé Claude Code — met dans le sien. Et ce que Trail of Bits utilise dans leurs repos d'audit sécurité. Et ce que les équipes qui gagnent les hackathons d'Anthropic utilisent pour surpasser de vrais ingénieurs seniors.
Mon CLAUDE.md fait maintenant plus de 200 lignes. La qualité de mes résultats a explosé. Dans le bon sens.
TL;DR : Votre CLAUDE.md est probablement un README glorifié. Il devrait être traité comme votre .env — sacré, spécifique au projet, et jamais négligé. Voici comment j'ai restructuré le mien sur 4 repos de production, quels patterns ont réellement changé le comportement de Claude, et pourquoi la plupart des "tips CLAUDE.md" sur X vous mènent vers des résultats pourris.
Votre Budget d'Instructions Est Plus Petit Que Vous Ne Le Pensez
Oubliez ce qu'il faut mettre dans CLAUDE.md une seconde. Parlons de ce qui arrive quand vous en mettez trop.
L'analyse d'HumanLayer (référençant un papier arxiv sur les limites de suivi d'instructions) suggère que les modèles de pointe peuvent suivre de manière fiable environ 150-200 instructions. Leur décortiquage du prompt système de Claude Code comptait ~50 instructions intégrées avant même que votre CLAUDE.md ne se charge.
Les chiffres exacts sont débattables — mais la tendance ne l'est pas. À un moment donné, ajouter plus de règles rend Claude moins bon pour suivre toutes les règles, pas seulement les nouvelles.
La conformité chute uniformément.
La conformité chute uniformément. Les règles qui vous importent le plus sont ignorées au même rythme que le remplissage que vous avez oublié de supprimer.
C'est pourquoi chaque ligne compte. Et c'est pourquoi les tweets viraux montrant des fichiers CLAUDE.md de 400 lignes qui "font de Claude un ingénieur 10x" sont activement contre-productifs. Les auteurs sont bien intentionnés — mais leurs followers bourrent leurs fichiers de règles que Claude arrête silencieusement de suivre après la centième.
Le contexte est un budget. Dépensez-le comme l'argent du loyer, pas comme des jetons de casino.
Le pire ? La moitié de ce que la plupart des gens mettent dans CLAUDE.md, Claude peut déjà l'inférer. Votre stack tech est dans package.json. La config TypeScript est dans tsconfig.json. Les règles de linter sont dans .eslintrc. Claude lit tout ça. Les répéter brûle des slots d'instructions sur des trucs qui ne changent rien.
Un test pour chaque ligne : "Supprimer ça ferait-il que Claude fasse une erreur dont il ne peut pas se remettre ?" Si vous supprimez "utilise TypeScript" et que votre projet a un tsconfig.json — rien ne se passe. Si vous supprimez "les queries Convex ne peuvent pas appeler de mutations, utilise des actions" — Claude génère du code qui passe le type checker et explose au runtime.
N'incluez que ce que Claude ne peut pas comprendre seul.
Ce Qui Clochait Vraiment Avec Mon Fichier de 47 Lignes
Mon ancien CLAUDE.md, paraphrasé (parce que je ne vais pas me faire subir l'embarras de la vraie version) :
# Mon Projet SaaS
Stack: Next.js, Convex, Clerk, Supabase, Tailwind
Version Node: 20
Gestionnaire de paquets: pnpm
## Règles
- Utilise TypeScript
- Écris des tests
- Ne supprime pas le fichier .env
Onze lignes "d'information" que Claude pouvait extraire de mon repo en 3 secondes. Le reste, c'étaient des platitudes. "Écris du code propre." "Suis les bonnes pratiques." "Garde les composants petits." Petits comment ? Petits comme un composant React ou petits comme un microservice ? Claude ne sait pas, alors il devine, et sa supposition est fausse environ 40% du temps.
Je brûlais mon budget d'instructions en disant à Claude des choses qu'il savait déjà, et je ne lui disais rien sur les choses qu'il ne pouvait pas savoir — les séquences de workflow, les étapes de vérification, le piège Convex deploy-before-build qui m'a coûté un dimanche entier en février à débugger une panne de production qui n'aurait pas dû arriver.
Ce dimanche-là, j'ai reconstruit le fichier de zéro.
La Restructuration : Ce Qui Va Vraiment Dedans
J'ai épluché les threads de Boris Cherny (il a créé Claude Code — ses conseils ont du poids), le repo de config publique de Trail of Bits, le guide Dometrain, et environ 40 vrais fichiers CLAUDE.md sur GitHub.
Le pattern était cohérent : les meilleurs fichiers ne sont pas les plus longs. Ils sont les plus spécifiques sur les modes de défaillance.
1. Commandes Qui Incluent Comment Elles Plantent
## Commandes
Lance TOUTES les commandes depuis la racine du projet sauf indication contraire.
### Dev
- `pnpm dev` — démarre Next.js sur :3000. Le serveur dev Convex doit tourner séparément.
- `npx convex dev` — lance dans un SECOND terminal. Échouera silencieusement si CONVEX_DEPLOY_KEY manque dans .env.local
### Test
- `pnpm vitest run src/path/to/file.test.ts` — lance UN SEUL fichier de test. Ne lance jamais la suite complète sauf demande explicite.
- Les tests d'intégration nécessitent une instance Convex dev qui tourne.
### Deploy
- `pnpm build && npx convex deploy` — build TOUJOURS en premier. Convex deploy seul utilisera des fonctions obsolètes.
- Si le deploy traîne >30s, tue-le. Vérifie `npx convex logs` pour les erreurs de validation de schéma.
Pas juste quoi taper. Ce qui foire et comment récupérer. Le conseil central de Boris : donne toujours à Claude un moyen de vérifier son propre travail. Tests, diffs, logs. Sans vérification, tu n'as que des impressions.
2. Décisions d'Architecture, Pas Descriptions d'Architecture
Avant je listais ma structure de fichiers. Gaspillage de tokens — Claude lit votre arbre de fichiers de toute façon.
Maintenant je documente le pourquoi derrière les choix que Claude ne peut pas inférer :
## Décisions d'Architecture
- Auth: Clerk gère toute l'auth. NE JAMAIS implémenter de logique d'auth custom.
- Base de données: Convex pour les données temps réel. Supabase pour le stockage de blobs UNIQUEMENT. N'utilise PAS Supabase pour les données structurées.
- État: Pas de librairie d'état client. Les queries réactives Convex remplacent useState pour toutes les données serveur.
- Styling: Tailwind uniquement. Pas de CSS modules, pas de styled-components.
Chaque ligne élimine une catégorie entière d'erreurs.
Avant que cette section existe, Claude créait périodiquement des tables Supabase pour les données utilisateur alors que Convex était juste là. Petites décisions qui se transformaient en sessions de refactoring que je n'avais pas budgétées.
3. La Boucle d'Auto-Amélioration
C'est peut-être le pattern avec le plus fort effet de levier dans tout le fichier.
Après que Claude fait une erreur, tu ne la corriges pas juste. Tu dis à Claude d'ajouter une nouvelle règle à CLAUDE.md pour qu'il ne refasse jamais cette erreur :
"Corrige le bug où tu importais depuis @clerk/nextjs/server sur un composant client.
Puis mets à jour CLAUDE.md avec une règle pour ne plus jamais faire ça."
Mon CLAUDE.md a maintenant une section ## Règles Apprises en bas qui est entièrement écrite par Claude :
## Règles Apprises (auto-générées, révise périodiquement)
- NE JAMAIS importer depuis `@clerk/nextjs/server` dans les fichiers sous `src/app/(dashboard)/`
- Les fonctions `query` Convex ne peuvent pas appeler de fonctions `mutation`. Utilise `action` pour les effets de bord.
- `useQuery` de convex/react retourne `undefined` pendant le chargement, pas `null`. Gère les deux.
- Les nouvelles routes API vont dans `src/app/api/` PAS `src/pages/api/` (App Router uniquement)
Avec le temps, cette section devient la partie la plus précieuse du fichier. Un changelog vivant de chaque erreur que Claude a faite sur votre projet spécifique. Connaissance qui s'accumule, pas erreurs qui s'accumulent. Si ça vous dit quelque chose — c'est la même philosophie derrière les Prompt Contracts : des contraintes structurées qui s'accumulent au lieu de se dégrader.
Le piège : éditez impitoyablement. Boris met en garde contre ça aussi.
Les fichiers gonflés font que Claude ignore tout — y compris les règles qui comptent le plus. Je taille toutes les deux semaines. Les règles redondantes sont fusionnées. Les évidentes sont coupées.
4. Garde-Fous de Sécurité
OK cette section existe parce que j'ai réalisé un matin que j'avais zéro protection contre rm -rf dans mon CLAUDE.md et que j'utilisais Claude Code dans mes repos de production depuis des mois. Cool. Cool cool cool. 😐
## Sécurité
- NE JAMAIS lancer `rm -rf` ou `rm -fr`. Utilise la commande `trash` à la place.
- NE JAMAIS modifier .env, .env.local, ou .env.production sans permission explicite.
- NE JAMAIS push directement sur `main`. Crée toujours une branche feature.
- NE JAMAIS lancer `npx convex deploy --prod` sauf si je dis explicitement "deploy en production."
Claude est un modèle probabiliste entraîné sur internet. rm -rf node_modules apparaît dans dix milliards de réponses Stack Overflow. Une mauvaise lecture de contexte et votre dossier src/ devient un doux souvenir.
Votre .env protège vos secrets. Votre CLAUDE.md protège votre code source. Même énergie. Même discipline.
5. Le Pattern Router
Pour tout ce qui est plus gros qu'un projet de weekend, un fichier ne suffit pas. Mais un fichier gonflé est pire qu'aucun. La solution : utilisez le CLAUDE.md racine comme table des matières.
# Racine du Projet
Voir @docs/convex-conventions.md pour les patterns de base de données
Voir @docs/api-patterns.md pour les conventions de routes API
Voir @docs/testing-guide.md pour la structure de test et les commandes
Claude Code résout @path/to/import nativement. Le CLAUDE.md racine se charge à chaque session. Les fichiers importés se chargent à la demande. Votre racine reste sous 100 lignes. Instructions totales quand vous travaillez dans une zone donnée : confortablement sous le plafond de 150-200. (Et si vous vous demandez si certaines de ces définitions d'outils devraient être des CLIs plutôt que des MCPs — moins d'outils en contexte signifie moins d'instructions brûlées.)
Trail of Bits pousse ça plus loin avec .claude/rules/ — des fichiers markdown scopés qui se chargent automatiquement selon le chemin de fichier :
---
paths: src/api/**/*.ts
---
# Règles API
- Tous les endpoints doivent inclure une validation d'entrée
- Utilise le format de réponse d'erreur standard
Règles API pour votre dossier API. Règles de test pour votre dossier de test. Claude ne charge que ce qui est pertinent. Mon SaaS a 3 zones — site marketing, dashboard, API — chacune avec son propre fichier de règles. Le CLAUDE.md racine ne dépasse jamais 100 lignes.
Mon Template Réel
Pas une version aseptisée. C'est le vrai squelette, commentaires inclus :
# [Nom du Projet]
## Contexte Critique
[2-3 lignes max. Ce que c'EST et la seule chose que Claude ne doit jamais foirer]
## Commandes
[Commandes exactes avec modes de défaillance. Pas un man page - un guide de survie]
## Décisions d'Architecture
[Seulement le POURQUOI derrière les choix que Claude ne peut pas inférer du code]
## Sécurité
[Limites dures. Oui, j'ai une section Sécurité. Oui, j'ai appris à mes dépens.]
## Style
[SEULEMENT ce que les linters n'appliquent pas. Si eslint l'attrape, supprime-le d'ici]
## Règles Apprises
[Écrit par Claude. La meilleure section du fichier. Taille-la ou elle bouffe tout le reste]
@docs/[zone]-conventions.md
Sept sections. Pas de "vue d'ensemble du projet" qui répète le README. Pas de stack tech qui duplique package.json.
Claude Code supporte aussi les Skills (.claude/skills/ — workflows à la demande qui ne se chargent pas à chaque session) et Auto Memory (~/.claude/projects/*/memory/ — notes que Claude écrit pour lui-même entre les sessions, opt-in avec CLAUDE_CODE_DISABLE_AUTO_MEMORY=0). Les deux réduisent ce dont vous avez besoin dans le fichier racine. Mais CLAUDE.md est la fondation — réussissez-le d'abord.
Le Vrai Déclic
Le vrai changement n'était pas d'apprendre quoi mettre dans CLAUDE.md. C'était d'apprendre quoi enlever.
J'ai supprimé la section stack tech.
Supprimé les règles de "style de code" que mon linter applique déjà. Supprimé les platitudes vagues qui n'accomplissaient exactement rien. Ce qui restait, c'étaient les choses qui empêchent Claude de faire des erreurs que seul un humain qui a travaillé sur ce projet pendant des mois saurait éviter.
La connaissance institutionnelle de votre projet, compressée dans la plus petite surface possible. Lue à chaque session. Taillée à chaque sprint.
Traitez-la comme votre .env. Chaque ligne mérite sa place ou elle est coupée.
Vous avez un pattern CLAUDE.md qui a changé votre workflow ? Ou une histoire de guerre sur une règle que vous auriez aimé écrire plus tôt ? Je collectionne ça pour un suivi. Abonnez-vous — le prochain porte sur comment transformer la boucle d'auto-amélioration en système qui s'accumule sur toute votre stack.
Medium n'envoie des emails aux abonnés que quand je publie — pas de spam, pas de digest. Un article atterrit dans votre boîte mail, vous le lisez ou pas. Mieux que de rafraîchir le feed.
Dans mon dernier article, je dévoile comment transformer votre CLAUDE.md en véritable configuration de production, au-delà du simple README.