This paper studies the files that give Agentic Coding tools their persistent, project-level instructions: agent context files, with AGENTS.md and CLAUDE.md as its named examples. It describes itself as the first large-scale empirical study of them, covering 2,303 context files from 1,925 repositories, and sets out to characterize three things about them: their structure, how they are maintained, and what they contain.
Its content analysis classifies the instructions in these files into 16 instruction types. The headline finding is an imbalance between what developers write down and what they leave out: functional context such as how to run tests, implementation details and architecture appears in most files, while non-functional requirements such as security and performance appear in few. The authors read this as developers using context files to make agents functional while providing few guardrails to ensure that agent-written code is secure or performant, and conclude that better tools and practices are needed.
The paper was first submitted to arXiv on 17 November 2025 (arXiv:2511.12884) and revised on 9 August 2026; it is listed under Software Engineering (cs.SE).
Key Points
- The study covers 2,303 agent context files from 1,925 repositories, which the authors present as the first large-scale empirical study of such files.
- The paper finds that context files are not static documentation but complex, difficult-to-read artifacts.
- It reports that these files evolve like configuration code, through frequent, small additions.
- The content analysis distinguishes 16 instruction types.
- The most common kinds of content are functional: test procedures (75.9% of files), implementation details (70.8%) and architecture (68.1%).
- Non-functional requirements are rarely specified: security appears in 14.8% of files and performance in 14.5%.
- The authors conclude that developers use context files to make agents functional while providing few guardrails to keep agent-written code secure or performant, and call for improved tools and practices.