CLAUDE.md: как настроить память и инструкции для Claude Code

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

Например, Claude может использовать npm, хотя проект давно работает на pnpm, положить новый модуль не в тот каталог или закончить задачу, не запустив обязательные тесты. Причина не обязательно в качестве модели. Скорее всего, ей просто не сообщили правила проекта.

Повторять одни и те же инструкции в каждом новом диалоге неудобно. Для этого в Claude Code есть постоянные инструкции — прежде всего файл CLAUDE.md. А рядом с ним работает auto memory: механизм, благодаря которому Claude может самостоятельно сохранять полезный контекст между сессиями.

Главное — не путать эти два инструмента.

Проще говоря: CLAUDE.md — это правила, которые задаёте вы, а auto memory — заметки, которые ведёт сам Claude. Оба механизма загружаются между сессиями, но решают разные задачи.

Что такое CLAUDE.md

CLAUDE.md — обычный Markdown-файл с постоянными инструкциями для Claude Code.

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

Например:

# Project instructions

## Commands

- Install dependencies with `pnpm install`.
- Run tests with `pnpm test`.
- Run lint with `pnpm lint`.

## Architecture

- API handlers live in `src/api/`.
- Business logic belongs in `src/services/`.
- Database access goes through `src/repositories/`.

## Working rules

- Do not edit generated files manually.
- Do not add dependencies unless necessary.
- Run relevant tests after changing application logic.

После этого Claude Code получает эти инструкции как часть рабочего контекста.

В официальной документации Anthropic рекомендует помещать в CLAUDE.md то, что в противном случае пришлось бы регулярно объяснять Claude заново: команды сборки и тестирования, соглашения по коду, устройство проекта, архитектурные решения и обязательные рабочие правила.

Где создать CLAUDE.md

Для обычного проекта достаточно создать CLAUDE.md в корне репозитория:

my-project/
├── CLAUDE.md
├── package.json
├── src/
└── tests/

Корень репозитория — это основная папка проекта, где обычно находятся исходный код, конфигурационные файлы и каталог Git.

Поддерживается и второй вариант:

.claude/CLAUDE.md

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

Можно ли не писать файл с нуля

Да. В Claude Code есть команда:

/init

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

Если CLAUDE.md уже существует, /init предлагает улучшения, а не просто перезаписывает существующий файл.

Но автоматически созданную версию стоит воспринимать как черновик.

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

Поэтому после /init файл лучше просмотреть вручную.

Что действительно стоит записывать в CLAUDE.md

Здесь работает хороший практический критерий:

Если вы регулярно объясняете Claude одно и то же, возможно, это пора записать в CLAUDE.md.

Anthropic предлагает похожий подход: постоянные инструкции стоит обновлять, если Claude второй раз допускает одну и ту же ошибку, разработчику снова приходится вводить то же уточнение или code review обнаруживает правило, которое Claude должен был знать.

При этом инструкции должны быть конкретными.

Плохо:

Пиши качественный код.

Claude не получает из этого проверяемого правила.

Лучше:

Run `pnpm test` after changing application logic.

Плохо:

Соблюдай архитектуру проекта.

Лучше:

Business logic belongs in `src/services/`.
API handlers should not access the database directly.

Чем конкретнее правило, тем проще модели его применить. В документации Anthropic прямо рекомендуется использовать короткие, структурированные и проверяемые инструкции.

Почему CLAUDE.md не должен быть огромным

Одна из самых распространённых ошибок — попытаться поместить в CLAUDE.md всю документацию проекта.

README, описание каждой папки, список всех библиотек, историю архитектуры, инструкции по деплою — кажется, что чем больше информации получит Claude, тем лучше.

На практике это не так.

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

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

Поэтому CLAUDE.md лучше воспринимать не как энциклопедию проекта, а как короткую памятку:

что Claude должен помнить почти всегда и чего он не сможет надёжно определить самостоятельно.

Несколько уровней инструкций: зачем они нужны

Когда проект небольшой, одного CLAUDE.md обычно достаточно. Но Claude Code поддерживает несколько уровней постоянных инструкций.

Например, пользовательский файл может содержать предпочтения конкретного разработчика, а проектный — стандарты всей команды.

CLAUDE.local.md удобен для локальных особенностей, которые не нужно отправлять остальным разработчикам. Anthropic рекомендует добавлять такой файл в .gitignore.

Важно понимать ещё одну деталь: найденные инструкции не обязательно «перезаписывают» друг друга. Claude Code может загрузить несколько файлов в один контекст. Поэтому противоречащие друг другу правила лучше устранять — иначе Claude может выбрать одно из них непредсказуемо.

Как проверить, что Claude действительно увидел CLAUDE.md

После создания файла полезно сразу проверить, загрузился ли он.

Для этого в Claude Code есть команда:

/context

В разделе Memory files отображаются файлы постоянного контекста, которые Claude получил в текущей сессии.

Это особенно полезно, если инструкция будто бы не работает.

Перед тем как переписывать формулировку, стоит проверить более простой вариант: а загрузился ли нужный файл вообще?

Официальная документация Anthropic рекомендует использовать /context именно для такой проверки.

Что такое auto memory

Теперь к второй части системы — автоматической памяти.

CLAUDE.md пишете вы.

Auto memory пишет сам Claude.

Во время работы Claude Code может решить, что определённая информация пригодится в следующих сессиях, и сохранить её.

В актуальной документации выделяются четыре типа таких заметок:

• user — роль пользователя, его опыт и рабочие предпочтения;

• feedback — исправления пользователя и подтверждённые подходы;

• project — решения и текущий контекст проекта, которые нельзя просто получить из кода или истории Git;

• reference — указания, где искать внешнюю информацию, например issue tracker или dashboard.

Claude специально старается не сохранять в auto memory то, что уже можно определить из кодовой базы или что прописано в CLAUDE.md. И он не обязан добавлять новое воспоминание после каждой сессии — система сама оценивает, пригодится ли информация в будущем.

Простой пример

Можно сказать Claude:

Remember that integration tests require a local Redis instance.

Если Claude считает это полезным для будущей работы, информация может попасть в auto memory.

Но правило:

Always run `pnpm lint` before completing a task.

лучше хранить в CLAUDE.md, если оно действительно является стандартом проекта.

Получается простое разделение:

официальные правила команды → CLAUDE.md;

накопленный рабочий контекст → auto memory.

Где хранится память Claude Code

Для каждого проекта Claude Code создаёт отдельный каталог:

~/.claude/projects/<project>/memory/

В нём находится индекс MEMORY.md и отдельные файлы с более подробными заметками.

Пример:

memory/
├── MEMORY.md
├── user_role.md
├── feedback_testing.md
└── ...

MEMORY.md работает как индекс — помогает Claude понять, какие воспоминания существуют и где лежат подробности.

При начале разговора Claude Code загружает первые 200 строк или 25 КБ MEMORY.md — в зависимости от того, какой предел будет достигнут раньше. Детальные тематические файлы не загружаются все сразу: Claude читает их по мере необходимости.

Есть важный нюанс: auto memory хранится локально на компьютере. Она не синхронизируется автоматически между разными машинами или облачными окружениями. Worktree и подкаталоги одного Git-репозитория при этом используют общую память репозитория.

Как посмотреть, что Claude запомнил

Для управления памятью используется:

/memory

Auto memory включена по умолчанию. Через /memory можно посмотреть доступные файлы памяти и изменить настройку автоматического запоминания.

Сами записи хранятся как обычные Markdown-файлы. Поэтому память можно просматривать и редактировать, а не воспринимать её как закрытую внутреннюю базу модели.

При необходимости auto memory можно отключить для проекта:

{
  "autoMemoryEnabled": false
}

или глобально через переменную окружения:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Когда одного CLAUDE.md становится мало

Допустим, у проекта есть backend, frontend, API и большой набор тестов. Для каждой части нужны разные инструкции.

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

Для таких случаев Claude Code поддерживает каталог:

.claude/rules/

Например:

.claude/
├── CLAUDE.md
└── rules/
    ├── api.md
    ├── frontend.md
    └── testing.md

Каждый файл содержит отдельную группу правил.

Кроме того, правило можно привязать только к определённым файлам с помощью поля paths:

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

# API rules

- Validate all external input.
- Use the standard error response.
- Add documentation for public endpoints.

Так инструкция применяется, когда Claude работает с подходящими файлами, а не постоянно занимает место в основном контексте.

Для первого знакомства с Claude Code усложнять конфигурацию не нужно. Начинать разумнее с одного небольшого CLAUDE.md и переносить правила в .claude/rules/ только тогда, когда основной файл действительно начинает разрастаться.

CLAUDE.md — это инструкция, а не система безопасности

Это различие особенно важно.

Предположим, вы напишете:

Never read .env files.

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

Anthropic прямо разделяет поведенческие инструкции и enforced settings: CLAUDE.md влияет на поведение модели, а технические ограничения применяются клиентом независимо от решения Claude.

Если чтение .env действительно необходимо заблокировать, для этого существуют permissions:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Такой пример используется и в официальной документации Claude Code.

Полезно запомнить разделение:

Что такое hooks

Hooks нужны, когда определённая проверка должна выполняться не потому, что Claude «попросили помнить о ней», а автоматически при конкретном событии.

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

Обычному пользователю hooks не нужны для первоначальной настройки.

Достаточно понимать разницу:

CLAUDE.md говорит модели, как следует работать.

Hook способен вмешаться в момент выполнения действия.

Для чего нужен sandbox

Sandbox решает ещё одну задачу: ограничивает файловый и сетевой доступ команд, запускаемых через shell.

Вместо того чтобы подтверждать каждую команду отдельно, можно определить границы, внутри которых Bash-команды смогут работать. Эти ограничения применяются средствами операционной системы.

Встроенный sandbox Claude Code сейчас работает на macOS, Linux и WSL2. Native Windows напрямую не поддерживается — для Windows Anthropic указывает WSL2.

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

А что насчёт AGENTS.md

В современных версиях Claude Code появилась прямая поддержка AGENTS.md.

Если в репозитории уже используется такой файл для других coding agents и нет проектного CLAUDE.md, Claude Code может использовать AGENTS.md как инструкции проекта.

Если же в рабочей директории или выше уже присутствует проектный CLAUDE.md или CLAUDE.local.md, по умолчанию Claude читает именно файлы CLAUDE.md. Поведение можно изменить в настройках Project instructions. Прямая поддержка AGENTS.md требует Claude Code версии 2.1.277 или новее.

Для обычного проекта, где уже настроен CLAUDE.md, переходить на AGENTS.md специально не требуется.

Пять ошибок, которые снижают пользу CLAUDE.md

Первая — слишком общие инструкции. «Пиши хороший код» значительно слабее, чем конкретное требование запустить определённый тест или сохранить бизнес-логику в заданном каталоге.

Вторая — слишком большой файл. CLAUDE.md не должен заменять всю документацию проекта. Anthropic рекомендует стремиться к объёму менее 200 строк.

Третья — противоречащие правила. Если разные файлы требуют противоположных действий, Claude может выбрать любое из них.

Четвёртая — попытка заменить безопасность текстовой инструкцией. Для реального запрета действий нужны permissions, hooks или sandbox.

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

Быстрая настройка CLAUDE.md за несколько шагов

Для первого запуска не нужна сложная система.

Создайте файл:

CLAUDE.md

или выполните:

/init

Оставьте в нём только основные команды, несколько архитектурных правил и обязательные действия:

# Commands

- Install dependencies with `pnpm install`.
- Run tests with `pnpm test`.

# Architecture

- API code lives in `src/api/`.
- Business logic lives in `src/services/`.

# Rules

- Do not edit generated files.
- Run relevant tests after code changes.

Затем выполните:

/context

и проверьте, появился ли CLAUDE.md среди Memory files.

После нескольких реальных рабочих сессий откройте:

/memory

и посмотрите, что Claude сохранил автоматически.

На этом базовую настройку можно считать законченной.

Не нужно заранее создавать десятки rules, hooks и сложную систему permissions. Их стоит добавлять тогда, когда возникает конкретная проблема, которую они действительно решают.

Вывод

Хорошо настроенный Claude Code не требует огромной инструкции на десятки страниц.

Рабочая схема намного проще.

CLAUDE.md хранит правила, которые Claude должен учитывать постоянно. Auto memory помогает переносить полезный рабочий контекст между сессиями. /context показывает, какие инструкции действительно загрузились. .claude/rules/ позволяет не раздувать основной файл в крупных проектах. А permissions, hooks и sandbox добавляют технический контроль там, где одной инструкции модели уже недостаточно.

Главный принцип можно сформулировать совсем просто:

если вы второй раз объясняете Claude одно и то же, стоит подумать, не пора ли перенести это в постоянный контекст.

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