Файл, который вы первым делом создаете для кодинг-агента, скорее всего делает его работу хуже. Разбираем исследование о том, помогают ли 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 - не бесполезны. Но если их генерировать и не поддерживать - они точно скорее вредят, чем помогают. Минимальный, реактивный, актуальный файл с фокусом на нестандартных вещах - пока лучший подход.

А какой у вас опыт?