Скрижаль проекта

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

Слои и порядок загрузки

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

Проверить, что именно загрузилось, можно только одним способом: /context, раздел Memory files. Файл, которого там нет, агент не видит.

Размер решает

Ориентир — до 200 строк на файл. Длинный файл не просто занимает место: он топит важные правила в шуме, и агент начинает игнорировать половину. Файл тяжелее 4 МиБ пропускается целиком.

Правило отбора одно: для каждой строки спросите — «если это убрать, агент начнёт ошибаться?». Если нет, строка лишняя.

Если одну инструкцию агент упорно пропускает, пометьте эмфазой именно её. Если выделено полдесятка строк, не выделена ни одна.

Импорты и правила

Синтаксис @путь/к/файлу подключает другой файл. Относительные пути считаются от файла с импортом, глубина вложенности — до четырёх переходов. Импорт не уменьшает контекст: подключённое грузится при старте так же, как основной файл. Это инструмент организации, а не экономии. Чтобы упомянуть путь и не подключить его, оберните в обратные кавычки.

Экономию даёт другой механизм — каталог .claude/rules/. Правило с frontmatter paths: грузится, только когда агент работает с подходящими файлами:

---
paths:
  - "src/api/**/*.ts"
---
Все обработчики валидируют вход и используют единый формат ошибок.

Правило без paths грузится всегда и имеет тот же приоритет, что .claude/CLAUDE.md. Правила уровня пользователя (~/.claude/rules/) читаются раньше проектных, поэтому проектные важнее.

Если процедура многошаговая или нужна редко — это уже не правило, а скилл: он грузится по вызову, а не в каждую сессию (Устройство артефакта).

Автопамять — вторая система

Рядом живёт то, что пишет себе сам агент: заметки о ваших правках, предпочтениях и контексте проекта в ~/.claude/projects/<проект>/memory/. В каждую сессию грузится только индекс MEMORY.md — первые 200 строк или 25 КБ. Тематические файлы читаются по требованию. Смотреть и править — командой /memory, отключить — autoMemoryEnabled: false или переменной CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

После сжатия

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

В монорепозитории чужие CLAUDE.md из родительских каталогов отсекаются настройкой claudeMdExcludes; исключить управляемую политику организации нельзя (Развёртывание на гильдию).