Агентские 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 для агентов»), которые содержат постоянные инструкции на уровне проекта. В данной статье мы проводим первое крупномасштабное эмпирическое исследование 2303 файлов контекста агента из 1925 репозиториев, чтобы охарактеризовать их структуру, поддержку и содержание. Мы обнаружили, что эти файлы представляют собой не статичную документацию, а сложные, трудные для восприятия артефакты, которые эволюционируют подобно конфигурационному коду и поддерживаются за счет частых небольших дополнений. Наш контент-анализ 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.