Anthropic et ETH Zurich : un CLAUDE.md trop long dégrade les performances de l'agent et augmente les coûts

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

Ce que la recherche a montré

Les auteurs de l'article Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? ont pris 138 dépôts réels, collecté 5694 pull requests et exécuté des tâches sur quatre modèles : Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini et Qwen3-30B. Ils ont comparé des scénarios sans fichiers spéciaux, avec des instructions générées par LLM et avec des AGENTS.md maintenus par des humains. C'est un point important : la recherche n'a pas examiné des démonstrations abstraites, mais des tâches réelles issues de bases de code en vivo.

La conclusion principale pour les fichiers créés automatiquement s'est avérée décevante. Le taux de réussite a chuté en moyenne de 3 %, et le coût d'inférence a augmenté de plus de 20 %. Les fichiers maintenus par des humains ont mieux performé : ils ont augmenté le succès d'environ 4 %, mais le coût a aussi augmenté de près de 19 %. En d'autres termes, un fichier de contexte n'a pas été un accélérateur gratuit. Même quand il aide, le gain de qualité reste modeste par rapport au surcoût constant en tokens et aux étapes supplémentaires de l'agent.

Pourquoi les fichiers longs nuisent

L'observation la plus contre-intuitive de l'article : les descriptions de la structure du projet aident à peine l'agent à naviguer. Les sections sur les dossiers, l'architecture et la pile technologique semblent utiles pour les humains, mais les agents trouvent souvent tout eux-mêmes via grep, glob et la lecture de fichiers. Si l'information est déjà dans pyproject.toml, package.json, la configuration du linter ou dans la structure du dépôt elle-même, une longue explication ne fait que dupliquer ce que le modèle peut découvrir rapidement par lui-même.

Si l'agent peut apprendre cela du code lui-même, il est préférable de

le supprimer de l'instruction.

Les chercheurs ont également remarqué que les modèles avec des fichiers de contexte effectuent plus d'actions que nécessaire pour la tâche spécifique. Ils relisent plus souvent les instructions, exécutent inutilement les tests et invoquent plus activement les outils mentionnés dans le fichier. L'article note séparément une augmentation des tokens de raisonnement pour les modèles GPT. En d'autres termes, l'instruction n'ajoute pas simplement des connaissances, elle change le comportement de l'agent : il commence à suivre les règles même là où elles ne l'aident pas à résoudre la tâche actuelle.

Ce qu'il faut conserver

Un rejet complet de CLAUDE.md ou AGENTS.md ne découle pas de cette recherche. Plutôt, la conclusion est différente : de tels fichiers doivent être brefs et ne contenir que ce que l'agent ne peut pas déduire de manière fiable du code ou des configurations par lui-même. Moins il y a de texte décoratif, plus le risque est faible que le modèle se concentre sur des rituels inutiles au lieu d'exécuter la demande spécifique.

• Commandes non standard pour exécuter les tests
• Gestionnaire de paquets, s'il n'est pas évident
• Scripts personnalisés, outils et spécificités de déploiement
• Conventions de nommage, si elles ne peuvent pas être rapidement déduites du code
• Lien vers .env.example ou un autre fichier d'entrée critique

Une autre étude se superpose à ce tableau, où Codex avec AGENTS.md a montré une accélération et une consommation de tokens inférieure. Mais là, l'échantillon était beaucoup plus petit, et l'exactitude des résultats a été évaluée de manière limitée. Donc la conclusion générale pour l'instant est prudente : un contexte court et pratique aide parfois, tandis qu'un long fichier examinant l'architecture, la pile technologique et les règles générales devient facilement du lest coûteux. ETH Zurich n'aborde également à peine la maintenabilité du code et le respect du style du projet, donc le différend sur l'utilité de tels fichiers n'est pas encore réglé.

Ce que cela signifie

La conclusion pratique est simple : traitez CLAUDE.md comme une liste de correctifs pour les erreurs de l'agent, pas comme une encyclopédie du projet. Si l'instruction ne vous aide pas à éviter une défaillance spécifique, ne décrit pas une commande non standard et n'ajoute pas de contexte unique, il est préférable de la supprimer. Pour les équipes qui utilisent activement les agents de codage, c'est une motivation directe pour réduire les fichiers de contexte, diminuer les dépenses en tokens et vérifier sur vos propres tâches quelles lignes améliorent réellement les résultats et lesquelles créent seulement du bruit coûteux.