Agent README's: Een Empirische Studie naar Contextbestanden voor Agent-gebaseerd Programmeren

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

November 17, 2025

Auteurs: 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

Samenvatting

Agentische codeertools ontvangen doelen geschreven in natuurlijke taal als invoer, splitsen deze op in specifieke taken, en schrijven of executeren de daadwerkelijke code met minimale menselijke tussenkomst. Centraal in dit proces staan agentcontextbestanden ("READMEs voor agents") die persistente, projectbrede instructies bevatten. In dit artikel voeren we de eerste grootschalige empirische studie uit van 2.303 agentcontextbestanden uit 1.925 repositories om hun structuur, onderhoud en inhoud te karakteriseren. Wij constateren dat deze bestanden geen statische documentatie zijn, maar complexe, moeilijk leesbare artefacten die evolueren zoals configuratiecode, onderhouden door frequente, kleine toevoegingen. Onze inhoudsanalyse van 16 instructietypen toont aan dat ontwikkelaars prioriteit geven aan functionele context, zoals build- en run-commando's (62,3%), implementatiedetails (69,9%) en architectuur (67,7%). We identificeren ook een significante kloof: niet-functionele vereisten zoals beveiliging (14,5%) en prestaties (14,5%) worden zelden gespecificeerd. Deze bevindingen geven aan dat ontwikkelaars contextbestanden weliswaar gebruiken om agents functioneel te maken, maar dat ze weinig veiligheidsmaatregelen bieden om te waarborgen dat door agents geschreven code veilig of performant is, wat de behoefte aan verbeterde tooling en praktijken benadrukt.

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.