Claude s’étouffe. Encore. Ce fichier CLAUDE.md monstrueux que vous lui avez servi — 250 lignes d’instructions zélées, listes d’outils, cas limites, citations motivantes — tout y est, pondu par un LLM pour une couverture totale. Pourtant, l’agent patine sur un banal refactor.
Reculez d’un pas : ce n’est pas une erreur d’utilisateur. Les chercheurs de l’ETH Zurich viennent de lâcher une étude choc sur 138 fichiers d’agents pour divers agents de codage IA. Les versions humaines punchy sous 60 lignes ? +4 % de succès. Les tomes crachés par LLM au-delà de 200 lignes ? -3 % de succès, et 20 % de jetons en plus.
C’est quoi au juste un fichier CLAUDE.md ?
C’est la sauce secrète d’Anthropic pour le codage agentique : un fichier markdown posé à la racine de votre repo qui dit à Claude (ou agents compatibles) comment se tenir. Une constitution de projet, en somme : règles, outils, workflows. Mais la plupart ? Du réchauffé. Parce que tout le monde court après l’exhaustivité, pas la clarté.
Voici la citation de l’ETH qui tape dans le mille :
Fichiers humains concis (< 60 lignes) : +4 % de taux de succès
Fichiers LLM verbeux (200+ lignes) : -3 % de taux de succès, +20 % de coût en jetons
Les fichiers générés par LLM dégradent les agents. Aïe.
Et ma sauce perso, absente de l’étude : ça rappelle les guerres de configs Vim dans les années 90. Les geeks farcissaient leur .vimrc de plugins à n’en plus finir — jusqu’à ce que Minimal ViM explose. On entre dans l’ère du minimalisme des prompts pour le dev IA ; ça va devenir le remix de la philosophie Unix : une chose, et la faire à la perfection.
Pourquoi la verbosité plombe votre agent ?
Simple. Les agents ne sont pas des avocats disséquant du jargon légal ; ce sont des détecteurs de patterns sous contrainte de jetons. Inondez-les de bruit, et la fenêtre de contexte sature — les instructions clés se noient dans le superflu.
Mais creusez l’archi. Le transformer sous-jacent de Claude (vous vous en doutiez) s’appuie sur des mécanismes d’attention qui se diluent sur de longs contextes. Les tests de l’ETH montrent que les fichiers verbeux font bondir les risques d’hallucination de 15 %, le modèle se focalisant sur des « best practices » hors sujet au lieu de la vraie structure de votre repo.
Bref, ce n’est pas que du coût. C’est cognitif. Un fichier de 60 lignes, c’est une spec API affûtée — prescriptive, sans graisse. Au-delà ? Vous élevez un gamin sur La Guerre et la Paix.
Le principe des 60 lignes n’est pas sorti d’un chapeau. Il est éprouvé : titre (5 lignes), règles de base (15), outils (10), workflows (20), métriques (10). Total : directive incisive.
À bannir : les dumps de doc (« Lisez notre wiki ! »), les manifestes LLM (« Vous êtes un ingénieur 10x qui… »), les fichiers fourre-tout.
Anti-patterns : la galerie des catastrophes
Premier coupable : le dump de documentation. « Voyez README.md pour le setup. » Les agents détestent l’indirection — ils ne « voient » pas les fichiers dynamiquement sans fetch explicite, qui bouffe des jetons.
Pire : le manifeste LLM. Pages de fluff personnel. « Soyez curieux, empathique, sceptique. » Mignon, mais ça noie le signal. Données ETH ? Ça fait chuter le succès de 7 % sur les tâches logiques.
Et le fichier fourre-tout — outils, règles, exemples, historique. Ville-bidonville. (Astuce pro : les agents parsent séquentiellement ; enterrez les pépites à la ligne 180, elles sont mortes.)
Disclosure progressive : les Skills au secours
Pas de dump. Du layering. Exploitez la fonctionnalité Skills de Claude — extensions modulaires chargées à la demande. Le CLAUDE.md de base reste light ; les skills gèrent les niches comme « debug » ou « déploiement ».
Comment ? Épinglez-les à des chemins de fichiers. L’agent détecte le besoin (via matching sémantique), les charge. Boum — fenêtre de contexte préservée, flexibilité en prime.
Ça ? Changement d’archi. Des prompts monolithiques à un OS agentique composable. Pourquoi ça comp
