Файл с инструкциями для проекта попадает в контекст агента на каждой задаче. Это одновременно и его сила, и его слабость: всё, что там написано, читается заново и заново, а значит цена лишних строк не разовая, она платится на каждом запуске.
Зачем вообще нужен такой файл
Агент без файла инструкций каждый раз заново угадывает: как запускать тесты, какой стиль кода принят в проекте, какие команды опасны. Часть ответов он находит сам по коду, часть додумывает неверно.
Файл убирает эту неопределённость один раз. Вместо того чтобы объяснять контекст проекта в каждой задаче заново, вы пишете его один раз, и агент читает файл перед тем, как приступить к работе.
Что кладут внутрь напрасно
Самая частая ошибка, общие рассуждения о качестве кода: "пиши чистый код", "следуй лучшим практикам", "будь аккуратен". Такие фразы ничего не меняют в поведении модели, потому что не дают проверяемого критерия. Агент не знает, что конкретно сделать иначе.
Вторая частая ошибка, дублирование того, что уже видно из кода. Если в проекте один способ форматирования и он закреплён в конфиге линтера, не нужно описывать его словами в файле инструкций, агент и так его увидит и применит.
Третья ошибка, слишком длинный файл с историей решений. Объяснение, почему два года назад выбрали именно этот фреймворк, полезно для человека и почти бесполезно для агента на конкретной задаче. Такой контекст съедает место, которое могло бы уйти на действительно нужные правила.
Что реально стоит держать в файле
Работают конкретные, проверяемые инструкции. Точная команда для запуска тестов, а не общее "тестируй изменения". Точный список файлов или директорий, которые нельзя трогать без явного разрешения. Точный формат коммита, если он в проекте единый.
Особенно ценны инструкции про исключения из общих правил кода: где в проекте намеренно нарушен обычный паттерн и почему, чтобы агент не "исправил" это как ошибку. Такие вещи невозможно вывести из самого кода, их нужно сказать прямо.
Полезно фиксировать команды деплоя и порядок шагов перед ним: что проверить, в каком порядке, что делать при провале одного из шагов. Это ровно тот случай, где жёсткий чеклист лучше общего описания.
Хороший пример конкретного правила: "перед пушем в main запускай npm run lint и go vet ./..., при ошибке останавливайся и сообщай, а не пытайся исправить линтер сам". Такое правило проверяемо: агент либо запустил команды, либо нет, и результат виден сразу, в отличие от общего "следи за качеством кода".
Структура, которая работает
Короткие секции с заголовками работают лучше одного длинного текста: агенту проще найти нужный кусок, если структура предсказуема. Раздел про запуск и тесты, раздел про деплой, раздел про то, что нельзя делать, раздел про стиль, если он не покрыт линтером.
Порядок важен не меньше содержания. Самые критичные правила, то, что нельзя нарушать ни при каких условиях, стоит держать ближе к началу файла, а не прятать в середине среди второстепенных заметок.
Как проверить, что агент действительно читает файл
Лучшая проверка, простая: добавьте в файл одно конкретное и легко проверяемое правило, которого раньше не было, например требование к формату коммитов. Дайте агенту типовую задачу и посмотрите, соблюдено ли правило в результате.
Если правило нарушено, причина обычно одна из двух: формулировка слишком расплывчатая, или файл слишком длинный и правило потерялось среди менее важных строк. Оба случая лечатся сокращением, а не добавлением ещё текста.
Как не дать файлу устареть
Файл инструкций стареет вместе с проектом, и устаревшее правило иногда вреднее отсутствия правила: оно уверенно направляет агента в сторону, которая давно не работает.
Хорошая привычка, обновлять файл в том же коммите, где меняется процесс, который он описывает. Если поменялась команда деплоя, обновление файла инструкций входит в тот же pull request, а не откладывается на потом.
Коротко
CLAUDE.md работает, когда в нём конкретные и проверяемые правила, а не общие пожелания. Уберите то, что и так видно из кода, уберите историю решений, оставьте команды, границы и исключения из паттернов. Короткий файл с точными правилами агент соблюдает, длинный файл с общими словами он просто не замечает.