エージェントREADME：エージェント駆動型コーディングにおけるコンテキストファイルの実証研究

要旨

エージェンシック・コーディングツールは、自然言語で記述された目標を入力として受け取り、それを特定のタスクに分解し、最小限の人的介入で実際のコードを記述または実行する。このプロセスの中心となるのは、プロジェクトレベルの永続的な指示を提供するエージェントコンテキストファイル（「エージェントのためのREADME」）である。本論文では、1,925のリポジトリから収集した2,303のエージェントコンテキストファイルに対して初の大規模実証研究を実施し、その構造、保守、内容を特徴づける。これらのファイルが静的なドキュメントではなく、頻繁で小規模な追加を通じて維持される、設定コードのように進化する、複雑で読みにくい成果物であることを明らかにする。16種類の指示タイプに対する内容分析により、開発者がビルドおよび実行コマンド（62.3%）、実装詳細（69.9%）、アーキテクチャ（67.7%）などの機能的コンテキストを優先していることが示された。さらに、セキュリティ（14.5%）やパフォーマンス（14.5%）といった非機能要件がほとんど規定されていないという重大なギャップを特定する。これらの知見は、開発者がコンテキストファイルを用いてエージェントを機能させる一方で、エージェントが記述するコードの安全性や性能を確保するためのガードレールをほとんど提供しておらず、ツールやプラクティスの改善必要性を浮き彫りにするものである。

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.

エージェントREADME：エージェント駆動型コーディングにおけるコンテキストファイルの実証研究

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

要旨

Support