Память Claude Code: CLAUDE.md, @импорты и правила для папок

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

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

Импорт @path: порядок, но не экономия

Строка с @ и путём подгружает другой файл вместе с CLAUDE.md:

# Проект linkcheck

@AGENTS.md

- Команды npm: @package.json
- Архитектура: @docs/architecture.md

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

Две мелочи, на которых спотыкаются чаще всего:

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

Если импортировать файл вне рабочей папки, например @~/notes.md, при первом использовании в проекте Claude Code попросит одобрения. Откажешь — импорт так и останется выключенным.

Ловушка с AGENTS.md

Многие проекты уже держат инструкции для ИИ-агентов в AGENTS.md. Тут важная деталь: если в проекте есть CLAUDE.md, Claude читает его вместо AGENTS.md. Правила из AGENTS.md молча пропадают.

Лечится одной строкой. Поставь первой строкой CLAUDE.md импорт:

@AGENTS.md

Теперь правила живут в одном месте, и их видят и Claude, и другие агенты.

Правило для папки: загружается, только когда нужно

Вот что действительно экономит контекст. Правило — это Markdown-файл в папке .claude/rules/. Без заголовка paths оно загружается при старте, как обычный CLAUDE.md. А с заголовком — только когда Claude работает с подходящим файлом:

---
paths:
  - "test/**/*.js"
---

# Тесты

- Используй node:test и node:assert/strict, других библиотек не подключай.

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

И главная тонкость, из-за которой правило «не работает»: оно срабатывает, когда Claude читает подходящий файл своим инструментом Read. Если Claude посмотрел файл командой cat в оболочке, правило не подгрузится.

Что и когда попадает в контекст

Для личных инструкций к проекту, которые не нужны команде, есть CLAUDE.local.md: его создают руками и не коммитят.

Claude не слушается? Сначала проверь загрузку

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

Способ 1: /context all. Обычный /context может свернуть список, а all раскрывает его. В разделе Memory files видно, что загружено при старте. Правила с paths появятся там только после того, как Claude прочитает подходящий файл.

Способ 2: хук InstructionsLoaded. Он срабатывает при каждой загрузке CLAUDE.md, правила или импорта и сообщает причину. Положи его в отдельный файл, например .practice/loaded-hook.json:

{
  "hooks": {
    "InstructionsLoaded": [
      { "hooks": [ { "type": "command", "command": "jq -r '[.load_reason, .file_path] | @tsv' >> \"$CLAUDE_PROJECT_DIR/.practice/loaded.txt\"" } ] }
    ]
  }
}

Запусти сессию с ним: claude --settings .practice/loaded-hook.json. В логе у каждой строки будет причина: session_start — загружено при старте, include — подтянуто импортом, path_glob_match — правило сработало по шаблону.

Нет строки path_glob_match для твоего правила? Сравни шаблон с реальными файлами через git:

git ls-files ':(glob)src/api/**/*.js'

Пустой вывод — шаблон ни с чем не совпадает. Классика жанра: правило для source/** в проекте, где код лежит в src/.

Что не стоит класть в память

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

Частые вопросы

Потренируйся

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