CLAUDE.md: как объяснить агенту ваш проект

5 мин чтения

CLAUDE.md лежит в корне проекта и подгружается автоматически. Это место для правил, которые иначе пришлось бы повторять в каждой задаче — и которые агент нарушит, если их не написать.

Что туда писать

Чего в проекте нет. «Не используем styled-components», «нет shadcn/ui» — иначе агент притащит это из готового сниппета, потому что так принято в интернете.
Неочевидные ловушки. Места, где легко ошибиться и где ошибка не видна сразу: дублирующаяся вёрстка, файлы, которые обязаны меняться парой, порядок запуска миграций.
Команды проверки. Что запустить перед коммитом: типы, тесты, сборка. Тогда агент проверит себя сам, без напоминаний.
Правила про деньги и доступ, если они есть. Это то место, где ошибка стоит дороже всего.

Чего писать не надо

Того, что видно из кода. Список папок и названия компонентов агент прочитает сам, и они устареют быстрее, чем вы их обновите.
Общих слов вроде «пиши чистый код» и «следуй лучшим практикам». Это не правило, а пожелание, и проверить его нельзя.
Длинных описаний архитектуры. Файл читается каждый раз, и чем он длиннее, тем хуже работает. Держите в пределах экрана-двух.
Секретов. Ключи, пароли, адреса внутренних сервисов — никогда.

Как понять, что правило нужно

Если вы объяснили одно и то же дважды в разных задачах — это кандидат в CLAUDE.md.
Если агент сделал что-то не так и вы поправили — запишите не саму правку, а правило, из которого она следует.
Хорошее правило объясняет почему, а не только что. «Ряды кнопок — flex-wrap, иначе на 360px они уезжают за край» работает лучше, чем «используй flex-wrap».

Пример структуры

Короткое описание проекта: что это и на чём сделано. Две-три строки.
Раздел про то, чего в проекте нет.
Разделы про узкие места — по одному на каждую область, где легко ошибиться.
Команды проверки перед коммитом.