READMEs de Agentes: Un Estudio Empírico de Archivos de Contexto para la Programación Agéntica
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
November 17, 2025
Autores: 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
Resumen
Las herramientas de codificación con agencia reciben objetivos escritos en lenguaje natural como entrada, los desglosan en tareas específicas y escriben o ejecutan el código real con mínima intervención humana. Central a este proceso son los archivos de contexto del agente ("READMEs para agentes") que proporcionan instrucciones persistentes a nivel de proyecto. En este artículo, realizamos el primer estudio empírico a gran escala de 2.303 archivos de contexto de agentes de 1.925 repositorios para caracterizar su estructura, mantenimiento y contenido. Encontramos que estos archivos no son documentación estática, sino artefactos complejos y difíciles de leer que evolucionan como código de configuración, mantenidos mediante adiciones frecuentes y pequeñas. Nuestro análisis de contenido de 16 tipos de instrucciones muestra que los desarrolladores priorizan el contexto funcional, como comandos de compilación y ejecución (62,3%), detalles de implementación (69,9%) y arquitectura (67,7%). También identificamos una brecha significativa: los requisitos no funcionales como seguridad (14,5%) y rendimiento (14,5%) rara vez se especifican. Estos hallazgos indican que, si bien los desarrolladores utilizan los archivos de contexto para hacer que los agentes sean funcionales, proporcionan pocas barreras de protección para garantizar que el código escrito por el agente sea seguro o eficiente, destacando la necesidad de mejores herramientas y prácticas.
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.