Видео: «CLAUDE.md, которому Claude следует»
Вот ловушка, в которую попадают почти все: ваш файл CLAUDE.md постоянно растёт. Столкнулись с проблемой, добавили правило. Столкнулись с другой, добавили ещё одно. Вскоре у вас один огромный файл, и Claude начинает игнорировать его части. Это не ошибка Claude. Так устроен сам файл.
Главное, что нужно понять: CLAUDE.md не является принудительной конфигурацией. Это рекомендации. Каждая строка конкурирует со всеми остальными за внимание Claude. Чем длиннее файл, тем сильнее он конкурирует сам с собой и тем менее надёжно Claude соблюдает любое отдельное правило. Поэтому цель не в том, чтобы записать всё подряд. Цель в том, чтобы файл оставался компактным. Чем он короче, тем большей его части Claude действительно следует.

Сначала спросите себя, подходит ли вообще CLAUDE.md

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

Возьмём правило «никогда не пушить в main». Если поместить его в CLAUDE.md, вы надеетесь, что Claude его прочитает и будет соблюдать. В большинстве случаев так и будет. Но «в большинстве случаев» недостаточно для чего-то настолько опасного. Такому жёсткому правилу место в pre-tool-use hook (хуке, срабатывающем перед вызовом инструмента).

Разница существенная. Hook представляет собой код, который выполняется до того, как Claude совершит действие, и может действительно его заблокировать. Даже если Claude попытается запушить в main, hook его остановит. Это настоящее принуждение, а не вежливая просьба. Перенесите жёсткие правила в hooks, а CLAUDE.md оставьте для более мягких соглашений.

Четыре расположения

CLAUDE.md не ограничивается одним файлом в вашем проекте. Он может находиться в четырёх местах, и Claude загружает их все вместе при запуске. Ничего не отбрасывается, они складываются.

Вот для чего нужно каждое из них:

Managed policy: файл уровня организации, которым управляет ваша платформенная команда. Исключить его нельзя, поэтому политика организации действует всегда.
User: ваши личные предпочтения, которые применяются во всех проектах на вашем компьютере.
Project: файл, общий для всей команды и хранящийся в репозитории.
Local: игнорируется git. Ваши личные заметки только для этого репозитория.

Последний, local, легко упустить из виду, но он очень удобен. Допустим, вы делаете рефакторинг в своей ветке и хотите, чтобы Claude держал в голове некоторые архитектурные решения, пока вы работаете. Это не стоит класть в общий файл проекта, где оно повлияет на всю команду. Это место для local: там оно только ваше и только для этого репозитория.

Разбивайте большой файл с помощью импортов

Когда файл проекта становится длинным, его можно разбить на части с помощью синтаксиса импорта по пути к файлу. Вместо сплошной стены текста вы ссылаетесь на другие файлы:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

Это отличный способ навести порядок. Но точно понимайте, что он вам даёт, потому что здесь легко ошибиться. При запуске Claude разворачивает импортированные файлы прямо в том месте, где вы на них сослались. Импорты помогают поддерживать порядок, но всё по-прежнему загружается сразу. Они не уменьшают объём контекста, который Claude должен прочитать. Используйте импорты для организации, а не для сокращения нагрузки.

Формулировка определяет, будет ли правило соблюдаться

Когда вы решили, что правило должно быть в CLAUDE.md, то, будет ли Claude ему следовать, зависит от формулировки. Большинство правил не работают из-за расплывчатости. Вот как это исправить.

Будьте конкретны и проверяемы

Не пишите «следовать лучшим практикам». Вы сами точно знаете, что это значит? Если вы не можете проверить, выполнено ли правило, Claude тоже не сможет. Сравните два варианта:

Расплывчато: «Следовать лучшим практикам для API-маршрутов».
Конкретно: «Размещать новые API-маршруты в src/api/handlers, по одному на файл».

Второй вариант однозначен. Вы смотрите на результат и сразу видите, сделано ли всё правильно. Это планка, которую должно преодолевать каждое правило.

Называйте замену, а не просто запрещайте

Когда вы говорите Claude чего-то не делать, укажите, что делать вместо этого. Иначе вы оставляете лазейку.

Оставляет лазейку: «Не использовать экспорт по умолчанию». Хорошо, а что тогда?
Закрывает её: «Использовать именованные экспорты, а не экспорт по умолчанию».

Второй вариант называет замену, и неверно истолковать его уже нельзя.

Акцент как бюджет

Слова вроде «IMPORTANT» и «YOU MUST» действительно повышают приоритет правила. Но только относительно всего более «тихого» вокруг. Если кричит каждое правило, ничто не выделяется, и акцент теряет смысл. Поэтому относитесь к акцентам как к бюджету. Тратьте его на два-три правила, нарушение которых действительно болезненно, а остальные пусть звучат в обычном тоне.

Постоянно пересматривайте файл

Ваш файл CLAUDE.md никогда не бывает завершён. Относитесь к нему как к живому коду, который постоянно редактируется.

Когда Claude делает что-то не так, не вздыхайте и не исправляйте вручную. Считайте это баг-репортом к вашему CLAUDE.md. Можно даже прямо сказать Claude: «добавьте это в файл CLAUDE.md», и он сам напишет правило. Так файл становится лучше каждый раз, когда что-то идёт не так.

Главное

Относитесь к CLAUDE.md как к продакшен-коду. Если строку нельзя обосновать, удалите её. Чтобы файл оставался компактным и выполнимым:

Переносите жёсткие правила в hooks, где они действительно принудительно соблюдаются.
Организуйте длинные файлы с помощью импортов (только помните, что они не уменьшают контекст).
Делайте каждое правило конкретным и проверяемым и называйте замену.
Тратьте бюджет акцентов на несколько самых важных правил.
Пересматривайте файл каждый раз, когда Claude делает что-то не так.

Идея простая. Чем компактнее файл, тем большей его части Claude следует.

CLAUDE.md, которому Claude следует