Файл, который вы первым делом создаете для кодинг-агента, скорее всего делает его работу хуже. Разбираем исследование о том, помогают ли AGENTS.md и CLAUDE.md файлы кодинг-агентам решать задачи.
Если вы работаете с Claude Code, Codex или Cursor — вы наверняка слышали: «первым делом настрой CLAUDE.md AGENTS.md`" (обобщим как context files). Кто-то использует шаблоны из Github и постов, а кто-то запускает `/init`. Звучит как must-have. Но исследователи из ETH Zurich решили проверить, работает ли это на самом деле.
Что проверяли и к чему пришли
Исследование «Do Context Files Help?» тестировало три сценария: агент с developer-written файлом, агент без файла вообще, и агент с LLM-generated файлом (тот самый /init). Задачи — реальные GitHub issues из SWE-bench. Получили:
— Developer-written файлы: +4% к resolve rate. Небольшой прирост
— LLM-generated файлы: -3%. Хуже, чем без файла вообще
— Стоимость: +20% во всех сценариях с context files
Результат стабилен по моделям и промптам для генерации. Авторы рекомендуют отказаться от auto-generated файлов и включать только минимальные специфические требования.
Когда модель сама генерирует описание кодовой базы, она записывает то, что и так может найти за минуту через rg и чтение package.json. По сути это дублирование. Только теперь это дублирование сидит в контексте каждого запроса, занимает токены и создает bias.
Еще есть и концепция «instruction budget» — frontier модели удерживают в фокусе примерно 150-200 инструкций. Но это общий бюджет на все: system prompt инструмента, ваш context file и сама задача. Системный промпт Claude Code или Codex уже занимает значительную часть этого бюджета. Каждая лишняя строка в вашем файле конкурирует за внимание модели со всем остальным.
Мой подход
Я практически не использую /init. Вместо этого начинаю с ручного минималистичного CLAUDE.md. Там чаще бизнес-контекст (про что проект, текущее состояние, что важно учитывать на этой стадии), а не описание файловой структуры. Придерживаюсь реактивного подхода: если агент раз за разом делает одну и ту же ошибку — добавляю правило. Не делает — не добавляю. Периодически делаю ревизию.
Часто использую условные правила вместо постоянных: «если делаешь X — используй Y» вместо «всегда используй Y». Это снижает noise для задач, где правило нерелевантно.
В больших проектах — вложенные файлы по папкам. Progressive disclosure: агент получает инструкции только для той части кодовой базы, в которой работает.
Еще из наблюдений
— Негативные инструкции («не используй X») парадоксально могут увеличить вероятность использования X. Лучше укажите что использовать вместо.
— Периодически удаляйте файл целиком и смотрите, что реально сломается. С каждым апдейтом моделей — сломается все меньше
— Compiler/linter лучше текстовых инструкций — если можно выразить правило через ESLint rule, tsconfig strict, pre-commit hook — это надежнее
— AGENTS.md ≠ CONTRIBUTING.md — если у вас уже есть CONTRIBUTING.md для людей, не дублируйте. Просто сошлитесь на него. То же касается README.md
— Не скачивайте всякие чужие awesome-claude-md-for-best-developers-pack — там нет нюансов вашего проекта, зато есть накопленные рудименты, которые современные модели и так знают.
— Иногда вам просто не нужен файл контекста, на сегодня вполне ок кодить без него, особенно если проект новый.
Context files — не бесполезны. Но если их генерировать и не поддерживать — они точно скорее вредят, чем помогают. Минимальный, реактивный, актуальный файл с фокусом на нестандартных вещах — пока лучший подход.
А какой у вас опыт?
Добавить комментарий