Конспект урока «A CLAUDE.md That Follows» из бесплатного курса Anthropic Claude Code in Action. Оригинал урока: https://anthropic.skilljar.com/claude-code-in-action/486929
Это пересказ на русском, а не перевод. Права на курс принадлежат Anthropic.
Файл CLAUDE.md разрастается сам собой: наткнулся на проблему — дописал правило, ещё раз наткнулся — ещё правило. В какой-то момент файл становится огромным, и Клод начинает часть правил игнорировать.
Это не баг. Так файл устроен: CLAUDE.md — не конфиг, а рекомендации. Каждая строчка конкурирует за внимание со всеми остальными. Чем длиннее файл, тем сильнее он конкурирует сам с собой и тем хуже соблюдается любое отдельное правило.
Отсюда главный вывод урока: цель не в том, чтобы записать всё. Цель — держать файл коротким. Чем он компактнее, тем большей его части Клод реально следует.
Прежде чем добавить строку, реши: это рекомендация или жёсткий запрет, который нельзя нарушать ни при каких условиях. Это две разные задачи.
Возьми правило «никогда не пушить в main». Записав его в CLAUDE.md, ты надеешься, что Клод прочитает и не станет. Скорее всего не станет. Но «скорее всего» — плохая гарантия для настолько опасной вещи.
Такому правилу место в hook'е на pre-tool-use. Hook — это код, который выполняется до действия и может его заблокировать. Даже если Клод попытается запушить в main, hook его остановит. Это настоящее принуждение, а не вежливая просьба.
Жёсткие правила — в hooks, мягкие договорённости — в CLAUDE.md.
CLAUDE.md — это не один файл в проекте. Их четыре, и при запуске Клод загружает все разом: ничего не теряется, они складываются друг с другом.
| Уровень | Для чего |
|---|---|
| Managed policy | файл уровня организации, им управляет платформенная команда. Исключить его нельзя — политика компании действует всегда |
| User | твои личные предпочтения, ездят за тобой по всем проектам на этой машине |
| Project | общий с командой файл, лежит в репозитории |
| Local | не попадает в git. Личные заметки под конкретный репозиторий |
Последний уровень часто упускают из виду, а он удобный. Скажем, ты рефакторишь в своей ветке и хочешь, чтобы Клод держал в голове пару архитектурных решений. В общий файл это класть нельзя — оно повлияет на всю команду. А в local — в самый раз.
Когда проектный файл разрастается, его можно разложить на куски через импорты:
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md
Тут важно не обмануться. При запуске Клод разворачивает импортированные файлы прямо на месте ссылки. То есть импорты помогают навести порядок, но объём читаемого контекста не уменьшают ни на байт. Используй их для организации, а не для экономии.
Если правило всё-таки идёт в CLAUDE.md, соблюдение зависит от того, как оно написано. Большинство правил не работает потому, что они расплывчатые.
Будь конкретным и проверяемым. Не пиши «следуй лучшим практикам» — ты и сам вряд ли скажешь, что именно под этим имеется в виду. Если ты не можешь проверить, соблюдено ли правило, то и Клод не может.
src/api/handlers, по одному на файл».Второе можно посмотреть на результат и сразу сказать, сделано или нет. Вот планка для любого правила.
Называй замену, а не только запрет. Запретил — скажи, что делать вместо этого, иначе дверь остаётся открытой.
Выделение — это бюджет. Слова вроде «ВАЖНО» и «ТЫ ДОЛЖЕН» действительно поднимают приоритет правила — но только относительно того, что вокруг звучит тише. Если кричат все правила, не выделяется ни одно. Трать этот бюджет на два-три правила, нарушение которых реально больно бьёт, остальные оставь обычной громкости.
Относись к CLAUDE.md как к живому коду, который постоянно правят.
Когда Клод сделал не то, не вздыхай и не исправляй руками молча — считай это баг-репортом на твой CLAUDE.md. Можно прямо сказать Клоду: «добавь это в CLAUDE.md», и он сам сформулирует правило. Так файл становится лучше после каждой осечки.
Относись к CLAUDE.md как к продакшн-коду: не можешь обосновать строку — удали её.
Идея простая: чем компактнее файл, тем большей его части Клод следует.