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

CLAUDE.md - обычный markdown-файл с инструкциями, который Claude Code читает в начале каждой сессии. В него кладут то, что иначе приходится объяснять заново каждый раз: чем собирается проект, какими командами гоняются тесты, где что лежит, чего в этом коде делать нельзя. Файл кладётся в корень проекта, создаётся командой /init и работает без всякой настройки.

Дальше - где именно он может лежать, почему файлов на самом деле несколько, что с ними делает механизм импортов, и почему написанное в нём иногда не выполняется.

Что такое CLAUDE.md

Каждая сессия Claude Code начинается с пустого контекста. Модель не помнит ни прошлого разговора, ни ваших поправок, ни того, что вчера вы просили не трогать папку с миграциями. CLAUDE.md - способ перенести это знание через границу сессии: его содержимое подставляется в начало каждого нового разговора.

Важная деталь, из которой следует почти всё остальное: CLAUDE.md попадает в контекст не как часть системного промпта, а как обычное сообщение пользователя. Claude его читает и старается выполнять, но это не конфигурация, которую что-то принудительно применяет. Гарантии исполнения нет.

Если инструкция должна выполняться всегда и без исключений - «не пушить в main», «прогонять линтер перед коммитом», - её место не в CLAUDE.md, а в хуке. Хук это shell-команда, привязанная к событию жизненного цикла: она срабатывает независимо от того, что решила модель. CLAUDE.md задаёт поведение, хук его гарантирует.

Рядом с CLAUDE.md в Claude Code живёт вторая система памяти - автопамять, куда заметки пишет уже сам Claude. Различие простое: CLAUDE.md пишете вы и держите там правила, автопамять пишет Claude и держит там выводы из ваших поправок. Про неё отдельный раздел ниже.

Что кладут в CLAUDE.md:

команды сборки, запуска и тестов, которые нельзя вывести из кода однозначно;
соглашения проекта: отступы, именование, формат коммитов;
раскладку: где handler-ы, где миграции, куда не лезть;
правила вида «всегда делай X» и «никогда не делай Y».

Признак, что пора дописать строку в файл: вы второй раз печатаете в чат одну и ту же поправку. Или ревью поймало то, что Claude должен был знать про этот проект с самого начала.

Что в CLAUDE.md класть не стоит: многошаговые процедуры и всё, что нужно ровно в одной части кодовой базы. Процедура - это навык, он подключается по описанию задачи и не висит в контексте постоянно. Инструкция для одного каталога - правило с областью применения, о нём ниже.

Где лежат файлы и в каком порядке грузятся

CLAUDE.md - не один файл, а четыре области видимости. Порядок в таблице - это порядок загрузки, от самой широкой области к самой узкой.

Область	Путь	Для чего
Политика организации	Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` Linux и WSL: `/etc/claude-code/CLAUDE.md`	Правила компании. Раскатывается через MDM или групповые политики, отключить настройками пользователя нельзя
Пользователь	`~/.claude/CLAUDE.md`	Ваши личные предпочтения во всех проектах на этой машине
Проект	`./CLAUDE.md` или `./.claude/CLAUDE.md`	Общие правила проекта, едут в репозитории вместе с кодом
Локально	`./CLAUDE.local.md`	Личное для этого проекта: свои адреса стендов, тестовые данные. Добавляется в `.gitignore`

Файлы не перекрывают друг друга - они складываются в контекст один за другим. Внутри каталога CLAUDE.local.md идёт после CLAUDE.md, так что ваши личные заметки Claude читает последними на этом уровне.

Второе, что стоит знать про загрузку: собираются не только файлы рабочего каталога, но и все каталоги выше него. Запустили Claude Code в foo/bar/ - подтянутся foo/bar/CLAUDE.md, foo/CLAUDE.md и лежащие рядом с ними CLAUDE.local.md. Порядок - от корня файловой системы вниз, к рабочему каталогу: то, что ближе к месту запуска, читается последним.

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

В монорепозитории соседние команды нередко держат свои CLAUDE.md выше по дереву, и они приезжают к вам вместе с остальным. Лишние файлы отключаются настройкой claudeMdExcludes - список путей или glob-масок, которые пропускаются при загрузке:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Держать такое лучше в .claude/settings.local.json, чтобы исключение осталось на вашей машине и не уехало команде. Файл политики организации исключить нельзя ни одной настройкой - в этом и смысл этого уровня.

Проверить, что именно загрузилось в текущую сессию, можно командой /context: там есть раздел Memory files со списком подхваченных файлов. Если вашего файла в списке нет - Claude его не видит, и дальше искать причину в формулировках бессмысленно.

Первый файл: команда /init

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

Ещё /init умеет забирать правила соседних инструментов. По умолчанию он читает правила Cursor - из .cursor/rules/ или .cursorrules - и инструкции Copilot из .github/copilot-instructions.md, и переносит из них подходящее.

Есть расширенный режим: с переменной окружения CLAUDE_CODE_NEW_INIT=1 команда работает диалогом. Она спрашивает, что именно завести (CLAUDE.md, навыки, хуки), изучает проект отдельным подагентом, задаёт уточняющие вопросы и показывает предложение до того, как что-то запишет на диск. В этом режиме /init дополнительно читает AGENTS.md, .devin/rules/, .windsurf/rules/ и .clinerules.

Дальше файл дорабатывается руками. Сгенерированный /init текст описывает то, что и так видно в коде; ценность появляется, когда вы добавляете к нему то, чего в коде не написано - причины решений, известные грабли, договорённости команды.

Как писать, чтобы инструкциям следовали

CLAUDE.md занимает место в контекстном окне с первой секунды сессии, и от того, как он написан, напрямую зависит, насколько точно его выполняют.

Размер. Ориентир из документации - до 200 строк на файл. Длиннее - больше расход контекста и хуже соблюдение. Формальный потолок другой: файл до 4 МиБ загружается целиком, файл больше пропускается молча. Но 4 МиБ это предел парсера, а не рекомендация.

Конкретность. Инструкцию должно быть возможно проверить. Разница видна сразу:

Работает плохо	Работает
Форматируй код правильно	Отступ - 2 пробела
Проверяй изменения	Перед коммитом запускай `npm test`
Держи файлы в порядке	Обработчики API лежат в `src/api/handlers/`

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

Структура. Заголовки и списки читаются лучше плотных абзацев - здесь это работает так же, как для человека.

Полезная мелочь: блочные HTML-комментарии  вырезаются из CLAUDE.md до подстановки в контекст. В них удобно оставлять пометки для людей, которые сопровождают файл, не тратя на них токены. Комментарии внутри блоков кода при этом сохраняются, и при обычном чтении файла инструментом они тоже видны.

Импорты @path и чужой AGENTS.md

CLAUDE.md умеет подключать другие файлы синтаксисом @путь:

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

Пути работают и относительные, и абсолютные; относительный считается от файла, где написан импорт, а не от рабочего каталога. Импортированный файл может импортировать следующий, максимальная глубина - четыре шага.

Разбор импортов пропускает код: то, что стоит в обратных кавычках или в блоке кода, файлом не считается. Нужно упомянуть путь в тексте без подключения - оберните его в кавычки-бэктики.

Импорт не экономит контекст. Подключённые файлы разворачиваются и грузятся при старте вместе с самим CLAUDE.md. Разбивать файл на импорты имеет смысл ради порядка, а не ради экономии токенов - для экономии нужны правила с областью применения.

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

У этого механизма есть практическое применение: если вы работаете в нескольких git worktree одного репозитория, CLAUDE.local.md будет только в том worktree, где вы его создали. Общие личные инструкции переносятся импортом из дома:

# Individual Preferences
- @~/.claude/my-project-instructions.md

AGENTS.md. Claude Code читает CLAUDE.md и не читает AGENTS.md. Если в репозитории уже лежит AGENTS.md для других агентов, дублировать его не надо - достаточно CLAUDE.md с импортом, а ниже можно дописать то, что касается только Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Симлинк ln -s AGENTS.md CLAUDE.md тоже работает, если ничего своего дописывать не нужно. На Windows симлинк требует прав администратора или включённого режима разработчика, поэтому там проще импорт.

Когда файл разросся: .claude/rules

Когда правил становится много, их выносят в каталог .claude/rules/. Один файл - одна тема, имя говорящее:

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Файлы находятся рекурсивно, так что правила можно разложить по подкаталогам вроде frontend/ и backend/. Правило без особых пометок грузится при старте с тем же приоритетом, что .claude/CLAUDE.md.

Главное здесь - привязка к путям. Правило с полем paths во фронтматтере попадает в контекст не всегда, а когда Claude работает с подходящими файлами:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

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

В масках работают фигурные скобки: src/**/*.{ts,tsx} разворачивается в два шаблона. Раскрытие ограничено бюджетом в 1000 шаблонов на одно правило - маска, которая в него не влезает, используется как есть, и её буквальные скобки не совпадут ни с одним файлом.

Есть и личные правила - ~/.claude/rules/, они применяются во всех проектах машины и грузятся раньше проектных, то-есть проектные важнее.

Граница между правилом и навыком проходит по тому, нужна ли инструкция постоянно. Правила лежат в контексте всю сессию (или пока не откроется подходящий файл), навык подгружается только когда задача его касается. Если инструкция нужна раз в неделю - это навык, а не правило.

Автопамять: что Claude пишет себе сам

Вторая система памяти работает без вашего участия. Claude сам сохраняет заметки четырёх типов: user - про вас и вашу манеру работы, feedback - ваши поправки и подтверждённые подходы, project - то, что происходит в проекте и не выводится из кода и истории git, reference - куда смотреть за пределами проекта.

Автопамять включена по умолчанию. Живёт она в ~/.claude/projects/<проект>/memory/, каталог определяется по git-репозиторию - все worktree и подкаталоги одного репозитория пишут в одну память. Внутри лежат индекс MEMORY.md и по файлу на тему.

В начало каждой сессии грузятся первые 200 строк MEMORY.md или первые 25 КБ - что кончится раньше. Всё, что дальше, не читается вовсе, поэтому индекс держится коротким: одна строка на запись, подробности в тематических файлах. Тематические файлы при старте не грузятся, Claude открывает их сам, когда они понадобились.

Выключается автопамять тремя способами: переключателем в /memory, ключом "autoMemoryEnabled": false в настройках (в проектных - только для этого проекта) или переменной CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Всё, что она сохранила, - обычный markdown, который можно прочитать, поправить и удалить. Команда /memory показывает список файлов памяти и открывает выбранный в редакторе. Смотреть туда стоит: память машинно-локальная, между машинами не синхронизируется, и мусор в ней накапливается незаметно.

Ещё одна деталь для тех, кто работает с подагентами: автопамять основного разговора в подагента не передаётся. У подагента может быть своя, отдельная.

Инструкции не работают: что проверять

Самая частая жалоба на CLAUDE.md - «написано, но не выполняется». Порядок разбора такой.

Файл вообще загрузился? /context, раздел Memory files. Нет в списке - дальше идти некуда, проблема в расположении файла, а не в тексте.
Файл в подхватываемом месте? Сверьтесь с таблицей областей. Частый случай - файл лежит в подкаталоге, а Claude Code запущен выше.
Инструкция конкретная? Расплывчатую выполнить нельзя даже при желании.
Нет ли противоречия? Проверьте пользовательский, проектный и вложенные файлы вместе, плюс .claude/rules/. Два разных правила про одно и то же дают случайный выбор.

Отдельный сюжет - «инструкции пропали после /compact». Проектный CLAUDE.md из корня сжатие переживает: после /compact он перечитывается с диска и подставляется заново. Вложенные файлы и правила с paths вернутся, когда Claude снова прочитает подходящий файл. А вот сказанное только в разговоре не вернётся никогда - если инструкция важная, её место в файле, а не в реплике.

Когда правило должно исполняться в конкретный момент - перед каждым коммитом, после каждой правки файла - переписывайте его в хук. Для инструкций уровня системного промпта есть флаг --append-system-prompt, но его надо передавать при каждом запуске, так что он для скриптов и автоматизации, а не для работы руками.

Короткий чек-лист

Ставится один раз и дальше не требует внимания:

/init в корне проекта, потом руками дописать то, чего в коде не видно;
держать файл в пределах ~200 строк, конкретика вместо общих слов;
личное - в CLAUDE.local.md и в .gitignore;
разрослось - .claude/rules/ с полем paths, а не длинный CLAUDE.md;
чужой AGENTS.md - импортом @AGENTS.md, без копирования;
не выполняется - сначала /context, потом уже формулировки;
должно выполняться всегда - хук, а не CLAUDE.md.

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