Agent READMEs: An Empirical Study of Context Files for Agentic Coding

TL;DR

This study analyzes 2,303 agent context files from repositories to understand their structure, content, and maintenance, revealing they are complex, evolving artifacts focused on functional instructions with minimal emphasis on non-functional requirements.

Contribution

It provides the first large-scale empirical characterization of agent context files, highlighting their complexity, maintenance patterns, and content focus, and identifies gaps in non-functional requirement coverage.

Findings

Context files are complex, evolving artifacts similar to configuration code.

Functional instructions like build, run, and architecture dominate content.

Non-functional requirements such as security and performance are rarely included.

Abstract

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.