Как писать README-файлы для ИИ-агентов

Сегодня, когда мы пишем код с помощью ИИ, мы формулируем задачу на естественном языке, и агент в IDE сам планирует шаги, пишет изменения, запускает тесты и пытается довести дело до результата. Такой подход называют агентное программирование. Но у него есть слабое место: агенту нужно быстро понять, как устроен проект, чем в нём принято пользоваться, как запускать сборку и тесты, какие архитектурные решения нельзя ломать и какие ограничения важны.

Именно поэтому в репозиториях стали появляться специальные файлы контекста — по сути README не для людей, а для агента. Обычно это Markdown-файлы вроде CLAUDE.md, AGENTS.md или copilot-instructions.md. Они подгружаются инструментом в начале сессии и работают как долговременная память: не приходится каждый раз объяснять одно и то же.

Авторы статьи «Agent READMEs: An Empirical Study of Context Files for Agentic Coding» решили посмотреть на явление не по отдельным примерам, а «с высоты птичьего полёта»: как эти файлы реально выглядят в тысячах репозиториев, как часто меняются и что в них обычно пишут.

Какую проблему решают исследователи

Проблема проста: вокруг контекстных файлов много практических советов о том, как правильно их писать, но мало фактов из разряда "а что действительно работает". Документация инструментов раскрывает общие вещи — опишите архитектуру, пайплайн и стандарты — но не объясняет, что команды пишут на самом деле и какие темы системно забывают. А если эти файлы действительно управляют поведением агента, то их качество напрямую влияет и на эффективность, и на безопасность результата.

Здесь и появляется цель исследования: собрать большую выборку таких файлов и описать их как инженерный артефакт — по размеру, читаемости, структуре, истории изменений и содержанию инструкций.

Как собрали данные и что с ними делали

Авторы отобрали oткрытые репозитории на GitHub (минимум 5 звёзд) и автоматически искали в корне файлы с официальными именами для трёх инструментов: Claude Code, OpenAI Codex и GitHub Copilot. В итоге набралось 2 303 файла из 1 925 репозиториев — на сегодня это действительно крупная эмпирическая выборка для такого нового типа документации.

Дальше началась «инвентаризация» по нескольким направлениям. Во‑первых, авторы измерили длину (по количеству слов), читабельность и то, как люди структурируют текст через Markdown-заголовки. Во‑вторых, подняли историю коммитов и посмотрели, как часто файлы правят и какими порциями. И, наконец, сделали контент-анализ: выделили 16 типов инструкций (например, Build and Run, Architecture, Testing, Security, Performance и другие) и отметили, какие темы встречаются чаще.

В отдельном эксперименте они проверили, можно ли автоматически размечать такие файлы по темам с помощью LLM (в работе использован GPT-5), потому что вручную это плохо масштабируется.

Файлы оказались длинными, сложными и… живыми

Первое впечатление по цифрам: эти «README для агента» вовсе не короткие подсказки. В медиане файлы для Claude Code и GitHub Copilot заметно длиннее, чем для Codex.

Но ещё интереснее читабельность: тексты часто написаны тяжело. У CLAUDE.md медианная оценка FRE настолько низкая, что попадает в категорию very difficult — примерно уровень академических или юридических формулировок. То есть они понятны авторам и «своим», но плохо читаются «со стороны», а значит со временем рискуют превратиться в трудноуправляемую кашу.

При этом со структурой всё более-менее: обычно один главный заголовок и дальше разбиение на H2/H3. Глубокая вложенность почти не встречается.

Главный неожиданный вывод — это не статичная документация. Файлы активно редактируются: значительная доля менялась в нескольких коммитах, причём изменения часто идут «всплесками», с небольшими добавлениями, а удалений существенно меньше.

По ощущениям это похоже на конфигурационный код: добавили новое правило, дописали команду запуска, уточнили стиль — и так постепенно наращивают файл, редко вычищая старое. Авторы называют это потенциальным источником «контекстного долга»: когда инструкции для агента накапливаются быстрее, чем команда успевает поддерживать их в ясном и непротиворечивом виде.

О чём там пишут — и о чём подозрительно молчат

Если посмотреть на содержание, то лидируют «практичные» темы: как собрать и запустить проект, как устроена архитектура, какие детали реализации важны, как прогонять тесты. Это логично: агенту нужно быстро завестись и попасть в колею конкретного репозитория.

Но нефункциональные требования встречаются редко. Безопасность и производительность присутствуют примерно в 14,5% файлов, UI/UX — ещё реже. Получается, что агентам часто объясняют «как сделать, чтобы работало», но значительно реже — «как сделать, чтобы было безопасно, быстро и не ломало пользовательский опыт». А если ограничений нет в явном виде, агент в лучшем случае будет следовать общим знаниям LLM, а в худшем — пойдёт по пути наименьшего сопротивления.

Интересная деталь из разметки: отдельной категорией всплыл Debugging — она встречается примерно в четверти файлов. Люди явно пытаются заранее подсказать агенту, где смотреть логи и какие флаги включать, чтобы не тратить время на слепые попытки.

Можно ли это разбирать автоматически

Ручная разметка хороша, но для индустрии нужен масштаб. Поэтому авторы проверили автоматическую классификацию по темам с помощью LLM. На подмножестве файлов модель показала micro-average F1 около 0.79. Лучше всего распознаются конкретные инженерные разделы вроде Architecture, Testing или Build and Run. Хуже — более расплывчатые вещи наподобие Maintainability или Project Management, где границы категории размыты и примеров мало.

Это важный практический намёк: в будущем вполне реалистичны линтеры и CI-проверки для контекстных файлов для агентов — чтобы подсвечивать пустые зоны (например, нет Security), конфликты правил или устаревшие команды запуска.

Что это значит для нас

Исследование оставляет ощущение, что мы наблюдаем рождение нового слоя инженерной культуры. Контекстные файлы для агентов быстро становятся инструментом, с помощью которых проект формализует свою «модель мира» для агента: как устроена система и как в ней безопасно действовать. И пока индустрия пишет туда в основном операционные подсказки (сборка, запуск, структура), но ещё не привыкла фиксировать ограничения качества — особенно по безопасности и производительности.

Отсюда простой вывод: если команда уже пишет код с помощью агентов, стоит относиться к этим файлам как к коду. Их нужно ревьюить, обновлять при изменениях инфраструктуры и явно прописывать нефункциональные требования, иначе автономность агента будет расти быстрее, чем управляемость результата.

📜 Полная статья

💾 Код

***

Если вам интересна тема ИИ, подписывайтесь на мой Telegram-канал — там я регулярно делюсь инсайтами по внедрению ИИ в бизнес, запуску ИИ-стартапов и объясняю, как работают все эти ИИ-чудеса.