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

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

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

Что уже умеем / что добавим

Вы уже запускали /init и знаете, что CLAUDE.md загружается автоматически при старте. Теперь копнём глубже: разберём все места, где эти файлы могут лежать, порядок их склейки, механизм вложенных файлов в подкаталогах, импорты через @path и приёмы, которые повышают шанс, что инструкции действительно сработают.

Что вы узнаете в рамках статьи

• Где могут лежать CLAUDE.md и в каком порядке они попадают в контекст
• Как работают вложенные CLAUDE.md в подкаталогах и чем они отличаются от корневого
• Как подключать дополнительные файлы через синтаксис @path
• Почему рекомендуется держать файл под 200 строк и что делать, когда он растёт
• Как проверить, что инструкции загрузились, и что делать, если агент их игнорирует

Ключевые термины

• CLAUDE.md — файл с постоянными инструкциями, который загружается в контекст в начале каждой сессии.
• CLAUDE.local.md — личный файл проектных инструкций, не предназначенный для коммита; добавляется в .gitignore.
• Импорт — подключение содержимого другого файла синтаксисом @path/to/file; импортированное разворачивается в контекст при старте.
• Вложенный CLAUDE.md — файл в подкаталоге, который подгружается не при старте, а когда агент обращается к файлам этого каталога.
• Managed policy — организационный уровень инструкций, разворачиваемый администраторами и не отключаемый пользовательскими настройками.
• /memory — команда просмотра и редактирования файлов памяти; /context показывает, что реально загрузилось в текущую сессию.

Где искать CLAUDE.md и в каком порядке они склеиваются

Файлов может быть несколько, и все они складываются в контекст, а не перебивают друг друга. Уровни, от самого широкого к самому узкому:

• Managed policy — организационный файл, разворачиваемый администраторами. На macOS это /Library/Application Support/ClaudeCode/CLAUDE.md, на Linux и WSL — /etc/claude-code/CLAUDE.md, на Windows — C:\Program Files\ClaudeCode\CLAUDE.md. Исключить его настройками нельзя.
• Пользовательский — ~/.claude/CLAUDE.md, ваши личные предпочтения во всех проектах.
• Проектный — ./CLAUDE.md или ./.claude/CLAUDE.md, командные договорённости, попадающие в репозиторий.
• Локальный — ./CLAUDE.local.md, ваши личные настройки под конкретный проект. Его добавляют в .gitignore.

Порядок склейки важен для понимания приоритетов. Файлы собираются от корня файловой системы вниз к рабочему каталогу, поэтому инструкции, лежащие ближе к точке запуска, читаются последними. Внутри одного каталога CLAUDE.local.md идёт после CLAUDE.md — ваши личные заметки оказываются последним, что агент прочитает на этом уровне.

Практический вывод: общие правила держите выше по дереву, специфичные — ниже.

Вложенные файлы в подкаталогах

Это тот механизм, который многие пропускают, а он заметно экономит контекст.

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

my-project/
├── CLAUDE.md              # загружается при старте
├── frontend/
│   └── CLAUDE.md          # подтянется при работе с frontend/
└── backend/
    └── CLAUDE.md          # подтянется при работе с backend/

Отсюда рабочая схема для монорепозитория: в корне — общие правила и команды сборки, в каталогах подпроектов — специфика конкретного стека. Пока вы работаете во фронтенде, инструкции бэкенда контекст не занимают.

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

Импорты и приёмы оформления

CLAUDE.md умеет подключать другие файлы синтаксисом @path/to/import. Пути допускаются относительные и абсолютные, причём относительные считаются от файла с импортом, а не от рабочего каталога. Импорты могут быть вложенными — до четырёх уровней.

Обзор проекта — @README, доступные команды — @package.json.

# Дополнительные инструкции
- работа с git: @docs/git-instructions.md

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

Если нужно упомянуть путь, не импортируя его, оберните в обратные кавычки: разбор импортов пропускает код-спаны и блоки кода.

Два приёма, которые стоит знать. Первый — блочные HTML-комментарии вырезаются перед подстановкой в контекст, так что заметки для людей не расходуют токены:

<!-- Заметка для команды: пересмотреть после миграции на v3 -->
- Используйте pnpm, не npm

Второй — акцент. Если одну инструкцию агент упорно пропускает, пометьте её словом IMPORTANT. Но именно одну: когда выделено всё, не выделено ничего.

Наконец, о репозиториях с AGENTS.md. Claude Code читает CLAUDE.md, а не AGENTS.md, поэтому создайте CLAUDE.md с импортом:

@AGENTS.md

## Claude Code
Используйте plan mode для изменений в `src/billing/`.

Как держать файл в работоспособном размере

Ориентир — до 200 строк. Это не жёсткий предел, а порог, за которым начинается заметная деградация: длинные файлы и контекст съедают, и следование инструкциям ухудшают.

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

Что стоит включать: команды, которые агент не угадает; правила стиля, отличающиеся от общепринятых; инструкции по тестам; договорённости о ветках и pull request; архитектурные решения именно вашего проекта; особенности окружения и неочевидные подводные камни.

Что не стоит: всё, что выводится из чтения кода; стандартные конвенции языка; подробную документацию API; часто меняющиеся сведения; пофайловые описания структуры; самоочевидные напутствия вроде «пишите чистый код».

Формулируйте проверяемо: «отступ в два пробела» работает лучше, чем «форматируйте код правильно»; «запускать npm test перед коммитом» — лучше, чем «тестируйте изменения».

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

Когда обрезать уже нечего, а материал нужен, растащите его по путям — этим займёмся в следующем уроке.

Частые ошибки

• Разросшийся файл. Самая частая проблема: инструкции добавляются, но никогда не удаляются. Когда важные правила тонут в неважных, агент начинает игнорировать половину. Регулярно вычищайте и относитесь к файлу как к коду: ревьюйте, когда что-то пошло не так.
• Противоречивые инструкции на разных уровнях. Если пользовательский и проектный файлы говорят разное об одном и том же, агент выберет вариант произвольно. Периодически сверяйте уровни между собой.
• Ожидание, что импорт сэкономит контекст. Разнести материал по файлам полезно для организации, но импортированное всё равно грузится при старте целиком. Экономия достигается другими средствами.
• Расчёт на CLAUDE.md как на гарантию. Содержимое файла — контекст, а не принудительная конфигурация. Если что-то должно происходить всегда и без исключений, это задача для другого механизма, а не для инструкции.

Наиболее частые вопросы

• Как убедиться, что файл загрузился? — Запустите /context и посмотрите список в разделе Memory files. Если файла там нет, агент его не видит.
• Чем /memory отличается от /context? — /memory показывает и открывает на редактирование файлы памяти по всем уровням, включая ещё не созданные. /context показывает, что реально загружено в текущей сессии.
• Куда класть личные заметки по проекту? — В CLAUDE.local.md рядом с проектным файлом, добавив его в .gitignore. Он загружается вместе с основным и читается после него.
• Что делать, если в монорепозитории цепляются чужие CLAUDE.md? — Используйте настройку claudeMdExcludes, чтобы исключить файлы по пути или шаблону. Организационный managed policy файл исключить нельзя.
• Переживает ли CLAUDE.md компактификацию? — Проектный файл из корня да: после /compact он перечитывается с диска. Вложенные файлы из подкаталогов вернутся, только когда агент снова обратится к их каталогу.

Итоги

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

Отдельно ценно, что теперь у вас есть диагностика: /context покажет, что загрузилось, а /memory даст всё это отредактировать. В следующем уроке решим задачу, к которой мы вплотную подошли: как быть, когда инструкций много, но нужны они не всегда. Ответ — правила в .claude/rules/ с привязкой к путям.