CLAUDE.md: как писать правила проекта для Claude Code

Каждая сессия Claude Code стартует с чистого контекста: агент не помнит, как устроен ваш проект, какими командами он собирается и что вы обсуждали вчера. Чтобы не объяснять одно и то же по кругу, есть файл CLAUDE.md — обычный markdown-документ, который агент читает в начале каждой сессии. Это одновременно память проекта и свод правил: где что лежит, как запускать тесты, каких соглашений держаться. Разберём, где его размещать, как он загружается и что в него писать.

Что такое CLAUDE.md и зачем он нужен

CLAUDE.md — это инструкции, которые вы пишете сами, чтобы задать агенту постоянный контекст: для проекта, личного процесса или всей компании. Файл работает как памятка, которую Claude держит перед глазами всю сессию. Важный нюанс: это именно контекст, а не жёсткая конфигурация. Агент старается следовать инструкциям, но строгого исполнения не гарантирует — чем конкретнее и короче формулировки, тем стабильнее результат. Если действие нужно выполнить принудительно (запретить команду, запустить проверку перед коммитом), для этого есть хуки, а не CLAUDE.md.

Простое правило: добавляйте то, что иначе пришлось бы объяснять заново. Claude второй раз наступил на те же грабли, вы снова печатаете вчерашнюю поправку — всё это кандидаты в CLAUDE.md. Держите там факты, нужные в каждой сессии: команды сборки и тестов, соглашения по коду, структуру проекта, правила «всегда делай X».

Где размещать CLAUDE.md: четыре уровня

Файл может лежать в нескольких местах, у каждого своя область видимости. Уровни идут в порядке загрузки — от самого широкого к самому конкретному, поэтому проектная инструкция оказывается в контексте после пользовательской и при конфликте имеет приоритет.

Управляемая политика (организация). Централизованный файл для всех разработчиков на машине: на macOS — /Library/Application Support/ClaudeCode/CLAUDE.md, на Linux и WSL — /etc/claude-code/CLAUDE.md, на Windows — C:\Program Files\ClaudeCode\CLAUDE.md. Сюда идут корпоративные стандарты; отключить его настройками пользователя нельзя.

Пользовательские инструкции. Файл ~/.claude/CLAUDE.md — ваши личные предпочтения сразу для всех проектов: стиль кода, привычные шорткаты.

Проектные инструкции. Файл ./CLAUDE.md или ./.claude/CLAUDE.md в корне репозитория. Это командный документ, он попадает в контроль версий, поэтому пишите сюда именно проектные стандарты — архитектуру, команды, соглашения об именовании, — а не личные привычки.

Локальные инструкции. Файл ./CLAUDE.local.md для личных заметок, которые не должны попасть в репозиторий: адреса песочниц, тестовые данные. Его добавляют в .gitignore, а загружается он рядом с CLAUDE.md.

Как файлы загружаются

Claude Code читает CLAUDE.md, поднимаясь вверх по дереву каталогов от рабочей директории и проверяя в каждой папке CLAUDE.md и CLAUDE.local.md. Найденные файлы не перезаписывают друг друга, а склеиваются: сверху то, что ближе к корню, снизу то, что ближе к месту запуска. Файлы в подкаталогах ниже тоже находятся, но грузятся не сразу, а когда Claude открывает файлы в этих папках. Проверить, что реально загрузилось в сессию, помогает команда /context — в разделе Memory files.

Что писать в CLAUDE.md

Файл целиком уходит в контекст в начале каждой сессии, поэтому его объём влияет и на расход токенов, и на то, насколько точно Claude следует правилам. Несколько ориентиров.

Размер. Цельтесь в объём до 200 строк на файл — более длинные документы съедают контекст и снижают адгезию (вероятность, что инструкция будет соблюдена). Если правил много, часть выносите в правила под конкретные пути (о них ниже).

Структура. Используйте заголовки и списки, группируйте связанные инструкции: по разделам агент ориентируется проще, чем в плотном абзаце.

Конкретность. Пишите так, чтобы правило можно было проверить. «Отступ — два пробела» лучше, чем «форматируй код правильно»; «запускай npm test перед коммитом» лучше, чем «тестируй изменения».

Непротиворечивость. Если два правила спорят, Claude выберет одно произвольно, поэтому периодически убирайте устаревшее. О том, какие сведения вообще стоит фиксировать в документации проекта, мы писали в заметке Что описать в файлах документации.

Импорты через @path

Чтобы не раздувать один файл, CLAUDE.md умеет подтягивать другие файлы синтаксисом @path/to/import: строка вроде См. @README и @package.json вставит их содержимое в контекст при запуске. Импортируемые файлы могут импортировать другие — максимум на четыре «прыжка» вглубь. Отдельный полезный сценарий — AGENTS.md: Claude Code читает CLAUDE.md, а не AGENTS.md, поэтому если в репозитории уже есть AGENTS.md для других агентов, создайте CLAUDE.md со строкой @AGENTS.md в начале — оба инструмента будут читать одни правила без дублирования.

.claude/rules/ — правила под конкретные файлы

Для крупных проектов инструкции удобно разбить на тематические файлы в каталоге .claude/rules/: testing.md, api-design.md, security.md. Все .md-файлы обнаруживаются рекурсивно и грузятся при запуске с тем же приоритетом, что и .claude/CLAUDE.md. Самое ценное — правило можно привязать к путям через YAML-заголовок с полем paths: правило с paths: ["src/api/**/*.ts"] об обязательной валидации активируется лишь при работе с API-хендлерами, а не висит в контексте всегда. Это экономит контекст и убирает шум. Подход хорошо ложится на дисциплину из нашей шпаргалки по структуре проекта для Claude Code.

CLAUDE.md и авто-память: в чём разница

У Claude Code две системы памяти, и обе загружаются в начале каждого разговора. CLAUDE.md пишете вы — это инструкции и правила. Авто-память (auto memory) агент ведёт сам: по ходу работы он сохраняет для себя команды сборки, находки при отладке и замеченные предпочтения. Хранится она локально, рядом с проектом, с файлом-индексом MEMORY.md; просмотреть и настроить её можно командой /memory. Практический вывод: осознанные стабильные правила — в CLAUDE.md; накопление опыта «на лету» оставьте авто-памяти.

Быстрый старт и частые ошибки

Писать файл с нуля не обязательно. Команда /init проанализирует кодовую базу и сгенерирует стартовый CLAUDE.md с найденными командами сборки, тестами и соглашениями; если файл уже есть, она предложит улучшения, а не перезапишет его. Заодно /init подхватывает правила из .cursor/rules/ и .github/copilot-instructions.md. Дальше дорабатывайте руками. Если вы только начинаете, загляните в наш практический гайд по Claude Code.

Когда Claude «не слушается» файла, причин обычно три: он не загрузился (проверьте через /context, что он в списке Memory files), формулировки расплывчаты или инструкции разных уровней конфликтуют. И помните: то, что должно срабатывать строго в определённый момент, — работа для хука, а инструкции из чата теряются после сжатия контекста, поэтому важное переносите в CLAUDE.md.

Вывод

CLAUDE.md — самый дешёвый способ сделать агента полезным именно в вашем проекте: один аккуратный файл на 100–200 строк экономит десятки повторных объяснений. Начните с /init, оставьте только конкретные и проверяемые правила, объёмные темы разнесите по .claude/rules/ с привязкой к путям, а личное держите в CLAUDE.local.md. Тогда каждая новая сессия стартует не с чистого листа, а с уже понятым контекстом вашей кодовой базы.