Помогает ли 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
Интересный рисерч. Взяли три реальных 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