Un guide pratique pour rédiger un fichier CLAUDE.md efficace.
Apprenez 21 règles concrètes et vérifiables pour réduire la taille d’un fichier CLAUDE.md surchargé, afin que Claude Code reste fiable, prévisible et facile à utiliser lors de sessions prolongées.
Le mois dernier, un développeur a supprimé 340 lignes d’un fichier CLAUDE.md qui s’était progressivement agrandi au cours d’une année.
Le fichier avait constamment pris de l’ampleur. Chaque fois que Claude Code se comportait de manière irritante, une nouvelle règle était ajoutée. Chaque fois qu’une règle ne fonctionnait pas, une version plus longue était insérée en dessous. En août, le fichier comptait déjà 400 lignes, et le comportement de Claude était nettement pire qu’avant, lorsque le fichier ne contenait que 60 lignes.
Après l’avoir réduit à 61 lignes, une amélioration a été constatée dès le même jour.
Ce n’est pas vraiment une leçon sur la discipline personnelle. C’est plutôt une leçon sur l’objectif d’un fichier de règles. Ce n’est pas une liste de souhaits que l’on accumule avec le temps. C’est un ensemble d’instructions que le modèle lit au début de chaque session, et chacune ligne supplémentaire doit rivaliser pour attirer l’attention avec tout ce qui s’y trouve déjà.
Voici les 21 règles qui ont survécu au filtrage, ainsi que les raisons derrière chacune d’elles.
Le véritable coût d’un CLAUDE.md surchargé
En août 2026, quelqu’un au sein de la communauté Claude Code a décidé de tester quelque chose qui semble évident mais que personne n’avait jamais vérifié concrètement : savoir si Claude respecte réellement les instructions contenues dans le CLAUDE.md qui lui sont données.
Une première analyse a révélé que 55,7 % des règles présentes dans un fichier typique pouvaient en principe être vérifiées. Une revue manuelle a ensuite réduit ce chiffre à 18 %, puis à 8,75 %, pour finalement s’arrêter à 6,67 %.
Restez un instant avec ce chiffre en tête. Dans un CLAUDE.md typique, seulement une règle sur quinze peut réellement être vérifiée. Les quatorze restantes ne sont essentiellement que des recommandations du type : « écrivez du code propre », « suivez les meilleures pratiques », « faites attention à la performance ». Personne, ni le modèle ni vous, ne peut déterminer si ces recommandations ont réellement été suivies.
C’est là le véritable coût d’un fichier surchargé. Il ne s’agit pas seulement du fait que les règles non vérifiables sont ignorées ; c’est aussi qu’elles occupent encore de l’espace dans la fenêtre de contexte à chaque tour, évincant ainsi les règles qui auraient pu être vraiment importantes.
À peu près à la même époque, les ingénieurs d’Anthropic ont fait une observation similaire concernant leurs prompts système : au-delà d’une certaine longueur, l’ajout de plus d’instructions détériore les performances au lieu de les améliorer. Leurs modèles les plus récents sont désormais livrés avec des prompts système dont la taille est bien inférieure à celle qu’ils avaient auparavant.
Votre fichier CLAUDE.md suit exactement le même schéma. Les 21 règles ci-dessous ont été conçues pour vous maintenir du côté productif de cette courbe.
Règles 1–7 : Arrêter les dégâts
Ces premières règles ont pour but d’empêcher Claude de transformer une tâche simple en véritable catastrophe.
Règle 1 : Effectuer uniquement des modifications ciblées
## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file, even if you would write it differently.
Pourquoi cela fonctionne : Sans cette contrainte, Claude a tendance à « améliorer » chaque fichier qu’il touche. Vous demandez une correction en une seule ligne, mais vous finissez par examiner un diff de 200 lignes où la correction réelle est cachée quelque part au milieu. C’est probablement le reproche le plus courant concernant les agents de codage, et aussi l’un des plus faciles à résoudre.
Auparavant : Vous demandez une correction pour une erreur de type « off-by-one » dans un callback. Au lieu de cela, le code est converti en async/await, trois variables sont renommées, et le bug initial reste présent.
Après : Une seule ligne est modifiée. L’examen de cette modification ne prend qu’environ quatre secondes.
Règle 2 : Ne réécrivez jamais mes tests
## Tests
Do not edit existing tests to make failing code pass.
If a test fails, fix the code.
If you believe the test itself is wrong, say so and stop. Do not edit it.
Pourquoi cela fonctionne : Un modèle chargé de faire passer les tests empruntera toujours le chemin le plus court disponible, et réécrire une assertion est plus rapide que de corriger réellement le bug sous-jacent. Cette règle élimine complètement cette solution de facilité.
Auparavant : Trois tests deviennent verts. Deux d’entre eux vérifient désormais quelque chose de incorrect.
Après : Claude indique qu’un test s’attend à recevoir 404 tandis que le code renvoie 500, puis demande lequel est réellement erroné.
Règle 3 : Ne pas ajouter de dépendance
## Dependencies
Do not add packages. Use what is already in package.json.
If you are convinced a new package is needed, name it, name what it
replaces, and stop. Wait for approval.
Pourquoi cela fonctionne : Chaque agent de codage cherche à utiliser une nouvelle bibliothèque de la même manière qu’un développeur junior. Sans contrôle, on se retrouve avec trois packages distincts pour gérer les dates et une taille de bundle que personne ne parvient à expliquer.
Auparavant : Une tâche simple de formatage de date en quatre lignes se transforme en une nouvelle dépendance ainsi qu’en un changement de fichier de verrouillage.
Après : Les mêmes quatre lignes, écrites à l’aide de l’API Intl déjà disponible.
Règle 4 : Aucune gestion d’erreurs pour des situations impossibles
## Error Handling
Handle errors that can actually occur here.
Do not add try/catch around code that cannot throw.
Do not add null checks for values this function is guaranteed to receive.
Pourquoi cela fonctionne : Un code défensif conçu pour se prémunir contre des états impossibles n’est en réalité pas une mesure de sécurité, mais plutôt du bruit. Il masque les deux vérifications vraiment importantes et double la longueur d’une fonction sans aucun avantage.
Auparavant : Une fonction de 12 lignes complétée par quatre clauses de protection, dont trois ne peuvent jamais être déclenchées.
Après : La même fonction de 12 lignes, ne conservant que la seule vérification qui pourrait réellement échouer.
Règle 5 : Ne touchez pas à ce pour quoi on ne vous a pas demandé de le faire
## Scope
Work only on what was asked.
Unrelated dead code, bad names, or missing types: mention them, do not fix them.
Remove imports and variables that YOUR change made unused. Nothing else.
Pourquoi cela fonctionne : L’expansion inattendue du champ d’application, cachée à l’intérieur d’un diff, reste invisible jusqu’à ce que quelqu’un la examine, et à ce moment-là, elle coûte du temps précieux. Définir clairement les limites dès le début élimine les incertitudes quant à ce qui est considéré comme acceptable.
Règle 6 : Ne jamais commiter de secrets
## Security
Never write a key, token, password, or connection string into a file.
Never commit .env, .env.*, or any credentials file.
If a value is needed, reference the environment variable by name.
Pourquoi cela fonctionne : C’est l’un des rares cas où une seule erreur est irréversible. L’instruction est courte, inconditionnelle et facile à vérifier, ce qui correspond exactement à la forme qu’une bonne règle doit avoir.
Règle 7 : Demander l’autorisation avant toute action destructrice
## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, or running a
migration against anything that is not local.
Pourquoi cela fonctionne : Un modèle ne possède pas de notion intégrée de ce qui peut ou ne peut pas être annulé. Du point de vue du modèle, modifier l’historique ou formater un fichier texte relèvent du même type d’action : il s’agit simplement d’une autre invocation d’outil. Cette règle lui fournit une catégorie de risque qu’il ne pourrait pas identifier par lui-même.
Règles 8-14 : Établir des règles qu’il peut réellement suivre
C’est la section qui aborde le problème sous-jacent à ce faible taux de conformité. Ces règles ne concernent pas directement le comportement, mais plutôt la manière de formuler les règles qui le régissent.
Règle 8 : Chaque règle doit être vérifiable
Bad: Write clean, maintainable code.
Good: Functions over 40 lines must be split.
Pourquoi cela fonctionne : Si vous ne pouvez pas jeter un coup d’œil à la sortie et répondre oui ou non, la règle ne sert qu’à occuper de l’espace dans le contexte. Avant d’ajouter une ligne à ce fichier, demandez-vous quelles preuves prouveraient qu’elle a été enfreinte. Si vous ne pouvez pas y répondre, n’ajoutez pas cette règle.
Auparavant : Une instruction comme « écrire du code propre et facile à maintenir » reste inutilisée dans votre fichier pendant des mois. Elle n’influence jamais la sortie et vous ne pouvez jamais citer de cas où elle aurait été violée.
Après : Une fonction de 61 lignes apparaît dans un diff, et vous pouvez pointer directement sur la règle qu’elle enfreint. À partir de là, soit la règle est respectée, soit elle est supprimée. Dans les deux cas, cela fait avancer les choses.
Règle 9 : Une règle, une ligne
Bad: When you are working on components, please try to keep them
focused and reasonably small, and generally avoid mixing data
fetching with presentation where that makes sense.
Good: Components do not fetch data. Fetch in the route, pass props down.
Pourquoi cela fonctionne : Une règle formulée de manière évasive ressemble à une suggestion douce. Les suggestions sont toujours éclipsées par ce que le modèle avait déjà l’intention de faire.
Règle 10 : Donnez un nom au fichier, pas à l’émotion
Bad: Follow our API conventions.
Good: New routes follow the shape in src/api/users/route.ts.
Pourquoi cela fonctionne : Une expression comme « nos conventions » n’a de sens que pour vous, l’être humain. Un chemin de fichier, lui, est quelque chose que le modèle peut réellement ouvrir et lire. Faire référence à du code existant vaut mieux que n’importe quelle description écrite de ce code.
Règle 11 : Interdire plutôt que d’encourager
Bad: Prefer simple solutions.
Good: Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Pourquoi cela fonctionne : Des mots comme « préférer » ne s’appliquent que comme critère de décision en cas d’égalité, et uniquement lorsque le modèle est déjà incertain. En revanche, « ne pas » agit comme une interdiction stricte. Presque toutes les règles qui échouent dans la pratique le font parce qu’elles ont été formulées comme des encouragements plutôt que comme des interdictions.
Il existe un test simple pour cela : lisez la règle et demandez-vous si un modèle déterminé à faire ce que vous essayez d’empêcher pourrait encore techniquement respecter la règle telle qu’elle est écrite. Si c’est le cas, ce que vous avez écrit n’est qu’une préférence, pas une règle.
Règle 12 : Placez la règle là où le travail a lieu
Core rules live in the root CLAUDE.md, not only in path-scoped rule files.
Pourquoi cela fonctionne : Cet élément est facile à manquer et peut provoquer un véritable bug si on l’ignore. En août 2026, une plainte a été déposée contre Claude Code décrivant comment les fichiers de règles spécifiques aux chemins peuvent échouer silencieusement à se charger lorsque l’agent modifie des fichiers via des commandes shell plutôt que son outil d’édition intégré, puisque l’injection de règles est liée à ce processus d’édition. D’autres utilisateurs ont signalé le même problème pour des règles stockées dans des fichiers situés dans des sous-dossiers imbriqués.
Cette leçon reste valable quel que soit le sort réservé à ce bug en particulier. Tout ce dont on ne peut vraiment pas se permettre de négliger doit être placé dans le fichier racine qui est toujours chargé, et non caché dans un fichier conditionnel qui ne l’est que parfois.
Règle 13 : Limiter la longueur du fichier
CLAUDE.md stays under 60 lines. If you need line 61, delete something first.
Pourquoi cela fonctionne : C’est la règle qui a le plus amélioré l’organisation réelle d’une équipe, et elle va à l’encontre de l’intuition. Allonger le fichier à 400 lignes ne signifie pas pour autant que le modèle dispose de 400 règles sur lesquelles agir. Cela crée simplement un bloc de texte dense où les instructions essentielles se mélangent aux éléments superflus.
Sixty lines n’est pas une sorte de seuil magique. Ce qui compte, c’est la contrainte elle-même : ajouter une nouvelle règle doit entraîner l’élimination d’une ancienne, de sorte que seules les règles utiles restent.
Règle 14 : Conserver les règles, les compétences et les flux de travail dans des endroits séparés
CLAUDE.md : rules that apply to every single task
.claude/skills : reference material, read only when relevant
.claude/commands : fixed step sequences, invoked by name
Pourquoi cela fonctionne : La plupart des fichiers de règles trop volumineux le sont parce qu’ils contiennent en réalité trois types différents de documents mélangés. Une description du schéma de votre base de données n’est pas une règle, tout comme la séquence de déploiement. Une fois ce matériel déplacé, les règles restantes redeviennent visibles au lieu d’être enfouies.
Règles 15 à 21 : Permettre au comportement de durer toute une session
Une règle que le modèle suit à la troisième étape mais oublie à la quarantième n’était en réalité jamais une vraie règle. Ce ensemble de directives vise à ce que les instructions restent en vigueur tout au long d’une session.
Règle 15 : Conserver les règles dans le fichier, et non seulement dans la conversation
Any instruction that must hold for the whole project belongs in this file.
Instructions given in conversation apply to the current task only.
Pourquoi cela fonctionne : Les sessions longues sont compressées à un moment donné. Lors de cette compression, les détails de la conversation sont résumés tandis que les fichiers sont rechargés dans leur intégralité. Un compte datant d’août 2026 illustre parfaitement ce phénomène : un utilisateur a demandé au modèle à deux reprises de ne jamais augmenter la version du paquet ; la compression a eu lieu en cours de route, et à la vingtième demande, la version avait malgré tout été mise à jour. Rien ne s’est arrêté ni n’a généré d’erreur — l’instruction avait simplement cessé d’exister dans le contexte de travail du modèle.
Si vous vous surprenez à répéter la même instruction plus d’une fois dans la conversation, considérez cela comme un signal. Elle doit figurer dans le fichier, et non dans vos saisies.
Règle 16 : Recharger le fichier des règles après compression
After any context compaction, re-read CLAUDE.md before the next edit.
Pourquoi cela fonctionne : Il s’agit d’une mesure de protection peu coûteuse contre précisément l’échec décrit dans la Règle 15, et c’est l’une des rares règles où l’on peut confirmer directement le respect des exigences en examinant simplement le texte transcrit.
Règle 17 : Spécifier la commande exacte utilisée pour vérifier le travail
## Verification
Before saying a task is done, run:
npm run typecheck && npm test -- --run
Paste the final line of output. If it fails, fix it. Do not report success.
Pourquoi cela fonctionne : Une instruction comme « assurez-vous que les tests passent » ne donne au modèle rien de concret à exécuter. Une commande shell littérale, en revanche, le fait, et l’exigence d’un résultat affiché permet de vérifier en un coup d’œil l’affirmation de succès, sans avoir à se fier aveuglément à elle.
Règle 18 : Préciser ce que signifie réellement « terminé »
## Done
A task is done when: the change is made, typecheck passes, tests pass,
and you have stated in one sentence what changed and why.
Not done: "this should work", "you may want to verify".
Pourquoi cela fonctionne : Lorsque cette valeur n’est pas définie, le modèle fournit sa propre définition de ce qu’est une tâche terminée, et cette définition est généralement simplement « J’ai généré du texte ». Cette seule règle contribue plus que toute autre à réduire le nombre de fois où, une heure plus tard, on découvre que la compilation est en réalité défectueuse.
Règle 19 : Limiter les retours à une seule modification concrète
When something did not work, name ONE thing to change and why.
Do not list five options.
Pourquoi cela fonctionne : Proposer cinq options différentes en cas d’échec revient en fait à éviter de prendre une décision. Cela rend également impossible de savoir ce qui a réellement résolu le problème, car on ne peut pas déterminer laquelle des cinq suggestions était pertinente.
Règle 20 : Demander plutôt que de deviner
If you need information you do not have, output:
MISSING: <exactly what you need>
and stop. Do not assume a plausible value and continue.
Pourquoi cela fonctionne : C’est peut-être la ligne la plus précieuse de tout le fichier. Presque tous les incidents graves impliquant un agent sont dus au fait qu’il remplit lui-même un détail manquant avec assurance, sans prendre le temps de demander. Un refus coûte trente secondes ; une supposition erronée faite avec assurance coûte toute l’après-midi, et on ne s’en rend généralement compte que plusieurs modifications plus tard.
Auparavant : Le modèle a besoin d’un nom de file d’attente que vous n’avez jamais spécifié. Il utilise par défaut quelque chose comme default, crée une intégration qui semble correcte, et les tâches s’accumulent dans une file d’attente que personne ne consomme. Vous le découvrez des jours plus tard.
Après : Il affiche MISSING: the queue name for the retry consumer. Vous fournissez la réponse en cinq secondes, et le code résultant est correct dès le départ.
Il existe une façon simple de vérifier si cette règle est réellement active : demander quelque chose qui dépend d’informations que vous avez délibérément cachées. Si le modèle répond malgré tout au lieu de signaler cette lacune, la règle n’existe que sur le papier.
Règle 21 : Continuer à éliminer, une règle par mois
Once a month, remove any rule you have not seen violated recently.
Pourquoi ça marche : Les fichiers de règles ont tendance à s’agrandir indéfiniment, car ajouter une nouvelle règle semble être un progrès tandis qu’en en supprimer une paraît être un risque. Mais si une règle n’a pas été utilisée au cours des derniers mois, c’est soit qu’elle n’est plus nécessaire, soit qu’elle n’a jamais vraiment été respectée. Dans tous les cas, elle consomme de l’attention à chaque interaction. La supprimer est le moyen le moins coûteux d’améliorer les performances.
Cinq règles qui ont été supprimées
La suppression de contenu était plus importante que tout ce qui y était ajouté ; voici donc cinq éléments qui se trouvaient auparavant dans un fichier de 400 lignes et qui manquent dans la version actuelle de 61 lignes. Si certains d’entre eux vous semblent familiers, vous pouvez probablement les supprimer ce soir même.
« Réfléchissez pas à pas au problème avant de coder. » C’est déjà le comportement par défaut. Les versions actuelles de Claude Code planifient leur approche avant d’interagir avec les fichiers, sans aucune demande de la part de l’utilisateur. Cette recommandation est un vestige d’habitudes anciennes et ne sert qu’à occuper de l’espace inutilement.
« Faites attention aux problèmes de performance. » Cette recommandation échoue complètement au test de vérifiabilité : quelle référence de performance doit-on prendre en compte ? Elle a été remplacée par deux règles spécifiques et testables concernant l’accès aux bases de données, celles-ci permettant réellement d’identifier des problèmes concrets.
Une description de 90 lignes du schéma de la base de données. Il s’agit de documentation, pas d’une règle. Elle doit figurer dans un fichier de compétences chargé lorsque le modèle effectue des tâches liées à la base de données, et non dans le fichier lu avant chaque tâche, même pour des ajustements aussi simples que ceux apportés au CSS. La suppression de cette section a représenté la plus grande réduction.
« N’utilisez jamais any en TypeScript. » Cette règle n’était pas fausse, mais elle était redondante — le linter l’empêche déjà d’être utilisée. Tout ce que l’outil de développement impose déjà n’a pas besoin d’occuper de place dans le fichier des règles. Si une violation peut être détectée en CI, laissez le CI s’en charger.
« Ajoutez des commentaires utiles. » Chaque tentative de formuler cette phrase a abouti à des commentaires qui se contentaient de répéter la ligne de code qui les précédait. La solution a été de changer l’approche : il ne s’agit pas d’expliquer ce que fait le code, mais uniquement pourquoi il le fait. Cette version est à la fois plus efficace et une ligne plus courte.
Cette logique est constante dans les cinq cas. Deux contenaient des éléments déjà gérés automatiquement par le modèle ou les outils. Deux ne pouvaient être vérifiés de manière concrète. Un était un document de référence présenté sous forme de règle. Cherchez ces mêmes quatre catégories dans votre propre fichier, et les éléments à supprimer apparaîtront rapidement.
Le fichier complet, prêt à l’emploi
# CLAUDE.md
## Stack
Next.js 15 App Router, TypeScript strict, Postgres via Drizzle, Vitest.## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file.## Scope
Work only on what was asked.
Mention unrelated problems, do not fix them.
Remove imports your change made unused. Nothing else.## Abstractions
Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Functions over 40 lines must be split.## Tests
Do not edit existing tests to make failing code pass.
If a test is wrong, say so and stop.## Dependencies
Do not add packages. Use what is in package.json.
To add one: name it, name what it replaces, stop, wait.## Error Handling
Handle errors that can actually occur here.
No try/catch around code that cannot throw.## Patterns
New routes follow src/api/users/route.ts.
Components do not fetch data. Fetch in the route, pass props down.
Database access goes through src/db/queries/. Never inline SQL.## Security
Never write a key, token, password, or connection string into a file.
Never commit .env or .env.*.
Reference environment variables by name only.## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, running a
migration against anything not local.## Verification
Before reporting done, run:
npm run typecheck && npm test -- --run
Paste the final line. If it fails, fix it. Do not report success.## Done
Done means: change made, typecheck passes, tests pass, and one sentence
saying what changed and why.## When Stuck
If you need information you do not have, output:
MISSING: <what you need>
and stop. Do not assume a value and continue.## Reporting
Name ONE thing to change. Not five options.## Persistence
Rules live here, not in chat. After compaction, re-read this file.
C’est tout le fichier — soixante et une lignes.
Qu’avez-vous modifié ?
Après avoir réduit le fichier de 400 lignes à 61 :
- Les réécritures de fichiers ont été interrompues. La règle d’édition ciblée existait également dans la version surchargée. Elle n’a commencé à être respectée qu’une fois qu’elle n’était plus enfouie vers la ligne 213.
- La règle
MISSING:est devenue active. Elle se déclenche désormais environ deux fois par semaine, en s’arrêtant pour demander plutôt que de fabriquer une valeur de configuration. Auparavant, ces deux situations produisaient un résultat incorrect et silencieux. - Les sessions longues ne s’éloignent plus indûment. Le problème lié aux mises à jour de version, ainsi que trois problèmes similaires, a disparu une fois que les règles ont été intégrées dans le fichier au lieu d’être dispersées dans des messages de chat antérieurs.
- Les revues se font plus rapidement, simplement parce que les différences deviennent plus petites. C’est tout le mécanisme — rien de plus complexe que cela.
Il n’existe pas ici de comparaison claire avant/après à présenter, et aucune ne sera fabriquée dans le but de raconter une histoire simplifiée. Ce qui existe, en revanche, c’est un fichier dont la lecture prend une minute, accompagné d’un comportement qui correspond réellement à ce qu’il indique.
Prochaines étapes
- Ouvrez votre fichier CLAUDE.md existant et comptez les lignes.
- Faites-le une fois, en marquant chaque règle pour laquelle vous ne pouvez pas citer de violation concrète en cas d’infraction. Supprimez-les.
- Transformez chaque « prefer » et « try to » en un interdiction stricte « do not. »
- Remplacez toute référence à « nos conventions » par un chemin de fichier réel.
- Si vous n’avez rien de similaire à la Règle 20, ajoutez-la. C’est la seule règle qui justifie de réaliser toute cette démarche.
Après cela, laissez le fichier inchangé pendant un mois. Lorsque vous y reviendrez, trouvez encore une chose à supprimer.
Les règles qui fonctionnent réellement partagent les mêmes caractéristiques : elles sont courtes, absolues et vérifiables. Tout le reste n’est qu’une note pour soi-même que le modèle finit par relire des centaines de fois par jour sans aucun avantage.
Lectures complémentaires
- Comparer les agents AI Frontier : Astra, Flash, Fable et Mythos — Une analyse de la performance des dernières versions des modèles GPT, Gemini et Claude sur des tâches réelles d’agentivité telles que le codage, la navigation et l’utilisation d’outils, et non seulement sur des benchmarks.
- Choisir un framework pour les agents AI Python en 2026 : une comparaison pratique — Compare cinq frameworks pour agents AI Python en fonction de leur gestion des échecs et de la complexité, afin d’aider les lecteurs à trouver l’outil adapté à leur flux de travail.