Как правильно подключать документацию в Claude Code: особенности импорта и работы с путями

Настройка контекста в Claude Code требует строгого соблюдения синтаксиса, поскольку ошибки в путях или структуре импорта могут приводить к тому, что файлы не загружаются в сессию без каких-либо предупреждений. Особенности работы с файлом CLAUDE.md определяют, какая именно информация будет доступна искусственному интеллекту на старте работы.

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

Почему прямой импорт в CLAUDE.md через @ может не загрузить файл

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

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

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

Обычный путь в CLAUDE.md и принятие решений о чтении

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

Подобный подход позволяет эффективно экономить доступное пространство контекста. Тяжелые справочные материалы и регламенты рекомендуется снабжать текстовыми пояснениями и условиями вроде «читай, когда…». Пока конкретная задача не требует обращения к документу, он не занимает место в оперативной памяти ИИ.

Что получают субагенты Claude Code при старте

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

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

Особенности работы со скиллами и выбор места для документов

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

Выбор способа подключения документа зависит от частоты его использования:

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