Écrivez CLAUDE.md comme une constitution : interdictions, règles de comportement, décisions par défaut. 92 commits en 5 jours, sans dérive.
En 5 jours, j'ai poussé 92 commits et mis un produit en production (github.com/defi-io/smarts). Pas d'embardée, pas de rollback, pas de gros refactor. Pas parce que Claude est un génie. Mais grâce aux 565 lignes du CLAUDE.md à la racine du projet.
Cet article explique comment écrire un CLAUDE.md qui fonctionne comme une constitution, et ce qui se passe ensuite.
Beaucoup écrivent CLAUDE.md comme un README — ce qu'est le projet, comment le lancer. C'est du gâchis.
Le README est pour les humains. CLAUDE.md est pour Claude. Claude le charge automatiquement au début de chaque session. Chaque ligne que vous y mettez devient une précondition pour toutes ses décisions ultérieures.
Style README, vous obtenez ceci : Claude sait à peu près ce qu'est le projet, sait lancer les tests, mais prend chaque décision technique à partir de zéro.
Style constitution, vous obtenez ceci : Claude sait quelles routes sont fermées, quelles conventions sont obligatoires, vers où pencher par défaut à chaque embranchement, et quand s'arrêter pour demander.
La différence : le premier va « tant qu'on y est » ajouter une nouvelle dépendance, glisser une couche d'abstraction, retoucher le Gemfile. Le second non.
Le projet sur lequel je travaille s'appelle smarts.md — une plateforme qui génère des live docs et des serveurs MCP pour les smart contracts. Son CLAUDE.md fait 565 lignes, en sections :
1. Identité du projet (5 lignes)
2. Cœur produit (définition en une phrase + différences structurelles avec les concurrents)
3. Stack technique (contraintes dures, format YAML)
4. Liste des interdits (items ❌ explicites)
5. Périmètre (limites dures du MVP)
6. Architecture (avec diagramme ASCII)
7. Arborescence (responsabilités par fichier)
8. Conventions Ruby (avec extraits do/don't)
9. Stratégie de cache (en tableau)
10. Exigences de tests
11. Détails de déploiement
12. Workflow Git
13. Règles d'usage de Claude Code (instructions de comportement)
14. Jalons à 90 jours
15. Principes fondamentaux
Aucune section n'est décorative. Je sélectionne ci-dessous quelques-unes et explique pourquoi elles sont écrites ainsi.
La mienne ressemble à ça :
❌ Pas de service TypeScript / Node.js
❌ Pas de ethers.js / web3.js
❌ Pas de Sidekiq (utiliser Solid Queue)
❌ Pas de React / Vue / Svelte (utiliser Hotwire)
❌ Pas de Redis (Solid Cache / Solid Queue / Solid Cable couvrent tout)
❌ Pas de contrats non vérifiés (uniquement vérifiés sur Etherscan)
❌ Pas de Solana / Bitcoin / Move (uniquement EVM)
C'est un projet Web3. Le défaut du Web3 est TypeScript + ethers.js + Redis + React. Je vais à contre-courant. J'ai mes raisons, mais Claude ne les connaît pas. Sans liste d'interdits, Claude appuiera ses recommandations sur le « bon sens de l'industrie » enfoui dans ses données d'entraînement — et ce sera presque sûrement la voie TypeScript.
Avec la liste, Claude arrête de demander « on ajoute un service Node pour faire tourner web3.js ? ». Cette route est fermée par défaut.
La clé : chaque entrée doit être explicite et absolue. N'écrivez pas « essayer d'éviter TypeScript ». Écrivez « pas de TypeScript ». Tout ce qui est flou, Claude le lit comme négociable.
Le dernier gros bloc de CLAUDE.md s'intitule « Règles d'usage de Claude Code » :
### Quand je dis « commence X »
1. Vérifie d'abord si les contraintes de CLAUDE.md autorisent cette approche
2. Cherche ensuite si une implémentation existe déjà (ne pas réinventer)
3. Avant d'écrire du code, ouvre une nouvelle branche
4. Une fois l'implémentation faite, lance les tests
5. Pas de commit auto — quand le code est écrit et les tests verts, arrête-toi
et fais ton rapport. Attends que je dise explicitement "commit"
### Quand je dis « j'ai une idée »
N'écris pas de code tout de suite. D'abord :
1. Confirme la compréhension (reformule)
2. Évalue par rapport aux contraintes de CLAUDE.md
3. Pointe les problèmes potentiels ou de meilleures alternatives
4. Attends ma confirmation avant d'agir
### Face à un embranchement technique
Quand CLAUDE.md ne précise pas :
1. Privilégie par défaut l'option la plus « Rails-native »
2. Privilégie par défaut l'option avec le moins de dépendances
3. Privilégie par défaut l'option qui permet à un solo dev d'itérer plus vite
4. En cas de doute, arrête-toi et demande
Cette partie pèse dix fois plus que « utilise snake_case ».
Le style de code, Claude l'apprend en lisant le code. Mais « quand s'arrêter pour demander », « en entendant 'j'ai une idée', reformuler avant d'écrire du code » — ce sont des schémas de comportement. Le code seul ne les enseigne pas.
La ligne la plus cruciale : vers où pencher par défaut à un embranchement. Cette seule règle décide ce que fait Claude quand vous n'êtes pas dans la pièce (quand vous lancez juste « commence X » et partez). Écrivez-la clairement et vous pouvez le laisser bosser sans surveillance.
L'en-tête du CLAUDE.md dit :
Ce document est la « source primaire » du projet. Chargé automatiquement au début de chaque session Claude Code. Quand vous changez des décisions techniques, modifiez ce fichier d'abord ; le code suit.
C'est un contrat de workflow. Quand je décide de changer un choix technique — disons, passer le modèle IA principal de gpt-5-mini à gpt-5 — la première étape n'est pas de toucher l'initializer. La première étape est d'éditer ce passage de CLAUDE.md :
ai:
fast: gpt-5-mini # avant
fast: gpt-5 # après
Ensuite je laisse Claude relire CLAUDE.md et aligner le code.
Pourquoi ? Parce que si vous changez une valeur dans le code et que CLAUDE.md reste en arrière, la prochaine fois Claude lit CLAUDE.md, voit la vieille valeur et « gentiment » revient sur votre code. Le conflit naît d'un point unique de défaillance — CLAUDE.md désynchronisé. Une constitution en retard sur la réalité, c'est ainsi qu'éclatent les guerres civiles.
Traiter CLAUDE.md comme une constitution signifie : il court toujours en avant du code.
smarts.md, 5 jours, 92 commits :
Durée de vie moyenne d'une PR : 30 minutes. Pas de gros refactor. Pas de « attend, cette direction était fausse, rollback ».
Pas parce que Claude fait de la magie. Parce qu'à chaque session il roulait sur 565 lignes de rails. Il savait ne pas amener TypeScript, savait que Solid Queue était la file par défaut, savait que les fonctions view sont en cache 60 secondes, savait que chaque service doit implémenter une méthode de classe call, savait attendre ma confirmation avant de commiter.
Retirez la moitié de ces contraintes et vous obtenez : 30 minutes par jour à expliquer « pourquoi on n'utilise pas X », 5 minutes à relire la dépendance qu'il a glissée « tant qu'on y est », et un Gemfile qui s'effrite.
Ne partez pas d'une feuille blanche. Partez de la décision la plus récente qui a fait mal.
Si dernièrement Claude « tire sans cesse de nouvelles dépendances », écrivez la liste des interdits.
Si c'est « il change l'architecture pour un rien », écrivez le diagramme + « ajout de microservice, changement de DB, etc. nécessitent confirmation ».
Si c'est « il n'écrit pas de tests », écrivez « ce qui doit être obligatoirement testé en unitaire ».
Si c'est « il commite trop agressivement », écrivez « pas de commit auto, attendre instruction explicite ».
Une douleur, une entrée. Le reste, pas pour l'instant.
Trois mois plus tard, vous aurez un CLAUDE.md de 500 lignes où chaque ligne est adossée à un « je ne veux plus qu'il fasse ça » concret. Ce document bat n'importe quel template, parce qu'il est calibré précisément pour votre projet, votre flux, votre équipe (même si elle se résume à vous).
Une constitution ne s'écrit pas d'un seul jet. Elle cristallise, conflit après conflit.
Source : github.com/defi-io/smarts