Когда контекст мешает: почему AGENTS.md делает работу агентов хуже

Идея кажется очевидной: если агенту для программирования дать специальный файл с правилами репозитория — как собирать проект, как гонять тесты, какие есть договорённости по стилю и структуре — он будет работать увереннее и реже ошибаться. Такие файлы часто называют context files: AGENTS.md, CLAUDE.md и похожие. Их уже десятки тысяч в open-source, а многие фреймворки для агентов даже предлагают команду “init”, которая сама сгенерирует нужный документ.

Проблема в том, что эту практику почти никто строго не проверял. Советы «добавьте AGENTS.md, и агент станет умнее» звучат убедительно, но до конца непонятно: помогает ли такой контекст именно в сложных задачах уровня репозитория, где агент должен разобраться в чужом коде, исправить баг или добавить фичу, не сломав тесты? Авторы работы Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? берутся ответить на этот вопрос экспериментально — и результаты получаются неожиданными.

Как устроена проверка и почему она ближе к реальности

Авторы тестируют context files в двух мирах. Первый — привычные популярные репозитории из SWE-bench Lite, где таких файлов обычно нет, поэтому их приходится генерировать с помощью LLM по рекомендациям конкретного агента. Второй — более интересный: новый бенчмарк AGENTbench, собранный из менее “звёздных”, но живых Python-репозиториев, где разработчики сами добавили AGENTS.md/CLAUDE.md и реально ими пользуются.

AGENTbench сделан довольно приземлённо: берутся реальные GitHub issues и соответствующие pull request, из которых восстанавливают задачу и проверку через тесты. В итоге получается 138 задач из 12 репозиториев: где-то это багфиксы, где-то добавление функциональности. Важная деталь: поскольку во многих небольших проектах тестов в PR может не быть, авторы генерируют регрессионные тесты так, чтобы они падали на версии “до” и проходили на “после”, а затем вручную чистят слишком жёсткие случаи.

Помогает ли AGENTS.md решать задачи лучше

Главный итог звучит почти парадоксально для индустриальных рекомендаций: автоматически сгенерированные context files чаще мешают, чем помогают. В среднем по настройкам такие файлы дают небольшое падение доли успешно решённых задач (примерно на несколько процентов) — причём это устойчиво для разных агентов и моделей.

Файлы, написанные людьми (то есть реально закоммиченные разработчиками в репозитории), выглядят лучше: на AGENTbench они дают небольшой плюс относительно режима без контекста (около +4% в среднем). Но это именно небольшой плюс, не прорыв. И что важно — даже человеческие файлы почти всегда увеличивают “цену” попытки.

Цена подсказок: агент старается больше, но выигрывает не всегда

Когда в репозитории появляется context file, агенты начинают вести себя иначе. Они больше исследуют кодовую базу, чаще запускают тесты, активнее используют инструменты и чаще следуют repo-specific инструкциям (например, переходят на uv, если это написано в файле). На уровне поведения кажется, что всё хорошо: агент дисциплинированнее, осторожнее, более “инженерный”.

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

В числах это выглядит жёстко: стоимость инференса растёт более чем на 20% почти везде, а количество шагов стабильно увеличивается. То есть context file почти гарантированно делает попытку дороже, даже если успех не растёт.

Почему структура проекта не спасает

Многие context files содержат обзор структуры проекта: перечисление папок, подсказки по типу “код здесь”, а “тесты там”. Кажется, это должно ускорять процесс. Авторы проверяют это через простой, но показательный прокси-сигнал: сколько шагов проходит до первого взаимодействия с файлом, который действительно был изменён в эталонном PR.

И тут неожиданно: без context files этот момент часто наступает раньше. То есть поход в репозиторий не ускоряет попадание в нужные места — а иногда даже наоборот.

Сценарий, где автогенерация всё-таки полезна

Есть важная оговорка, которая делает работу особенно честной. Авторы проверяют гипотезу: может быть, LLM-сгенерированные context files кажутся вредными лишь потому, что в популярных репозиториях и так много документации, и файл просто дублирует лишнее?

Они искусственно удаляют документацию из кодовой базы (md-файлы, docs и т.п.) и повторяют оценку. И вот в такой “пустыне” автогенерированные context files начинают выигрывать и иногда даже обходят человеческие файлы. Это хорошо объясняет, почему на практике разработчики нередко ощущают пользу: в плохо документированных проектах любой связный “быстрый гайд” действительно помогает.

Что из этого следует для тех, кто пишет AGENTS.md

Работа не говорит нам “не используйте context files”. Она скорее приземляет ожидания и подсказывает стиль: чем больше в файле требований, тем выше шанс, что агент станет медленнее и дороже — и не факт, что точнее. Лучший человекописный AGENTS.md, судя по выводам, — минимальный: только то, без чего агент реально не запустит проект (команды, тест-раннер, ключевые переменные окружения), а не попытка пересказать архитектуру и правила на все случаи жизни.

А вот автогенерацию “по кнопке” авторы прямо не рекомендуют: в среднем она ухудшает успешность и стабильно повышает стоимость. Если уж генерировать, то, возможно, как временную замену отсутствующей документации — и затем редактировать человеком, вырезая всё лишнее.