에이전트 README: 에이전트 기반 코딩을 위한 컨텍스트 파일에 관한 실증적 연구

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

November 17, 2025

저자: 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

초록

에이전트형 코딩 도구는 자연어로 작성된 목표를 입력받아 구체적인 작업으로 분해하고, 최소한의 인간 개입으로 실제 코드를 작성하거나 실행합니다. 이 과정의 핵심은 프로젝트 수준의 지속적인 지침을 제공하는 에이전트 컨텍스트 파일("에이전트를 위한 README")입니다. 본 논문에서는 1,925개 저장소의 2,303개 에이전트 컨텍스트 파일을 대상으로 첫 대규모 실증 연구를 수행하여 그 구조, 유지 관리, 내용의 특성을 분석합니다. 우리는 이러한 파일이 정적 문서가 아니라 구성 코드처럼 진화하며, 빈번하고 소규모의 추가를 통해 유지되는 복잡하고 가독성이 낮은 결과물임을 발견했습니다. 16가지 지침 유형에 대한 내용 분석 결과, 개발자들은 빌드 및 실행 명령(62.3%), 구현 세부 사항(69.9%), 아키텍처(67.7%) 등의 기능적 컨텍스트를 우선적으로 명시하는 것으로 나타났습니다. 또한 보안(14.5%) 및 성능(14.5%)과 같은 비기능적 요구사항이 거의 명시되지 않는 중요한 격차를 확인했습니다. 이러한 결과는 개발자들이 컨텍스트 파일을 사용해 에이전트를 기능적으로 만드는 반면, 에이전트가 작성한 코드의 보안이나 성능을 보장하기 위한 안전장치(Safety Guardrail)는 거의 제공하지 않음을 시사하며, 개선된 도구와 관행의 필요성을 강조합니다.

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.