Agent READMEs: An Empirical Study of Context Files for Agentic Coding
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.
691bea4f6bfd5965c0fd3837
Worawalan Chatlatanagulchai
691bea4f6bfd5965c0fd3838
Hao Li
claimed_verified
2025-11-18T14:07:56.453Z
62b4f3b7464e664268bf4e85
https://cdn-avatars.huggingface.co/v1/production/uploads/62b4f3b7464e664268bf4e85/atFIscmB37aur0a1zuQ2o.jpeg
Leo
hao-li
user
hao-li
691bea4f6bfd5965c0fd3839
Yutaro Kashiwa
691bea4f6bfd5965c0fd383a
Brittany Reid
691bea4f6bfd5965c0fd383b
Kundjanasith Thonglek
691bea4f6bfd5965c0fd383c
Pattara Leelaprute
691bea4f6bfd5965c0fd383d
Arnon Rungsawang
691bea4f6bfd5965c0fd383e
Bundit Manaskasemsak
691bea4f6bfd5965c0fd383f
Bram Adams
691bea4f6bfd5965c0fd3840
Ahmed E. Hassan
691bea4f6bfd5965c0fd3841
Hajimu Iida
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
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.