Agent READMEs: An Empirical Study of Context Files for Agentic Coding
ACM Transactions on Software Engineering and Methodology · 30.11.2026 · 35 (11) · 1-38
DOI: 10.1145/3840295 ↗Kurz gefasst
Fachartikel in der Zeitschrift ACM Transactions on Software Engineering and Methodology, online erschienen am 04.11.2026. Verfasst von Worawalan Chatlatanagulchai und 10 weiteren Autor:innen. Die Arbeit wurde bisher 6-mal zitiert (Crossref) und nennt 86 Literaturangaben. Der Volltext ist frei zugänglich (Open Access, CC BY 4.0). Gefördert von: JSPS KAKENHI, ASPIRE, JST CREST.
Abstract (Originalsprache)
Agentic coding tools receive goals written in natural language, break them down into specific tasks, and write or execute code with minimal human intervention. Central to this process are agent context files (e.g., AGENTS.md and CLAUDE.md) that provide persistent, project-level instructions. In this article, 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 through frequent, small additions. Our content analysis of 16 instruction types shows that developers prioritize functional context, such as test procedures (75.9%), implementation details (70.8%), and architecture (68.1%). We also identify a significant gap: non-functional requirements such as security (14.8%) 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 tools and practices.
Förderung
- JSPS KAKENHI
- ASPIRE
- JST CREST
- JST FOREST
- Natural Sciences and Engineering Research Council of Canada
Zitieren
APA
Chatlatanagulchai, W., Li, H., Kashiwa, Y., Reid, B., Thonglek, K., Leelaprute, P., Rungsawang, A., Manaskasemsak, B., Adams, B., Hassan, A. E., & Iida, H. (2026). Agent READMEs: An Empirical Study of Context Files for Agentic Coding. ACM Transactions on Software Engineering and Methodology, 35(11), 1-38. https://doi.org/10.1145/3840295
Vancouver
Chatlatanagulchai W, Li H, Kashiwa Y, Reid B, Thonglek K, Leelaprute P, et al. Agent READMEs: An Empirical Study of Context Files for Agentic Coding. ACM Transactions on Software Engineering and Methodology. 2026;35(11):1-38. doi:10.1145/3840295
BibTeX
@article{Chatlatanagulchai2026,
author = {Chatlatanagulchai, Worawalan and Li, Hao and Kashiwa, Yutaro and Reid, Brittany and Thonglek, Kundjanasith and Leelaprute, Pattara and Rungsawang, Arnon and Manaskasemsak, Bundit and Adams, Bram and Hassan, Ahmed E. and Iida, Hajimu},
title = {Agent READMEs: An Empirical Study of Context Files for Agentic Coding},
journal = {ACM Transactions on Software Engineering and Methodology},
year = {2026},
volume = {35},
number = {11},
pages = {1--38},
doi = {10.1145/3840295}
}
EUVIMED