Ce que vous saurez faire
- Mesurer les mots qui se chargent ensemble dans votre projet par rapport à un budget.
- Appliquer le test de la ligne à chaque ligne et consigner chaque verdict dans un registre des coupes.
- Déplacer chaque ligne coupée vers la bonne destination et laisser un pointeur d'une ligne.
- Mettre en place un seul fichier d'instructions que Claude Code, OpenCode et Kimi Code lisent tous.
- Confirmer son chargement avec /context et revérifier le décompte de mots à chaque changement.
Points clés
- Un CLAUDE.md est trop long quand il contient des lignes sans lesquelles l'agent ne se tromperait pas ; Anthropic vise moins de 200 lignes par fichier, et nous budgétons en mots, pas en lignes.
- Posez une question à chaque ligne : l'agent ferait-il une erreur sans elle ? Ne gardez que les oui.
- Chaque ligne coupée trouve une place : une page de documentation, une règle de dossier, un skill, une étape de workflow, un hook ou la corbeille.
- Gardez CLAUDE.md comme source unique et faites d'AGENTS.md un lien symbolique vers lui : c'est la configuration la plus simple pour que Claude Code, OpenCode et Kimi Code lisent tous les mêmes instructions.
- Remesurez avec un décompte de mots à chaque modification, car un fichier allégé regrossit.
Un CLAUDE.md est trop long quand il contient des lignes sans lesquelles l'agent ne se tromperait pas. La documentation d'Anthropic vise moins de 200 lignes par fichier CLAUDE.md ; nous budgétons en mots, car les lignes masquent la densité. À la fin de ce guide, vous aurez audité votre fichier ligne par ligne, trouvé une place à chaque ligne coupée et mis en place un seul fichier que Claude Code, OpenCode et Kimi Code lisent tous.
Un fichier d'instructions trop long n'est pas un problème d'écriture. C'est un problème de rangement : presque chaque ligne est vraie, elle est simplement au mauvais endroit. Une ligne mal rangée coûte du contexte à chaque session et noie les règles qui comptent. Anthropic le dit sans détour : des fichiers CLAUDE.md surchargés poussent Claude à ignorer vos véritables instructions (Anthropic, Best practices(s’ouvre dans un nouvel onglet)).
Chaque exemple utilise Mossbank, une application de planification fictive pour les entreprises de plomberie et de chauffage. Son fichier et ses chiffres sont inventés ; les budgets et les règles sont ceux que nous appliquons chez Neomanex.
Ce qu'il vous faut avant de commencer
Auditez les fichiers qui se chargent ensemble, pas celui que vous avez ouvert par hasard. L'agent ne voit jamais un fichier seul : Claude Code charge chaque CLAUDE.md depuis le haut du projet jusqu'au dossier où vous travaillez, plus tout ce qu'ils importent.
| Il vous faut | Pourquoi |
|---|---|
| Chaque fichier d'instructions qui se charge dans votre dossier de travail | L'agent paie pour la somme |
Un décompte de mots (wc -w sur macOS ou Linux) | Le budget est en mots |
/context dans Claude Code | Il montre quels fichiers se sont réellement chargés |
Mesurer ce qui se charge vraiment
Nous avons arrêté de compter les lignes. Une ligne de tableau peut contenir un paragraphe : nous budgétons donc en mots et traitons un fichier dense comme un fichier long.
Lancez wc -lw sur chaque fichier, additionnez les mots, puis divisez les mots par les lignes. Au-delà d'environ 15 mots par ligne, les cellules de tableau sont devenues des paragraphes : scindez la cellule ou sortez le contenu.
| Fichier | Cible | Maximum absolu | Pourquoi |
|---|---|---|---|
| Fichier enfant (un sous-dossier) | 500 mots | 750 mots | Il n'ajoute que ce qui manque au parent |
| Racine du projet | 1 200 mots | 1 800 mots | Identité, carte des dossiers, tests, déploiement, pièges ; les enfants portent le reste |
| Racine de l'espace de travail (plusieurs projets) | 2 000 mots | 2 800 mots | Il se charge à chaque session, pour tout type de travail |
| Tout ce qui se charge ensemble | 5 000 mots | 7 000 mots | L'agent paie pour la somme, pas pour un seul fichier |
La cible en lignes d'Anthropic existe parce que « les fichiers plus longs consomment plus de contexte et sont moins bien suivis » (Anthropic, Memory(s’ouvre dans un nouvel onglet)). Les imports comptent en entier : les fichiers importés se chargent eux aussi au lancement.
Le fichier racine de Mossbank fait 420 lignes et environ 9 600 mots : 23 mots par ligne, bien au-delà du maximum absolu de 1 800 mots pour une racine de projet.
Appliquer le test de la ligne à chaque ligne
La question d'élagage d'Anthropic constitue tout l'audit : supprimer cette ligne pousserait-il Claude à faire une erreur ? La discipline consiste à la poser pour chaque ligne, y compris celles que vous avez écrites la semaine dernière.
Qu'est-ce qu'un registre des coupes ? Un registre des coupes est un tableau qui compte une rangée par ligne ou bloc du fichier : la ligne, si l'agent se trompe sans elle, pourquoi, et où va la ligne.
| # | Ligne du fichier de Mossbank | Erreur sans elle ? | Pourquoi | Destination |
|---|---|---|---|---|
| 1 | « Lancer les tests avec make test, jamais pytest seul » | Oui | pytest seul saute les fixtures de base de données | Garder |
| 2 | « price est stocké en centimes (voir models/job.py) » | Oui | Une mauvaise supposition corrompt les données | Garder, avec sa source |
| 3 | Une carte des modules de 60 lignes | Parfois | De la référence, utile pour naviguer | Page de documentation |
| 4 | Comment ajouter un prestataire de paiement, en 14 étapes | Pour cette tâche seulement | Une procédure | Skill |
| 5 | « Dans migrations/, ne jamais modifier une migration déjà exécutée » | Dans ce dossier seulement | Un seul sous-arbre | Règle de dossier |
| 6 | « NE JAMAIS lancer db reset sur staging » | Cela ne doit jamais arriver | La prose n'est qu'indicative | Hook |
| 7 | Release : version, changelog, tag, déploiement, page de santé, demander à Dana avant le tag | À la release seulement | Un ordre et une validation | Étape de workflow |
| 8 | « Indenter avec 4 espaces » | Non | L'outil de formatage l'impose | Supprimer |
| 9 | « L'API compte 37 endpoints » | Non | Faux dès le commit suivant | Supprimer |
| 10 | La liste des paramètres des outils MCP de l'équipe | Non | L'outil envoie son propre schéma | Supprimer |
Deux lignes restent. La ligne 2 ne reste que parce qu'elle nomme le fichier qui la prouve.
Trouver une destination pour chaque ligne coupée
Supprimer est le dernier recours, pas le premier. La plupart des lignes coupées sont des connaissances qui ont leur place là où l'agent ne les lit que lorsqu'il en a besoin.
Posez les questions dans cet ordre. Le premier oui désigne la destination.
| Destination | Accueille | Se charge quand |
|---|---|---|
| Hook | Ce qui doit toujours ou ne jamais arriver | À chaque appel d'outil, et il bloque |
| Étape de workflow | Un processus avec un ordre ou une validation | À cette étape |
| Règle de dossier | Ce qui n'est vrai que dans un dossier | Quand l'agent lit, écrit ou modifie un fichier de ce dossier |
| Skill | Une procédure dont certaines tâches ont besoin | Quand la tâche correspond ; jusque-là, seule sa courte description se charge |
| Page de documentation | La référence : cartes, explications | Quand l'agent suit le pointeur |
| Supprimer | Les décomptes, l'historique, les copies, tout ce que l'agent fait déjà bien | Jamais |
Le hook vient en premier parce que le fichier n'est qu'indicatif : pour bloquer une action quoi que Claude décide, la documentation d'Anthropic recommande un hook PreToolUse. Notre guide pour empêcher Claude Code de supprimer vos fichiers en construit un pas à pas. Dans Claude Code, une règle de dossier est un fichier .claude/rules/ avec un frontmatter paths:, qui cible ici migrations/**, ou un CLAUDE.md enfant dans ce dossier. Nous limitons les nôtres à des chemins précis.
La checklist de release de Mossbank est l'exemple type de la ligne mal rangée : un ordre et la validation de Dana, lus en entier à chaque session, avec la pause de validation laissée à la mémoire. Nous gardons ce genre de processus sous forme de workflows ConvOps(s’ouvre dans un nouvel onglet) : l'agent lit une étape à la fois et la validation est une étape à part entière (comment nous dirigeons notre entreprise avec des workflows). Sortez tous les processus du fichier et il se réduit à un fichier d'identité : c'est la voie radicale, le graph engineering.
Déplacer chaque ligne et laisser un pointeur d'une ligne
Une coupe qui perd de la connaissance n'est pas une coupe. C'est un futur bug : chaque ligne déplacée laisse donc un pointeur derrière elle.
La carte des modules de Mossbank devient docs/module-map.md, et le fichier garde une ligne qui nomme la page. Sur les 420 lignes, 90 restent, 150 partent vers trois pages de documentation, 60 vers deux skills, 30 vers une règle de dossier, 25 vers le workflow de release, 10 vers deux hooks, et 55 sont supprimées. Le fichier finit à environ 100 lignes, les 90 conservées plus 10 lignes de pointeurs, et 1 100 mots, sous la cible de 1 200 mots.
Un import @ n'est pas une coupe. @docs/module-map.md charge la page au lancement quoi qu'il arrive. Un simple pointeur ne charge rien tant que l'agent ne le suit pas.
Un seul fichier pour CLAUDE.md et AGENTS.md
Deux fichiers d'instructions pour trois outils, et chaque outil lit un fichier différent. Nous gardons une seule source et y lions l'autre nom.
Nous avons testé chaque configuration le 9 octobre 2026, avec un mot de code différent dans chaque fichier :
| Configuration dans le dossier du projet | Claude Code 2.1.295 | OpenCode 1.18.31 | Kimi Code 0.31.1 |
|---|---|---|---|
| AGENTS.md seul | Charge AGENTS.md | Charge AGENTS.md | Charge AGENTS.md |
| CLAUDE.md et AGENTS.md, deux fichiers | Charge uniquement CLAUDE.md | Charge uniquement AGENTS.md | Charge uniquement AGENTS.md |
| AGENTS.md en lien symbolique vers CLAUDE.md | Le charge une fois | Le charge une fois | Le charge une fois |
| CLAUDE.md seul | Charge CLAUDE.md | Charge CLAUDE.md | Ne le charge pas |
Deux fichiers séparés divergent, et chaque outil suit alors des instructions différentes. CLAUDE.md seul ne laisse rien à Kimi Code. Gardez CLAUDE.md comme source et lancez ln -s CLAUDE.md AGENTS.md : des quatre configurations testées, c'est la seule où les trois outils lisent le même texte une seule fois. Le nôtre est généré : un script crée AGENTS.md à côté de chaque CLAUDE.md, si bien que chaque dossier a une seule source.
D'après la documentation d'Anthropic, les outils Edit et Write de Claude Code refusent d'écrire à travers un lien symbolique : modifiez donc CLAUDE.md ; sous Windows, faites plutôt de CLAUDE.md un import @AGENTS.md d'une ligne. Supprimez ou déplacez les deux ensemble : un CLAUDE.md supprimé laisse son lien AGENTS.md pointer vers rien.
Vérifier le chargement, puis revérifier à chaque fois que le fichier grossit
Un fichier allégé regrossit inévitablement, car chaque leçon veut vivre dans le fichier que tout le monde lit. La revérification fait partie de la modification, pas d'un jour de grand ménage.
| Vérification | Comment | Ce que vous voyez |
|---|---|---|
| Le fichier s'est-il chargé ? | /context dans Claude Code | La liste Memory files (fichiers mémoire) nomme chaque fichier chargé ; avec le lien symbolique, uniquement CLAUDE.md |
| Dans le budget ? | wc -w additionné sur les fichiers qui se chargent ensemble | Un nombre à confronter au budget, à chaque modification |
| Des contradictions ? (facultatif) | /doctor prompt-audit, Claude Code 2.1.283 ou ultérieur | Les instructions obsolètes ou contradictoires, avec des modifications proposées ; rien ne change tant que vous ne le demandez pas |
Le fichier de Mossbank gagne deux lignes dès la première semaine, deux vraies leçons, et le décompte de mots les repère. La règle : une nouvelle leçon va d'abord à sa destination, et au fichier en dernier.
Commencez par votre processus le plus long. Créez un compte ConvOps gratuit(s’ouvre dans un nouvel onglet), demandez à votre IA d'écrire ce processus sous forme de workflow, puis supprimez-le du fichier. Envie d'un regard extérieur sur les fichiers d'instructions de votre équipe ? Réservez une séance de découverte gratuite.
Les erreurs courantes et les règles qu'elles ont laissées
Chaque règle de notre budget existe parce qu'un fichier s'est trompé, pas parce qu'un guide de style l'a dit. Chaque erreur ci-dessous nous est arrivée, racontée ici sur Mossbank.
| Erreur | Chez Mossbank | Règle qui en découle |
|---|---|---|
| Compter les lignes | Un fichier de 180 lignes à 33 mots par ligne fait environ 6 000 mots | Budgéter en mots ; signaler au-delà d'environ 15 mots par ligne |
| Un contrat sans source | Le fichier dit que price est en euros ; il est en centimes, donc l'agent écrit une remise en euros | Une ligne qui décrit un champ, un type ou une forme cite le fichier qui le prouve |
| Des étapes de déploiement dans un fichier enfant | worker/CLAUDE.md décrit encore l'ancien déploiement et contredit la racine | Le parent possède chaque fait ; un enfant porte au plus un pointeur |
| Les décomptes | « L'API compte 37 endpoints » est faux dès le commit suivant | Décrire, jamais compter |
| Répéter une règle qui se charge déjà | Le fichier recopie les règles de test partagées, avec une option périmée | Pointer vers la règle ; ne jamais la répéter |
Étapes
Mesurer ce qui se charge vraiment
Lancez wc -lw sur chaque fichier d'instructions qui se charge dans votre dossier de travail, imports compris, et additionnez les mots. Comparez chaque fichier et le total au budget de mots, et signalez tout fichier au-dessus d'environ 15 mots par ligne.
Appliquer le test de la ligne à chaque ligne
Pour chaque ligne ou bloc, demandez-vous si l'agent ferait une erreur sans elle. Consignez la ligne, la réponse et la raison dans un registre des coupes, et ne gardez que les oui.
Trouver une destination pour chaque ligne coupée
Posez les questions dans l'ordre : cela doit-il toujours ou ne jamais arriver (hook), y a-t-il un ordre ou une validation (étape de workflow), est-ce vrai dans un seul dossier (règle de dossier), est-ce une procédure pour certaines tâches (skill), est-ce de la référence (page de documentation). Si toutes les réponses sont non, supprimez la ligne.
Déplacer chaque ligne et laisser un pointeur d'une ligne
Déplacez chaque ligne vers sa destination et laissez un pointeur d'une ligne dans le fichier partout où l'agent doit pouvoir la retrouver. Ne comptez jamais un import @ comme une coupe, car les fichiers importés se chargent au lancement.
Un seul fichier pour CLAUDE.md et AGENTS.md
Gardez CLAUDE.md comme source et lancez ln -s CLAUDE.md AGENTS.md dans le même dossier, pour que Claude Code, OpenCode et Kimi Code lisent le même texte une seule fois. Supprimez ou déplacez les deux fichiers ensemble.
Vérifier le chargement, puis revérifier à chaque fois que le fichier grossit
Lancez /context dans Claude Code et confirmez que le fichier figure sous Memory files (fichiers mémoire). À chaque modification, relancez wc -w par rapport au budget, et envoyez chaque nouvelle leçon vers sa destination avant le fichier.
Questions fréquentes
À partir de quelle longueur un CLAUDE.md est-il trop long ?
La documentation d'Anthropic vise moins de 200 lignes par fichier CLAUDE.md. Chez Neomanex, nous budgétons plutôt en mots, car un fichier court fait de lignes de tableau denses coûte quand même cher : environ 1 200 mots pour une racine de projet, 2 000 pour la racine d'un grand espace de travail et 5 000 pour tout ce qui se charge ensemble. Au-delà, ou au-dessus d'environ 15 mots par ligne, le fichier est trop long. Le vrai test se fait ligne par ligne : ne garder que ce qui évite une erreur.
Qui devrait alléger son CLAUDE.md ou son AGENTS.md ?
Les développeurs et les responsables d'équipe dont l'agent de code ignore des règles qu'on lui a données, ou dont le fichier d'instructions grossit à chaque leçon, devraient l'alléger. Chez Neomanex, la règle est d'auditer un fichier dès qu'il dépasse son budget de mots. Résultat : un fichier que l'agent suit et qui coûte moins de contexte à chaque session, avec la connaissance coupée conservée dans des pages de documentation, des skills, des règles de dossier, des workflows et des hooks.
Que dois-je retirer en premier de mon CLAUDE.md ?
Supprimez ce dont l'agent n'a jamais besoin : les décomptes qui deviennent obsolètes, l'historique du projet, les copies d'autres fichiers, les listes de paramètres d'outils que l'outil envoie déjà et les règles de style qu'un outil de formatage impose. Le standard Neomanex les classe en suppressions directes, car elles coûtent du contexte et n'apportent rien. Déplacez ensuite la référence vers des pages de documentation, et les processus avec un ordre ou une validation vers des workflows, là où Neomanex les garde, dans ConvOps.
Importer des fichiers avec @ raccourcit-il mon CLAUDE.md ?
Non. Chez Neomanex, nous comptons chaque import @ dans le budget de mots, car la documentation d'Anthropic indique que les fichiers importés se chargent eux aussi au lancement : un import déplace le texte sans réduire son coût. Une vraie coupe, c'est une page de documentation avec un pointeur d'une ligne, un skill ou une règle limitée à un chemin, car chacun ne se charge que lorsque l'agent en a besoin.
Pourquoi Claude n'utilise-t-il pas mon AGENTS.md ?
Claude Code ne lit AGENTS.md que lorsqu'aucun CLAUDE.md n'existe dans le dossier ou au-dessus. Neomanex l'a testé sur Claude Code 2.1.295 en octobre 2026 : avec les deux fichiers présents, il n'a chargé que CLAUDE.md. La solution est une seule source par dossier : gardez CLAUDE.md et faites d'AGENTS.md un lien symbolique vers lui, ou, sous Windows, faites de CLAUDE.md un import @AGENTS.md d'une ligne.
Un AGENTS.md trop long, est-ce le même problème qu'un CLAUDE.md trop long ?
Oui, et il demande le même audit. Neomanex a testé OpenCode 1.18.31 et Kimi Code 0.31.1 en octobre 2026 : les deux lisent AGENTS.md, OpenCode ignore CLAUDE.md quand un AGENTS.md existe, et Kimi Code ne charge pas le CLAUDE.md d'un projet. Un seul CLAUDE.md allégé, avec AGENTS.md en lien symbolique vers lui, sert Claude Code, OpenCode et Kimi Code avec le même texte.
Comment corriger l'erreur « prompt is too long » dans Claude ?
Lancez /context dans Claude Code pour voir ce qui remplit la fenêtre de contexte, puis lancez /compact ou démarrez une nouvelle session. Chez Neomanex, nous traitons cette erreur (« prompt is too long », soit un prompt trop long) comme le signe d'une conversation pleine, un problème différent d'un fichier d'instructions trop long. Un CLAUDE.md allégé aide quand même, car il se charge avant votre premier message et chaque session démarre plus légère.