J'étais trop flemmard pour écrire un CLAUDE.md — et c'était la bonne décision

Chaque fois qu’un article sur CLAUDE.md (ou AGENTS.md) défilait dans mon fil, je me disais « je m’en occuperai plus tard » et je passais à autre chose. Voir les autres construire des configurations AGENTS.md ultra-élaborées me donnait un peu d’anxiété. Étais-je en train de prendre du retard ?

Puis des données de benchmark sont tombées, et cette anxiété s’est évaporée. Il s’avère que ma flemme était une décision d’ingénierie parfaitement rationnelle.

Les fichiers de contexte générés par LLM empirent les choses

« Donner plus de contexte à l’agent, ça aide forcément, non ? » C’est ce que je pensais aussi.

Quand les chercheurs ont testé un contexte auto-généré par LLM sur SWE-bench Lite, le taux de succès a chuté de 0,5 %. Sur AgentBench, il a encore reculé de 2 %. Même les fichiers soigneusement rédigés à la main n’ont produit qu’une amélioration de 4 %. J’appellerais ça du « surapprentissage de contexte ».

• Baisse de 0,5 % du taux de succès avec un contexte généré par LLM sur SWE-bench Lite
• Recul supplémentaire de 2 % sur AgentBench
• Augmentation de 20 à 23 % des coûts d’inférence
• Effet positif (2,7 %) observé uniquement dans les dépôts sans aucune documentation

L’article « Evaluating AGENTS.md » de Gloaguen et al. l’a confirmé : les fichiers de contexte ont tendance à faire baisser les taux de réussite des tâches par rapport à l’absence totale de contexte de dépôt.

Les agents suivent les instructions trop bien — et c’est là le problème

Le problème n’est pas que les agents ignorent vos instructions. C’est tout le contraire.

Écrivez une seule ligne dans votre fichier de contexte pour dire à l’agent d’utiliser uv, et il va installer et exécuter uv même dans des situations où c’est complètement inutile, en ajoutant des étapes superflues à chaque fois.

Avec GPT-5.2, les tokens d’inférence ont augmenté de 14 à 22 % en présence de fichiers de contexte. L’agent était tellement occupé à suivre les instructions qu’il perdait de vue l’objectif réel : résoudre le problème.

• Les exécutions inutiles de pytest ont augmenté
• L’utilisation des outils grep et read a explosé bien au-delà du nécessaire

« Ne fais pas X » fait penser l’agent à X encore plus

J’avais évoqué dans un précédent article comment le contenu de SKILL.md est lu à des moments précis, et AGENTS.md souffre du même travers.

Il se loge dans la couche « message développeur », entre le prompt système et le prompt utilisateur. Cette position contraint fortement le raisonnement de l’agent.

Écrivez « ne touche pas à ce fichier » et l’agent va penser à ce fichier une fois de plus. Les chercheurs ont appelé ça l’« effet éléphant rose ». Dites à quelqu’un de ne pas penser à un éléphant rose, et c’est exactement ce qui lui vient à l’esprit.

• Ordre de priorité : instructions du fournisseur → prompt système → AGENTS.md → prompt utilisateur
• Les fichiers maintenus manuellement ne peuvent pas suivre les évolutions du code, et les informations deviennent vite obsolètes

Si vous devez en écrire un, faites court

Si votre dépôt n’a absolument aucune documentation, les fichiers de contexte peuvent aider — les données montrent un effet positif de 2,7 % dans ces cas-là. Mais si vous en écrivez un, réduisez le volume au strict minimum.

Une ligne pour indiquer l’outil de build propre au dépôt. Une ligne pour corriger un pattern que l’agent reproduit systématiquement à tort.

Ajoutez une astuce du genre « si tu trouves quelque chose de structurellement bizarre, signale-le immédiatement » et l’agent devient un outil qui remonte les failles de votre codebase. Au-delà de ça, rendre la structure de votre code plus intuitive est bien plus efficace que d’écrire des instructions à son sujet.

• Renforcer les tests unitaires et les vérifications de types est plus payant que les fichiers de contexte
• Si l’emplacement des fichiers prête à confusion, déplacez les fichiers plutôt que d’écrire un mode d’emploi

Savoir écrire de bons fichiers de contexte n’est pas forcément un signe de compétence. Comprendre la structure des fichiers de contexte et concevoir des méta-systèmes autour d’eux — ça, c’est de la compétence. Et parfois, « être flemmard » est la meilleure décision d’ingénierie que vous puissiez prendre.