README degli Agenti: Uno Studio Empirico sui File di Contesto per la Programmazione Agente
Agent READMEs: An Empirical Study of Context Files for Agentic Coding
November 17, 2025
Autori: 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
Abstract
Gli strumenti di codifica agentica ricevono obiettivi scritti in linguaggio naturale come input, li scompongono in compiti specifici e scrivono o eseguono il codice effettivo con un intervento umano minimo. Centrali in questo processo sono i file di contesto dell'agente ("README per agenti") che forniscono istruzioni persistenti a livello di progetto. In questo articolo, conduciamo il primo studio empirico su larga scala di 2.303 file di contesto provenienti da 1.925 repository per caratterizzarne la struttura, la manutenzione e il contenuto. Scopriamo che questi file non sono documentazione statica, ma artefatti complessi e di difficile lettura che si evolvono come codice di configurazione, mantenuti attraverso aggiunte frequenti e piccole. La nostra analisi del contenuto su 16 tipi di istruzioni mostra che gli sviluppatori danno priorità al contesto funzionale, come i comandi di build e run (62,3%), i dettagli implementativi (69,9%) e l'architettura (67,7%). Identifichiamo anche un divario significativo: i requisiti non funzionali come la sicurezza (14,5%) e le prestazioni (14,5%) sono raramente specificati. Questi risultati indicano che, sebbene gli sviluppatori utilizzino i file di contesto per rendere gli agenti funzionali, forniscono poche protezioni per garantire che il codice scritto dagli agenti sia sicuro o performante, evidenziando la necessità di strumenti e pratiche migliorati.
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.