Import-синтаксис @path

Почему это важно именно вам

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

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

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

Что это такое

Синтаксис @путь/к/файлу.md внутри CLAUDE.md — это директива включения. Когда Claude Code читает ваш CLAUDE.md и встречает строку вида @docs/style.md, он читает этот файл и подставляет его содержимое прямо на это место. С точки зрения Claude — это один большой документ. С вашей точки зрения — это несколько отдельных файлов, каждый из которых можно редактировать независимо.

Аналогия из бизнеса: оглавление в корпоративном регламенте. Есть главный документ, который описывает структуру. Каждая глава — в отдельном приложении. Когда юрист обновляет правила закупок, он открывает только приложение №3. Главный документ не трогается. Все ссылки работают как прежде.

Или ещё ближе к жизни: папка «Шаблоны» на рабочем столе. В каждом шаблоне — своя задача. Нужно написать договор — берёте шаблон договора. Нужно написать письмо партнёру — берёте шаблон письма. Никто не хранит все шаблоны в одном Word-документе на 80 страниц.

Ключевая идея

@path работает во время чтения файла Claude Code, а не во время его выполнения. Это просто подстановка текста. Никакой магии, никаких дополнительных зависимостей. Файл должен существовать — тогда всё работает.

Пути могут быть относительными (от расположения CLAUDE.md) или абсолютными (от корня системы). Расположение CLAUDE.md определяет базовую точку для относительных путей. Если ваш CLAUDE.md лежит в ~/Документы/, то @templates/report.md будет искать файл по пути ~/Документы/templates/report.md.

Как работает на практике

Шаг 1. Аудит вашего текущего CLAUDE.md

Прежде чем разбивать, нужно понять, что в нём есть. Откройте файл и пройдитесь по нему с простым вопросом: «Как часто эта секция меняется?»

Типичные секции в CLAUDE.md директора и их динамика:

Правила стиля письма и тона — меняются редко, раз в несколько месяцев
Форматы отчётов — меняются редко, иногда под конкретный запрос руководства
Структура договоров — почти не меняется, разве что появился новый тип
Контекст текущих проектов — меняется регулярно, иногда еженедельно
Список контрагентов и сокращений — пополняется постоянно
Правила работы с бюджетом — меняются при смене цикла

Секции с разной динамикой — кандидаты на разные файлы. Статичные правила стиля не должны лежать рядом с постоянно обновляемым контекстом проектов.

Шаг 2. Создание структуры папок

Создайте папку рядом с вашим CLAUDE.md. Например:

~/Документы/Работа/
├── CLAUDE.md           ← главный файл
└── claude_modules/     ← папка с модулями
    ├── style.md        ← правила стиля и тона
    ├── reports.md      ← форматы отчётов
    ├── contracts.md    ← шаблоны договоров
    ├── projects.md     ← контекст текущих проектов
    └── contacts.md     ← контрагенты и сокращения

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

Где хранить модули

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

Шаг 3. Разбиваем файл

Возьмём пример. До разбивки CLAUDE.md выглядит так:

# Мой контекст для Claude

## Стиль коммуникации
Всегда пиши в деловом стиле, без панибратства.
Обращение к партнёрам — «Уважаемый [Имя Отчество]».
Письма заканчивай предложением следующего шага.
Не используй слова «уникальный», «эффективный», «инновационный».

## Форматы отчётов
Еженедельный отчёт: сначала KPI-блок, потом выполненные задачи,
потом задачи на следующую неделю, потом риски.
Шрифт заголовков — полужирный. Числа — с пробелом-разделителем тысяч.
Отчёт для совета директоров: только три пункта — итоги, проблемы, решения.

## Текущие проекты
Проект Альфа — запуск нового продукта, дедлайн 30 июня.
Ответственный — Иванов И.И.
Проект Бета — реорганизация колл-центра, дедлайн Q3.
Ответственный — Петрова А.В.

После разбивки каждая секция переходит в свой файл:

Файл claude_modules/style.md:

## Стиль коммуникации

Всегда пиши в деловом стиле, без панибратства.
Обращение к партнёрам — «Уважаемый [Имя Отчество]».
Письма заканчивай предложением следующего шага.
Не используй слова «уникальный», «эффективный», «инновационный».

Файл claude_modules/reports.md:

## Форматы отчётов

Еженедельный отчёт: сначала KPI-блок, потом выполненные задачи,
потом задачи на следующую неделю, потом риски.
Шрифт заголовков — полужирный. Числа — с пробелом-разделителем тысяч.
Отчёт для совета директоров: только три пункта — итоги, проблемы, решения.

Файл claude_modules/projects.md:

## Текущие проекты

Проект Альфа — запуск нового продукта, дедлайн 30 июня.
Ответственный — Иванов И.И.

Проект Бета — реорганизация колл-центра, дедлайн Q3.
Ответственный — Петрова А.В.

Шаг 4. Обновляем CLAUDE.md

Главный файл теперь выглядит так:

# Мой контекст для Claude

@claude_modules/style.md
@claude_modules/reports.md
@claude_modules/projects.md

Три строки вместо сорока. И каждая строка говорит сама за себя.

Как это читает Claude

Когда Claude Code запускается в этой папке, он открывает CLAUDE.md, видит директивы @, читает каждый файл по указанному пути и склеивает содержимое в единый контекст. Для дальнейшей работы это ровно тот же результат, как если бы всё было написано в одном файле. Разница только для вас — в удобстве управления.

Шаг 5. Разные файлы для разных задач

Один из мощных сценариев — иметь несколько вариантов одного модуля под разные задачи. Например:

claude_modules/
├── style.md              ← стиль по умолчанию
├── style_formal.md       ← максимально официальный тон (суд, ФНС)
├── style_brief.md        ← очень коротко, для мессенджеров
├── reports.md            ← отчёты по умолчанию
└── reports_board.md      ← отчёты для совета директоров

В CLAUDE.md подключаете тот вариант, который актуален прямо сейчас:

@claude_modules/style_formal.md
@claude_modules/reports_board.md

Подготовка к совету директоров? Меняете одну строку в CLAUDE.md. Задача закрыта, возвращаете обычные стили. Никакого копирования, никакого «что там было до меня».

Шаг 6. Вложенные импорты

Импорты работают и внутри самих модулей. Файл reports.md может импортировать общие определения из файла с терминологией:

## Форматы отчётов

@claude_modules/terminology.md

Еженедельный отчёт строится так: ...

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

Глубина вложенности

Теоретически импорты могут быть многоуровневыми, но на практике лучше держать структуру плоской: CLAUDE.md → модули первого уровня → опционально один уровень вложенности. Глубокие деревья быстро теряют наглядность. Если чувствуете, что структура усложняется — это сигнал сделать её проще.

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

Ошибка 1. Неверный путь к файлу

Написали @modules/style.md, но папка называется claude_modules. Claude Code тихо пропустит директиву или выдаст ошибку. Перед тем как полагаться на импорт, проверьте: файл существует, путь правильный, расширение .md стоит.

Как исправить: запустите ls claude_modules/ и убедитесь, что имена файлов совпадают с тем, что написано в директивах.

Ошибка 2. Дублирование контента в разных модулях

Вы написали правила про деловой стиль и в style.md, и в contracts.md, потому что «там тоже важно». Через месяц обновили в одном файле, забыли в другом. Claude получает противоречивые инструкции.

Как исправить: правило живёт ровно в одном месте. Если оно нужно в нескольких модулях — вынесите в общий файл и импортируйте его.

Ошибка 3. Модуль вырос до размеров исходного CLAUDE.md

Начали с небольшого projects.md, за три месяца он разросся до 300 строк. Проблема вернулась, просто переехала в другой файл.

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

Ошибка 4. Импортировать всё подряд при каждом запуске

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

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

Бонус: шаблон структуры для директора

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

~/Документы/Работа/
├── CLAUDE.md
└── claude_modules/
    ├── style.md          ← тон, стиль, обращения, запретные слова
    ├── reports.md        ← форматы всех типов отчётов
    ├── contracts.md      ← типовые условия, реквизиты, структура
    ├── projects.md       ← активные проекты: статус, ответственные, дедлайны
    ├── contacts.md       ← контрагенты, сокращения, должности в компании
    └── budget.md         ← правила работы с бюджетами, форматы сумм

Начните с двух-трёх модулей, которые используете чаще всего. Остальные добавляйте по мере необходимости, не наперёд.

Ревизия раз в квартал

Договоритесь сами с собой: раз в квартал открываете папку claude_modules/ и проходитесь по каждому файлу. Актуально? Не устарело? Не задублировано в другом файле? Десять минут на ревизию экономят часы недоразумений. Особенно критично для projects.md — там информация устаревает быстро.

Когда нужно / когда нет

Import-синтаксис нужен, когда ваш CLAUDE.md превысил 50-60 строк и вы уже не можете с первого взгляда найти нужную секцию. Это сигнал: пора разбивать.

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

Он нужен, когда вы хотите переиспользовать часть правил в разных проектах. Общий style.md лежит в одном месте, а разные CLAUDE.md в разных проектах его импортируют. Изменили стиль один раз — изменение подхватили все проекты.

Import-синтаксис не нужен, пока CLAUDE.md небольшой. Если он умещается на один экран — разбивать его на модули преждевременная оптимизация. Добавляет сложность там, где ещё нет проблемы.

Он не нужен для разовых задач. Если вы добавляете контекст специально под один запрос — проще передать файл через @имя_файла.txt прямо в чате, чем добавлять его в постоянный контекст через CLAUDE.md.

Когда файл не найден

Если указанный в директиве файл не существует, Claude Code сообщит об ошибке при загрузке контекста. Это предсказуемое поведение — лучше явная ошибка, чем тихое игнорирование. Держите структуру папок аккуратной и синхронизированной с директивами в CLAUDE.md.

Связь с другими уроками

День 11 (CLAUDE.md — структура и уровни) — там разобрана базовая логика CLAUDE.md: что в него класть, как Claude Code его читает. Import-синтаксис — следующий шаг после понимания основ.
День 12 (четыре уровня CLAUDE.md) — глобальный, проектный, папочный и пользовательский уровни. Import-синтаксис работает на любом из них, поэтому понимание уровней помогает правильно выбрать, где держать модули.
День 21 (субагенты и специализация) — там разберём, как разные субагенты могут импортировать разные наборы правил, создавая специализированные роли из одного набора модулей.

Задание на сегодня

Возьмите ваш текущий CLAUDE.md и выделите из него одну секцию в отдельный файл.

Конкретные шаги:

Откройте CLAUDE.md и выберите секцию, которая логически самостоятельна — например, правила стиля или форматы отчётов.
Создайте папку claude_modules/ рядом с CLAUDE.md.
Создайте файл внутри — например, claude_modules/style.md. Скопируйте туда выбранную секцию.
В CLAUDE.md на месте этой секции напишите одну строку: @claude_modules/style.md.
Запустите Claude Code в этой папке и дайте простой запрос, который задействует правила из вынесенного модуля. Убедитесь, что правила применяются.

Критерий выполнено: Claude Code применил правила из внешнего файла так же, как раньше применял их из CLAUDE.md напрямую. Видите в ответе влияние вашего модуля — задание выполнено.

Если CLAUDE.md у вас пока нет или он минимальный — создайте его с одной секцией «Стиль» и сразу разместите её в модуле. Это правильный способ начать.

Резюме

@путь/к/файлу.md внутри CLAUDE.md подставляет содержимое файла прямо на это место при загрузке контекста
Разбивка на модули решает проблему роста: большой CLAUDE.md становится оглавлением, каждая секция — отдельным файлом
Разные модули можно включать и выключать под конкретную задачу — это снижает шум и повышает точность ответов
Путь в директиве — относительный от расположения CLAUDE.md или абсолютный; файл должен существовать
Начинайте разбивать, когда CLAUDE.md перевалил за 50-60 строк и навигация стала неудобной — раньше не нужно