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