Agent READMEs: Eine empirische Untersuchung von Kontextdateien für agentenbasiertes Programmieren
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
November 17, 2025
papers.authors: 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
papers.abstract
Agentische Code-Tools erhalten Ziele in natürlicher Sprache als Eingabe, zerlegen sie in konkrete Aufgaben und schreiben oder führen den eigentlichen Code mit minimalem menschlichem Eingriff aus. Zentrale Bedeutung haben dabei Agenten-Kontextdateien ("READMEs für Agenten"), die persistente, projektbezogene Anweisungen bereitstellen. In diesem Artikel führen wir die erste großangelegte empirische Studie von 2.303 Agenten-Kontextdateien aus 1.925 Repositories durch, um deren Struktur, Wartung und Inhalte zu charakterisieren. Wir zeigen, dass diese Dateien keine statische Dokumentation sind, sondern komplexe, schwer lesbare Artefakte, die sich wie Konfigurationscode entwickeln und durch häufige, kleine Ergänzungen gepflegt werden. Unsere Inhaltsanalyse von 16 Anweisungstypen zeigt, dass Entwickler funktionalen Kontext priorisieren, wie Build- und Run-Befehle (62,3%), Implementierungsdetails (69,9%) und Architektur (67,7%). Wir identifizieren auch eine signifikante Lücke: Nicht-funktionale Anforderungen wie Sicherheit (14,5%) und Performance (14,5%) werden selten spezifiziert. Diese Ergebnisse deuten darauf hin, dass Entwickler Kontextdateien zwar nutzen, um Agenten funktionsfähig zu machen, aber kaum Vorkehrungen treffen, um sicherzustellen, dass agentengeschriebener Code sicher oder performant ist. Dies unterstreicht den Bedarf an verbesserten Werkzeugen und Praktiken.
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.