Эффективность AGENTS.md в разработке с ИИ-агентами
A@ai_productAI-инженер
3 недИсследование влияния файла AGENTS.md на производительность ИИ-агентов при работе с кодом. Выводы о том, какие инструкции реально помогают, а какие бесполезны.
Файлы с инструкциями для ИИ-агентов работают как операционные памятки, а не как база знаний.
- Инструкции о стиле кода или архитектуре (SOLID) не улучшают качество работы агентов.
- Технические ограничения (время выполнения тестов, команды сборки) реально экономят ресурсы и время.
- Агенты лучше справляются с задачами при качественной декомпозиции, а не при наличии подробных описаний проекта в контексте.
Помогает ли claude.md файл?
Интересный рисерч. Взяли три реальных Python-репозитория с хорошими AGENTS.md – pdm, firebase-admin-python и opshin. Из смерженных PR сделали 17 задач: описание PR = промпт агенту, тесты из этого же PR = скрытая проверка. Агент тестов не видит.
Дальше три режима подачи контекста:
– none – файл вообще убран из воркспейса
– always_on – весь AGENTS.md вставляется в системный промпт каждый ход
– selective – вместо файла лежит вики по темам, агент читает нужное сам
Прогнали на Claude Code (Sonnet 4.6) и Codex CLI (GPT-5.5), по 3 повтора. Всего 288 засчитанных прогонов.
Результат - все тлен. Claude: 53,3% / 55,6% / 55,6%. Codex: 58,8% / 56,9% / 52,9%. В пределах шума.
Автор вручную разобрал «почти прошедшие» падения – те, где до зачёта не хватило пары тестов. И там ни одного случая, где агенту не хватило знания о репозитории. Не хватало интеллекта и инженерии, и такое AGENTS.md не лечит.
Отдельно проверял улучшение правил, чтобы падения починить. Не получилось.
А вот что реально сработало: у репозитория opshin в AGENTS.md есть строчка: полный прогон тестов занимает больше 20 минут. Без контекста Claude вслепую гонял весь сьют 3,67 раза за прогон. С always_on – 2,44. С selective – 1,67. Время выполнения упало с 2689 до ~2030 секунд, примерно на четверть. Корректность при этом не сдвинулась ни на пункт.
То есть контекст-файл работает как операционная инструкция, а не как учебник. «Не запускай полный сьют, он медленный», «сборка вот этой командой», «линтер такой» – экономит время и деньги.
А вот всякие там "ты синьор разработчик", "мы придерживаемся чистой архитектуры и SOLID" – не делает ничего измеримого.
До этого были две работы с противоположными выводами – одна на Codex-агентах нашла пользу у файла, другая на Claude-агентах не нашла. Оказалось, сложность задач у агентов не совпадает: примерно у 40% задач агенты по-разному упираются в потолок. Задача, на которой можно было бы увидеть эффект у одного агента, у другого либо решается всегда, либо не решается никогда.
Короче, писать AGENTS.md стоит, но как список правил, не как описание проекта. Команды, тайминги, грабли, что не трогать. Всё, что агент может вывести из кода сам, туда класть бессмысленно: он и выведет. А качество реализации вытягивается не файлом, а декомпозицией задачи и примерами.
https://arxiv.org/abs/2607.27250
Кратко (AI)
Исследование показало, что наличие файла AGENTS.md в репозитории практически не влияет на качество решения задач ИИ-агентами, так как они упираются в ограничения интеллекта, а не нехватку контекста. Однако такие файлы полезны как операционные инструкции (тайминги, команды, ограничения), позволяя экономить время и ресурсы за счет оптимизации действий агента.
Обсуждение
2288 прогонов с числами вместо «мне помогло» — уже респект. Про опшин вообще показательно: файл агента не умнее не делает, но экономит четверть времени просто тем что не гоняет тесты вслепую. Похоже что такие файлы в итоге и станут чек-листами граблей, а не манифестами про SOLID.
ну а что тут удивительного, всегда было понятно что агент не тянет сложные задачи, а не правила не знает. файл как чек-лист по командам и таймингам норм, но продавать его как 'контекст проекта' это хайп изначально был. selective vs always_on там разница в шуме, интеллект потолок все равно не пробивает.