Anthropic et ETH Zurich : un CLAUDE.md trop long dégrade le travail de l'agent et fait grimper la facture

CLAUDE.md et AGENTS.md ont été conçus comme un moyen rapide d'expliquer à un agent les règles d'un projet, mais une nouvelle étude montre qu'un contexte long nuit plus souvent qu'il n'aide. Sur un échantillon de 138 dépôts Python, les chercheurs de l'ETH Zurich ont constaté une baisse du taux de réussite et une hausse des coûts, surtout avec les fichiers générés automatiquement.

Ce que montre l'étude

Les auteurs de Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? ont pris 138 dépôts réels, rassemblé 5694 pull requests et soumis les tâches à quatre modèles : Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini et Qwen3-30B. Ils ont comparé trois scénarios : sans fichier spécial, avec des instructions générées par un LLM et avec des AGENTS.md entretenus par des humains. Le point est important : l'étude ne porte pas sur des démos abstraites, mais sur des tâches réelles issues de bases de code en production.

Le principal résultat pour les fichiers créés automatiquement est décevant. Le taux de réussite a baissé de 3 % en moyenne, tandis que le coût d'inférence a augmenté de plus de 20 %. Les fichiers rédigés par des humains s'en sortent mieux : ils améliorent la réussite d'environ 4 %, mais le coût grimpe aussi de près de 19 %. Autrement dit, le fichier de contexte n'est pas un accélérateur gratuit. Même quand il aide, le gain de qualité reste modeste face au surcoût permanent en tokens et aux étapes superflues de l'agent.

Pourquoi un fichier long gêne

L'observation la plus contre-intuitive de l'article : les descriptions de la structure du projet n'aident presque pas l'agent à s'orienter. Les sections sur les dossiers, l'architecture et la stack semblent utiles pour un humain, mais l'agent retrouve souvent tout seul l'information avec grep, glob et la lecture de fichiers. Si elle figure déjà dans pyproject.toml, package.json, la configuration du linter ou la structure même du dépôt, une longue explication ne fait que dupliquer ce que le modèle peut découvrir rapidement par lui-même.

Si l'agent peut l'apprendre lui-même à partir du code, mieux vaut le

supprimer des instructions.

Les chercheurs ont aussi remarqué que les modèles dotés de fichiers de contexte effectuent plus d'actions que la tâche ne l'exige. Ils relisent plus souvent les instructions, relancent les tests une fois de trop et appellent davantage les outils mentionnés dans le fichier. L'article relève à part une hausse des reasoning tokens chez les modèles GPT. En d'autres termes, l'instruction n'ajoute pas seulement des connaissances : elle modifie le comportement de l'agent, qui se met à suivre des règles même là où elles n'aident pas à résoudre la tâche en cours.

Ce qu'il vaut la peine de garder

L'étude ne conclut pas à l'abandon complet de CLAUDE.md ou d'AGENTS.md. Sa conclusion est plutôt que ces fichiers doivent être courts et ne contenir que ce que l'agent ne peut pas déduire de façon fiable du code ou des configurations. Moins il y a de texte décoratif, moins le modèle risque de s'enfermer dans des rituels inutiles au lieu de traiter la demande concrète.

• Une commande de lancement des tests non standard
• Le gestionnaire de paquets, s'il n'est pas évident
• Les scripts personnalisés, les outils et les particularités de déploiement
• Les règles de nommage, si on ne peut pas les déduire rapidement du code
• Un renvoi vers .env.example ou un autre fichier d'entrée critique

Une autre étude vient nuancer le tableau : Codex avec AGENTS.md y montrait une accélération et une moindre consommation de tokens. Mais l'échantillon y était bien plus petit et l'exactitude des résultats n'était évaluée que de façon limitée. La conclusion générale reste donc prudente : un contexte court et pratique aide parfois, alors qu'un long fichier avec un tour d'horizon de l'architecture, de la stack et des règles générales se transforme facilement en lest coûteux. L'ETH Zurich n'aborde en outre presque pas la maintenabilité du code ni le respect du style du projet : le débat sur l'utilité de ces fichiers n'est donc pas clos.

Ce que cela signifie

La conclusion pratique est simple : traiter CLAUDE.md comme une liste des erreurs corrigées de l'agent, et non comme l'encyclopédie du projet. Si une instruction n'aide pas à éviter un échec précis, ne décrit pas une commande non standard et n'apporte aucun contexte unique, mieux vaut la retirer. Pour les équipes qui utilisent beaucoup d'agents de code, c'est une raison directe de raccourcir les fichiers de contexte, de réduire la consommation de tokens et de vérifier sur leurs propres tâches quelles lignes améliorent réellement le résultat et lesquelles ne produisent qu'un bruit coûteux.