Память проекта по-взрослому

Ты уже умеешь писать CLAUDE.md. Но у большого проекта он быстро разрастается: команды, договорённости, правила для API, для тестов, для вёрстки. И каждая строка загружается в каждую сессию — даже когда ты правишь README.

Два инструмента помогают навести порядок: импорт и правило.

Импорт: @path

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

# Проект linkcheck

@AGENTS.md

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

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

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

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

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

AGENTS.md и CLAUDE.md

Если в проекте уже есть AGENTS.md для других агентов, учти: когда существует CLAUDE.md, Claude читает его вместо AGENTS.md. Чтобы не дублировать правила, поставь первой строкой CLAUDE.md импорт @AGENTS.md.

Правило: .claude/rules

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

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

# Тесты

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

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

Главная тонкость: правило с paths срабатывает, когда Claude читает совпадающий файл своим инструментом Read. Если он посмотрел файл командой cat в оболочке, правило не подгрузится. Поэтому при проверке так и проси: «прочитай test/config.test.js инструментом Read».

Что и когда загружается

Для личных инструкций к этому проекту есть CLAUDE.local.md. Его создают руками и не коммитят — как раз об этом урок про общий набор для команды.

Почему Claude не слушается

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

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

Второй способ — хук 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 — загружен при старте, как CLAUDE.md;
• include — подтянут импортом;
• path_glob_match — правило сработало по шаблону.

Если строки path_glob_match для твоего правила нет, сравни шаблон с настоящими файлами. Помогает git:

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

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

Правка посреди сессии

Claude Code читает CLAUDE.md проекта один раз, при старте. Поправил файл — правка дойдёт до сессии после /clear, /compact или перезапуска.

А чтобы найти инструкции, которые противоречат друг другу или ссылаются на удалённые файлы, запусти /doctor prompt-audit. Он предложит правки и ничего не изменит, пока ты не попросишь.