Если в пути импорта в CLAUDE.md есть пробел, Claude Code обрывает путь на нём, файл не грузится, а ошибки нет. Так у меня ни разу не загрузились два общих справочника, на которые ссылался CLAUDE.md. Я собрал пустой проект, разложил по файлам кодовые слова и спрашивал агента, какие слова он видит, запретив ему читать файлы. Вышло, что ссылка на документ в CLAUDE.md ещё не значит, что агент его прочтёт: у каждого способа ссылки свои правила загрузки.
Почему импорт в CLAUDE.md через @ молча не грузит файл
CLAUDE.md — файл с инструкциями, который Claude Code читает в начале каждой сессии. Строка @путь/к/файлу в нём — импорт. По документации импортированный файл целиком попадает в контекст на старте. Контекст — всё, что агент держит перед глазами. Импорт делит длинный файл на части, но места не экономит. Путь с пробелом требует обратного слэша перед каждым пробелом: без слэша путь обрывается на первом пробеле, в кавычках импорт не работает вовсе.
Первый опыт. В пустом git-репозитории лежит CLAUDE.md из семи строк:
# Тест
@Design Docs/a.md
@Design Docs/b.md
Кодовое слово В лежит в plain.md.В a.md записано «Кодовое слово А: ЛАЗУРЬ», в b.md — ОХРА, в plain.md — УМБРА. Запуск без инструментов чтения:
claude -p "Не открывай файлы. Назови кодовые слова А, Б, В из своего контекста; нет слова — пиши НЕТ."
--disallowedTools "Read,Bash,Grep,Glob"Ответ: А — НЕТ, Б — ОХРА, В — НЕТ. Импорт без слэша не сработал и ничего не сообщил, со слэшем файл дошёл. У меня пробел сидел в имени папки, и обе строки оборвались на нём. Если бы файлы грузились, они добавляли бы на каждом старте вчетверо больше текста, чем весь CLAUDE.md. Чинить слэшем я не стал: эти справочники нужны в редких задачах, и такая плата за каждый старт выше их пользы. Им место в обычной ссылке без @ с пометкой, когда её открывать.
Вторая ловушка, уже по документации, — путь вне рабочей папки: Claude Code считает такой файл внешним и при первой встрече просит одобрения, а после отказа больше не спрашивает.
Второй опыт проверяет глубину. Шесть файлов, в каждом своё слово, и каждый импортирует следующий:
for i in 1 2 3 4 5; do
printf 'Кодовое слово W%snn@f%s.mdn' "$i" "$((i+1))" > "f$i.md"
done
printf 'Кодовое слово W6n' > f6.md
printf '@f1.mdn' > CLAUDE.mdАгент назвал слова первых четырёх файлов, пятого и шестого не увидел. Уровни считаются так: сам CLAUDE.md не в счёт, f1 — первый уровень, f4 — четвёртый. Документация разрешает четыре уровня, и обрыв опять прошёл без ошибки. Что загрузилось в сессию, показывает команда /context.
Обычный путь в CLAUDE.md Claude открывает только по своему решению
Третий опыт. Тот же проект, чтение разрешено, вопрос про слово В. Ответ: «УМБРА. Прочитал из plain.md, на который указывает CLAUDE.md». Без права чтения было НЕТ. Документация говорит то же на примере AGENTS.md — файла инструкций, который читают и другие агенты для кода. Если CLAUDE.md словами велит прочитать AGENTS.md, Claude увидит этот файл, только если решит его открыть.
Поэтому рядом с путём я пишу условие, когда его открывать. Ядро моего CLAUDE.md чуть длиннее ориентира документации в 200 строк. Ещё пять файлов docs/, вдвое больше ядра по объёму, перечислены в таблице из двух колонок, вот две её строки (имена файлов условные):
|
Читай, когда |
Файл |
|
Запускаешь производство статьи |
docs/pipeline.md |
|
Нужна карта методологии |
docs/methodology.md |
Документ, нужный не в каждой сессии, выгоднее держать путём с условием. Пока задача его не требует, место в контексте свободно.
Что субагенты Claude Code получают при старте
Субагент — отдельный экземпляр Claude, которому главный агент отдаёт подзадачу. По документации он стартует с чистым контекстом: не видит историю разговора, вызванные скиллы (готовые инструкции под задачу) и файлы, которые главный агент уже прочитал. На старте у него есть тело файла самого агента, текст задания, CLAUDE.md всех уровней с импортами и скиллы из поля skills. Встроенные Explore и Plan CLAUDE.md не грузят.
Четвёртый опыт. Главный агент прочитал plain.md и запустил субагента general-purpose с заданием «не вызывай инструменты, назови слова Б и В». Ответ: Б — ОХРА, В — НЕТ, «содержимого этого файла в моём контексте нет». Импорт из CLAUDE.md дошёл, прочитанное родителем осталось у родителя.
Документ для одной задачи я называю в тексте задания, а путь, который нужен субагенту в каждой задаче, пишу в теле его файла. Постоянные знания идут в поле skills: полный текст каждого скилла из списка встраивается на старте. В описании агента пишется, когда его звать, — по описаниям главный агент и решает, кому отдать работу.
Скиллы для Claude Code грузят полный текст только при вызове
Скилл — папка с файлом SKILL.md, инструкция под конкретную задачу. По документации в контексте всегда лежит только описание скилла, полный текст грузится при вызове. Команды Claude Code устроены так же: файл .claude/commands/deploy.md и скилл .claude/skills/deploy/SKILL.md дают одну и ту же команду /deploy. Длинный справочник поэтому выгодно держать в скилле: по документации, пока скилл не вызвали, его текст почти ничего не стоит контексту.
В какой файл класть документ при настройке Claude Code
-
Нужное в каждой сессии — в ядро CLAUDE.md, держа его около 200 строк.
-
Тяжёлый файл, нужный всегда, — импортом через
@. Пробел в пути экранировать обратным слэшем, кавычки не ставить, цепочку держать не глубже четырёх уровней, после правки проверить/context. -
Справочник на отдельный случай — обычным путём с условием «читай, когда…».
-
Документ для субагента — в текст задания или в тело его файла (путь там тоже работает как обычный путь: откроет, если решит), постоянные знания — в поле
skills. -
Длинную процедуру — в скилл или команду, в ядре оставить строку о вызове.
-
Правило, которое нельзя нарушить, — в хук PreToolUse. Хук — скрипт, который Claude Code запускает перед вызовом инструмента, и он может вызов заблокировать. По документации CLAUDE.md для Claude — контекст, а не принудительная настройка. У меня на хуке висит около двух десятков правил: например, коммит не пройдёт, если в изменениях есть строка, похожая на живой ключ API.
Всё это я проверял на версии 2.1.288 и только в режиме claude -p: в диалоге может выйти иначе, а правила загрузки в документации помечены версиями, с которых они действуют, — опыты стоит повторить на своей. Третий и четвёртый опыты я прогнал по одному разу. Вопрос про кодовое слово прямо толкал агента открыть файл. Совет писать условие «читай, когда…» — моя практика, опытом я его не проверял.
Автор: sburyi
