READMEs d'agent : une étude empirique des fichiers de contexte pour le codage agentiel
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
November 17, 2025
papers.authors: Worawalan Chatlatanagulchai, Hao Li, Yutaro Kashiwa, Brittany Reid, Kundjanasith Thonglek, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasemsak, Bram Adams, Ahmed E. Hassan, Hajimu Iida
cs.AI
papers.abstract
Les outils de programmation agentique reçoivent des objectifs formulés en langage naturel, les décomposent en tâches spécifiques, et écrivent ou exécutent le code réel avec une intervention humaine minimale. Au cœur de ce processus se trouvent les fichiers de contexte d'agent (« README pour agents »), qui fournissent des instructions persistantes au niveau du projet. Dans cet article, nous menons la première étude empirique à grande échelle sur 2 303 fichiers de contexte d'agent provenant de 1 925 dépôts pour caractériser leur structure, leur maintenance et leur contenu. Nous constatons que ces fichiers ne sont pas une documentation statique, mais des artefacts complexes et difficiles à lire qui évoluent comme du code de configuration, maintenus par de fréquents ajouts mineurs. Notre analyse de contenu sur 16 types d'instructions montre que les développeurs privilégient le contexte fonctionnel, tel que les commandes de compilation et d'exécution (62,3 %), les détails d'implémentation (69,9 %) et l'architecture (67,7 %). Nous identifions également un écart significatif : les exigences non fonctionnelles comme la sécurité (14,5 %) et les performances (14,5 %) sont rarement spécifiées. Ces résultats indiquent que si les développeurs utilisent les fichiers de contexte pour rendre les agents fonctionnels, ils fournissent peu de garde-fous pour garantir que le code généré par l'agent est sécurisé ou performant, soulignant le besoin d'améliorer les outils et les pratiques.
English
Agentic coding tools receive goals written in natural language as input, break them down into specific tasks, and write or execute the actual code with minimal human intervention. Central to this process are agent context files ("READMEs for agents") that provide persistent, project-level instructions. In this paper, we conduct the first large-scale empirical study of 2,303 agent context files from 1,925 repositories to characterize their structure, maintenance, and content. We find that these files are not static documentation but complex, difficult-to-read artifacts that evolve like configuration code, maintained through frequent, small additions. Our content analysis of 16 instruction types shows that developers prioritize functional context, such as build and run commands (62.3%), implementation details (69.9%), and architecture (67.7%). We also identify a significant gap: non-functional requirements like security (14.5%) and performance (14.5%) are rarely specified. These findings indicate that while developers use context files to make agents functional, they provide few guardrails to ensure that agent-written code is secure or performant, highlighting the need for improved tooling and practices.