CLAUDE.md: как написать файл инструкций для Claude Code + шаблон

CLAUDE.md - markdown-файл с постоянными инструкциями, который Claude Code загружает в контекст в начале каждой сессии. Документация прямо называет его статус: Claude воспринимает такие файлы «as context, not enforced configuration». Модель читает файл и обычно ему следует, но гарантии нет. Если действие нужно заблокировать при любом решении модели, нужен hook.

Из этой разницы вырастают многие проблемы с CLAUDE.md. Файл растёт, в нём множатся CRITICAL и ВАЖНО, а модель всё равно пропускает правила. Официальное руководство рекомендует держать каждый CLAUDE.md короче 200 строк. Исследователи из ETH Zurich и LogicStar.ai пришли к похожему выводу с другой стороны: контекст-файлы в среднем удорожают работу агента больше чем на 20% и в целом не повышают долю решённых задач.

Статья о том, как устроен CLAUDE.md в текущих версиях Claude Code: где лежат файлы, в каком порядке грузятся, как работают импорты и .claude/rules/, что писать в файл и что выносить в hooks и skills. В конце есть шаблон и чек-лист аудита. Общий для разных агентов формат AGENTS.md разобран отдельно в гайде по AGENTS.md. Примеры взяты из реальных файлов рабочего пространства автора (около 15 проектов) и обезличены, поведение AGENTS.md проверено на Claude Code 2.1.318.

Что такое CLAUDE.md и чем он отличается от auto memory

Контекст, а не конфигурация

У Claude Code два механизма, которые переносят знания между сессиями. CLAUDE.md пишет человек. Auto memory ведёт сам Claude по вашим поправкам. Оба грузятся в начале каждой сессии.

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

Страница best practices делит инструкции на два вида. Недетерминированные (промпт, CLAUDE.md, skills) читает модель и сама решает, применять ли их. Детерминированные (hooks, deny-правила, managed settings) исполняет Claude Code, и решение модели на них не влияет. CLAUDE.md всегда остаётся в первой группе.

Где лежит CLAUDE.md и как грузится

Четыре уровня

Таблица идёт в порядке загрузки, от широкого уровня к узкому: проектная инструкция окажется в контексте после пользовательской. Managed-файл раскатывают через MDM, Group Policy или Ansible. Вместо отдельного файла его текст можно положить в ключ claudeMd в managed-settings.json. Документация советует держать в управляемом CLAUDE.md поведенческие правила, а запреты на инструменты и пути оформлять через permissions.deny в managed settings.

Родительские и вложенные папки

Claude Code читает CLAUDE.md и CLAUDE.local.md из рабочей директории и из каждой директории выше. Если запустить его в foo/bar/, загрузятся foo/bar/CLAUDE.md, foo/CLAUDE.md и лежащие рядом с ними CLAUDE.local.md.

Три детали, которые часто путают:

1. Файлы склеиваются. Ни один не переопределяет другой. Порядок идёт от корня файловой системы к рабочей директории, поэтому инструкции ближе к месту запуска модель читает последними. Внутри одной директории CLAUDE.local.md стоит после CLAUDE.md. Если два файла противоречат друг другу, Claude, по документации, может выбрать любой вариант.
2. Подпапки грузятся по требованию. CLAUDE.md в подпапке ниже рабочей директории при старте не грузится. Claude Code подтягивает его, когда Claude читает, пишет или правит файл в этой подпапке, включая чтение через cat или head в Bash.
3. У файлов, которые грузятся по требованию, есть лимит на символы. При контекстном окне 200K это 40 000 символов на файл. Если вложенный CLAUDE.md или path-scoped правило длиннее, Claude получает только начало и пометку дочитать остальное через Read. Размер проверяется командой wc -m, лимит действует с v2.1.309.

Для заметок мейнтейнерам есть бесплатный способ: блочные HTML-комментарии <!-- ... --> вырезаются перед отправкой в контекст и токенов не тратят. Комментарии внутри блоков кода сохраняются.

Монорепо: claudeMdExcludes и --add-dir

В большом монорепо подгружаются чужие CLAUDE.md из родительских папок. Отключить их можно настройкой claudeMdExcludes, glob-шаблоны в ней сравниваются с абсолютными путями:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Документация советует класть эту настройку в .claude/settings.local.json, чтобы исключение осталось на вашей машине. Работает она на любом уровне settings, массивы из разных уровней объединяются. Managed CLAUDE.md исключить нельзя.

С --add-dir ситуация обратная: CLAUDE.md из дополнительных директорий по умолчанию не грузятся. Включает их переменная окружения:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Подробнее о раскладке файлов в больших репозиториях написано на странице Monorepos and large repos.

Импорты @path в CLAUDE.md

Синтаксис и ограничения

Строка @path/to/file в любом месте CLAUDE.md подставляет содержимое файла в контекст:

См. @README для обзора и @package.json для npm-команд.

# Дополнительно
- git workflow @docs/git-instructions.md

Правила разбора:

• относительный путь считается от файла, в котором стоит импорт, а не от рабочей директории;
• импортированные файлы могут импортировать другие, глубина ограничена четырьмя прыжками;
• внутри code span и блоков кода импорт не срабатывает, поэтому путь, который нужно упомянуть без загрузки, оборачивают в обратные кавычки (`@README`);
• пробел в пути экранируют обратным слэшем (@Design\ Docs/api.md), путь в кавычках не импортируется вообще;
• импорт из проектного файла, который ведёт за пределы рабочей директории, при первом появлении вызывает диалог одобрения. Если отказаться, импорты останутся выключенными. Файлы пользовательского уровня (~/.claude/CLAUDE.md, ~/.claude/rules/) импортируют без диалога, исключение составляют сессии Cowork.

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

Паттерн: тонкий глобальный файл

В рабочем пространстве автора глобальный ~/.claude/CLAUDE.md состоит из одной строки:

@shared-rules.md

Личные правила лежат в отдельном файле на 225 строк. Он версионируется сам по себе и импортируется во все проекты. Это импорт как способ организации: файл удобно редактировать и переносить между машинами. Контекст при этом платит за все 225 строк, и сам файл выходит за рекомендацию в 200.

Тот же приём пригодится для worktrees. Игнорируемый git’ом CLAUDE.local.md существует только в том worktree, где его создали. Чтобы личные инструкции были во всех копиях репозитория, документация предлагает импортировать файл из домашней директории: @~/.claude/my-project-instructions.md.

Что писать в CLAUDE.md и чего не писать

Что писать

Best practices оставляют в файле то, что Claude не выведет из кода сам:

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

В разделе «When to add to CLAUDE.md» есть четыре сигнала, что запись пора добавить. Claude повторил ту же ошибку. Code review поймал то, что Claude должен был знать о кодовой базе. Вы вводите в чат ту же поправку, что и в прошлой сессии. Новому человеку в команде понадобился бы тот же контекст.

Формулировки должны быть проверяемыми. «Отступ 2 пробела» лучше, чем «форматируй код правильно». «Запускай npm test перед коммитом» лучше, чем «тестируй изменения». «Обработчики API лежат в src/api/handlers/» лучше, чем «держи файлы в порядке».

Чего не писать

• Архитектуру и раскладку файлов, которые видны из кода. В таблице устаревших советов best practices этому отведена отдельная строка: Claude читает репозиторий сам.
• Общие пожелания без критерия проверки. «Никаких костылей» и «пиши эталонный код» модель не может проверить, а значит, не может и надёжно исполнить.
• Многошаговые процедуры. Релиз, runbook инцидента, порядок миграции данных оформляют как skill. Если Claude может запускать skill сам, в каждой сессии видны только его name и description, а полный текст грузится, когда задача его требует.
• Правила для одной части кода. Их место в .claude/rules/ с полем paths.
• Секреты. Схему работы с ними (откуда берутся, каким скриптом синхронизируются) описать можно, значения нельзя.

У этого подхода есть эмпирическая опора. В работе «Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?» (Gloaguen и соавторы, ETH Zurich и LogicStar.ai, arXiv 2602.11988) агентов прогнали на задачах SWE-bench с контекст-файлами, которые сгенерировала LLM, и на новой выборке issues из репозиториев, где такие файлы написали сами разработчики. Выводы из аннотации: контекст-файлы в целом не повышают долю решённых задач и увеличивают стоимость инференса в среднем больше чем на 20%. Инструкции агенты выполняют хорошо, обзоры репозитория им не помогают, а пользу файлы приносят там, где описывают нестандартные практики. Работа посвящена AGENTS.md, но формат тот же, и вывод совпадает с рекомендацией docs: писать только неочевидное.

Правило, причина, способ проверки

Самые устойчивые правила в файлах автора устроены одинаково: запрет, причина и ссылка на то, что проверит результат за человека. Пример (обезличенный):

## Deploy
- Не деплоить функции голой CLI-командой: она сбрасывает флаг
  проверки JWT, после чего ломается регистрация.
  Деплой только через `scripts/deploy.sh`: он после выкладки сверяет флаги.

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

С git-правилами работает тот же подход. В одном из проектов запрет git stash -u сопровождается описанием реального инцидента: опубликованные материалы ушли в untracked-часть stash и пропали из рабочего дерева. Рядом описан установленный git hook, который блокирует удаление такого stash. Текст объясняет причину, hook следит за исполнением.

Ещё два паттерна, которые хорошо себя показали:

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

Размер CLAUDE.md и цена в контексте

Рекомендация в 200 строк

Формулировка документации: «target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence». Это ориентир. Текст после 200-й строки никто не обрезает. На практике происходит следующее:

• если файл длиннее рекомендованного, Claude Code показывает предупреждение при старте и в /status;
• отдельное предупреждение появляется, когда файлы, каждый в пределах нормы, вместе превышают общий лимит на старте (каждый CLAUDE.md, файл правил и @-импорт считается отдельным файлом);
• файл больше 4 MiB Claude Code пропускает целиком;
• для файлов, которые грузятся по требованию, действует лимит в символах (40 000 при окне 200K), после которого модель видит только начало.

Цифры из рабочего пространства автора (wc, ноябрь 2026):

Сколько токенов занимает самый большой файл, автор не измерял, поэтому оценки здесь нет. Для своего файла это число показывает /context.

Как измерить: /context и /memory

/context all выводит раздел Memory files: какие CLAUDE.md, CLAUDE.local.md и AGENTS.md загружены при старте и сколько токенов занимает каждый. Если файла нет в списке, модель его не видит. В полноэкранном режиме /context без аргумента сворачивает этот список.

/memory перечисляет файлы памяти на уровне пользователя и проекта, открывает их в редакторе и включает или выключает auto memory.

Для чистки есть две встроенные проверки:

• /doctor предлагает сократить проектный CLAUDE.md. Он убирает то, что Claude выведет из кода (раскладку директорий, списки зависимостей, обзоры архитектуры), и оставляет подводные камни, обоснования и соглашения, которые отличаются от дефолтов;
• /doctor prompt-audit (с v2.1.283) ищет инструкции, написанные под старые модели, ссылки на несуществующие файлы и команды, противоречия между файлами. Он проверяет CLAUDE.md, CLAUDE.local.md, AGENTS.md, а также rules, skills, commands, subagents и output styles в .claude/ и ~/.claude/. Отчёт ничего не меняет, пока вы не попросите применить правки.

Почему компактный и релевантный контекст работает лучше большого, подробно разобрано в гайде по context engineering.

.claude/rules/ и path-scoped правила

Если правило нужно только в части кодовой базы, его выносят в .claude/rules/. Каждый .md-файл в этой папке отвечает за одну тему, поддиректории обходятся рекурсивно.

Правила без поля paths грузятся при старте с тем же приоритетом, что и .claude/CLAUDE.md. Правила с полем paths грузятся, когда Claude читает, пишет или правит подходящий файл:

---
paths:
  - "src/api/**/*.ts"
---
- Тела запросов валидировать zod-схемами из src/api/schemas/
- Каждому новому endpoint нужна запись в openapi.yaml, иначе падает CI

Из frontmatter файла правил Claude Code читает только paths, остальные поля молча игнорируются. Если YAML не парсится, frontmatter отбрасывается, и правило грузится как безусловное. Ошибку разбора показывает claude --debug.

Есть ещё два механизма. Личные правила для всех проектов кладут в ~/.claude/rules/, они грузятся раньше проектных. Общий набор правил можно подключить симлинком в .claude/rules/, но симлинк за пределы рабочей директории считается внешним импортом и требует одобрения.

Хорошие кандидаты на перенос в rules - разделы CLAUDE.md, которые начинаются словами «при работе с …»: при работе с миграциями, при правке мобильного клиента, при изменении edge-функций.

CLAUDE.md, hook или skill: что куда

Граница между CLAUDE.md и hook проходит по исключениям. Best practices разбирают три правила: «не читать .env», «запускать форматтер после правки», «не трогать папку migrations». Модель соблюдает их почти всегда. Если «почти» недостаточно, правило переносят в конфигурацию: форматтер в PostToolUse hook, запрет на migrations в PreToolUse hook, который завершается с кодом 2. А вот «Prefer named exports» остаётся в CLAUDE.md, потому что у такого правила много законных исключений.

Признак, что строку пора превращать в hook, документация описывает так: вы раз за разом усиливаете её эмфазой, а Claude всё равно её пропускает. Верно и обратное: hooks для того, что на деле просто предпочтение, лучше удалить и дать модели решать. События, коды выхода и примеры разобраны в гайде по hooks Claude Code, вынос исследования в отдельный контекст описан в статье о субагентах.

Шаблон CLAUDE.md

Шаблон ниже собран по принципу «только неочевидное». Значения в нём - пример для TypeScript-проекта, их нужно заменить своими. HTML-комментарии в контекст не попадают, так что подсказки для людей можно оставить прямо в файле.

# CLAUDE.md
<!-- Только то, что Claude не выведет из кода. Цель: меньше 200 строк. -->

## Commands
- Install: `pnpm install --frozen-lockfile`
- Один тест: `pnpm vitest run path/to/file.test.ts`
- Typecheck: `pnpm tsc --noEmit`
- Полная проверка перед PR: `pnpm lint && pnpm test && pnpm build`

## Constraints
- Не править сгенерированный клиент в `src/gen/`: его перезаписывает `pnpm codegen`.
- Изменение схемы БД делать только новой миграцией в `db/migrations/`.

## Conventions
- Ошибки бросать через хелперы из `src/lib/errors.ts`, не строками.
- `src/legacy/` живой, но его паттерны в новый код не переносить.

## Gotchas
- Интеграционным тестам нужен `DATABASE_URL`, см. `.env.example`.

## Ask before changing
- `infra/`, `.github/workflows/`, существующие файлы в `db/migrations/`

## Learned rules
<!-- Формат: правило / почему (что сломалось) / дата. Пересматривать раз в квартал. -->
- Деплой только через `scripts/deploy.sh`: голая CLI-команда сбрасывает
  флаги безопасности функции. (YYYY-MM)

## References
- Архитектурные решения: @docs/decisions/README.md

Шаблон CLAUDE.local.md для личных настроек в том же проекте (файл добавляют в .gitignore):

# CLAUDE.local.md: только для меня, не коммитится
- Тестовое окружение: http://localhost:3000, тестовый пользователь из `seed/users.ts`
- Отвечать по-русски, термины и код писать на английском
- Перед большими правками показывать план

Писать файл с нуля не обязательно. /init сгенерирует первую версию по кодовой базе, а при существующем CLAUDE.md предложит улучшения и не станет его перезаписывать. С переменной CLAUDE_CODE_NEW_INIT=1 команда работает интерактивно: спрашивает, что настроить (CLAUDE.md, skills, hooks), исследует код субагентом и показывает предложение до записи файлов. По формулировке best practices, дальше работа в основном сводится к удалению строк.

Короткий стартовый вариант с проверенными командами и ограничениями есть в полном гайде по Claude Code.

Как поддерживать CLAUDE.md

Learned Rules и аудит

Раздел «Learned Rules» в файлах автора пополняется только после реальной ошибки, с датой и коротким «почему». Пример из практики, обезличенный: определение «готово» для security-фикса из четырёх проверок (повтор атаки снаружи, CVE запущенной версии, все пути входа, детектор с бэктестом). Правило появилось после случая, когда «фикс» проверили только по конфигурации.

Без ухода такой раздел быстро разрастается. Рабочий ритм выглядит так:

1. После ошибки добавить правило в формате «что делать, почему, дата».
2. Раз в квартал прогнать /doctor prompt-audit и удалить правила, которые перекрыты hook’ом или линтером либо устарели вместе с моделью.
3. Правило, которое модель продолжает нарушать, перенести в hook.
4. Заметки для людей оставлять в HTML-комментариях, они не стоят токенов.

Типичные ошибки

Все примеры ниже нашлись в собственных файлах автора:

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

CLAUDE.md и AGENTS.md

В части руководств до сих пор написано, что Claude Code читает только CLAUDE.md. Для версий начиная с v2.1.277 это неверно: встроенный плагин читает AGENTS.md напрямую. Поведение по умолчанию:

Автор проверил четыре конфигурации на Claude Code 2.1.318 (claude -p, изолированные папки, в каждом файле уникальный маркер) и сверил ответ модели с выводом /context all. Результат совпал с документацией. Одну ловушку легко пропустить: личный CLAUDE.local.md в проекте на AGENTS.md отключает чтение AGENTS.md, и модель видит только локальный файл. Импорт @AGENTS.md дубля не создаёт, в Memory files оба файла показаны по одному разу.

Чтобы Claude читал оба файла, в /config выставляют Project instructions = claude-md-and-agents-md. В файле настроек это ключ pluginConfigs["cc-plugin-agents-md@builtin"].options.instructionFiles. Читается он только из ~/.claude/settings.json, файла --settings или managed settings, а в проектных settings игнорируется. Формат, совместимость с Codex, Cursor и Copilot и способы держать один файл для всех агентов разобраны в гайде по AGENTS.md. Если правила синхронизирует отдельный инструмент, пригодится разбор AgentSync: после появления прямого чтения AGENTS.md часть таких сценариев упростилась.

Ограничения и что не проверено

• Документация Claude Code меняется часто. Номера версий (v2.1.277, v2.1.283, v2.1.285, v2.1.309) и ID плагина cc-plugin-agents-md@builtin актуальны на ноябрь 2026. До v2.1.285 плагин назывался agents-md@builtin.
• Поведение после /compact описано по документации. Корневой CLAUDE.md после компакции перечитывается с диска и снова вставляется в сессию, вложенные CLAUDE.md и правила с paths подгружаются заново по требованию. Инструкции, которые звучали только в разговоре, теряются, поэтому их стоит переносить в файл. Живым /compact это не проверялось.
• Проверка AGENTS.md проведена в неинтерактивном режиме claude -p. Интерактивный /config, --add-dir, симлинк CLAUDE.md на AGENTS.md и вложенные AGENTS.md не проверялись.
• Данные ETH Zurich взяты из аннотации статьи. Проценты по отдельным агентам и моделям здесь не приводятся.
• Как сокращение файла на 708 строк меняет качество работы, не измерялось. Таблица размеров показывает объём, а не эффект.

С чего начать

1. Запустите /context all и посмотрите, какие файлы на самом деле загружены и сколько они стоят.
2. Если CLAUDE.md нет, сгенерируйте его через /init и сразу удалите всё, что Claude прочитает из кода сам.
3. Поставьте в начало файла точные команды проверки: тесты, typecheck, линтер, запуск одного теста.
4. Прогоните /doctor prompt-audit и разберите противоречия и мёртвые ссылки.
5. Найдите правила с CRITICAL и ВАЖНО: каждое либо переформулируйте спокойно, либо перенесите в hook.
6. Разделы «при работе с …» вынесите в .claude/rules/ с paths, процедуры переведите в skills.

Если в проекте живут и CLAUDE.md, и AGENTS.md, продолжите гайдом по AGENTS.md: там разобрано, как оставить один источник правил. Более широкий обзор skills, субагентов и hooks есть в статье Claude Code Skills и Agents.