CLAUDE.md: как писать инструкции для Claude Code
Разбираю CLAUDE.md на демо-проекте: четыре уровня файлов, /init, импорты и правила с paths, AGENTS.md и проверку через /context all.
Кажется, что Claude Code сам поймёт проект по коду. На моём демо без инструкций он записал платёж на 1290 рублей числом 1290, хотя проект хранит деньги в копейках. CLAUDE.md — это файл с инструкциями для Claude Code, который агент читает в начале каждой сессии. В нём пишут то, что иначе пришлось бы объяснять заново: команды сборки и тестов, правила кода, запреты и неочевидные соглашения проекта. Проектный файл лежит в корне репозитория, личный в ~/.claude/CLAUDE.md, а хороший CLAUDE.md занимает меньше 200 строк.
Я веду такой файл во всех своих репозиториях с начала 2026 года, и за это время он заметно вырос в возможностях. Появились правила для отдельных папок, импорты, чтение AGENTS.md и встроенный аудит инструкций. Для этого гайда я собрал демо-проект и прогнал на нём Claude Code 2.1.319: каждый вывод ниже настоящий.
В статье разберём:
- зачем Claude Code нужен CLAUDE.md;
- где хранить инструкции и в каком порядке Claude их читает;
- как создать файл командой /init;
- что писать в CLAUDE.md;
- как разбить большой файл на импорты и правила;
- как Claude работает с AGENTS.md;
- как проверить, что Claude видит инструкции;
- какие ошибки портят файл инструкций.
Зачем Claude Code нужен CLAUDE.md
Каждая сессия Claude Code начинается с чистого контекста. Модель хорошо знает Python, FastAPI и Git, но не знает, как принято в твоём проекте: какой командой гонять тесты, где лежат хендлеры, в каких единицах хранить деньги. Часть этого она выведет из кода, остальное угадает.
CLAUDE.md закрывает именно угадывание. Документация Anthropic советует дописывать файл, когда Claude второй раз повторяет одну ошибку или когда ты в который раз печатаешь в чат одно и то же уточнение.
Я проверил разницу на одной задаче. Взял демо-API магазина в двух копиях: в первой есть файл инструкций и файл с соглашениями, где сказано, что деньги хранятся в копейках, во второй инструкций нет. Обеим копиям дал один промпт: «Добавь эндпоинт GET /payments/{payment_id}: платёж №7 на 1290 рублей пока храни в словаре. Добавь тест и закоммить».


С CLAUDE.md Claude записал сумму в копейках и сам сослался на соглашение проекта. Без инструкций та же задача дала сумму 1290, то есть рубли. Скриншот: терминал / matveev.tech
Код в обоих случаях рабочий, тесты на месте. Но во втором проекте сумма платежа в сто раз меньше той, что ждёт остальной код. Такую ошибку ревью легко пропускает, а инструкции убрали её одной строкой. Ещё деталь: с инструкциями Claude отдельно предупредил, что правила требуют прогнать make test перед коммитом, а я в промпте это запретил.
Где хранить инструкции и в каком порядке Claude их читает
У CLAUDE.md четыре уровня. Claude Code загружает их от широкого к узкому, и более конкретный файл оказывается в контексте позже.
| Уровень | Где лежит | Для чего |
|---|---|---|
| Политика организации | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux: /etc/claude-code/CLAUDE.md |
Общие правила компании, раскатывает IT |
| Пользователь | ~/.claude/CLAUDE.md |
Твои привычки для всех проектов: язык ответов, стиль |
| Проект | ./CLAUDE.md или ./.claude/CLAUDE.md |
Правила команды, лежат в Git |
| Локальный | ./CLAUDE.local.md |
Личное для этого проекта, добавь в .gitignore |
Файлы складываются, и ни один не отменяет другой. Если запустить Claude в foo/bar/, он прочитает и foo/CLAUDE.md, и foo/bar/CLAUDE.md, а CLAUDE.local.md в каждой папке встанет после CLAUDE.md. Файлы из вложенных папок Claude подгружает позже, когда начинает работать с файлом из такой папки.
В моём демо три файла: проектный, импортированный из него файл с соглашениями и личный CLAUDE.local.md. Команда /context all показывает их в разделе Memory files вместе с размером в токенах.

Где что держать, я решаю просто. Всё, что касается проекта и пригодится коллеге, идёт в проектный CLAUDE.md и коммитится. Личное, вроде адреса своей тестовой базы, уходит в CLAUDE.local.md. Привычки, которые не зависят от проекта, живут в ~/.claude/CLAUDE.md.
Как создать файл инструкций командой /init
Писать файл с нуля не нужно. Команда /init изучает репозиторий и собирает черновик файла: команды из Makefile и package.json, структуру проекта, заметные соглашения. Если файл уже есть, /init предлагает улучшения и ничего не перезаписывает.
Я запустил /init на демо-проекте. Claude прочитал Makefile, pyproject.toml, код и тесты и написал файл на 30 строк.

Черновик, честно говоря, вышел толковее, чем я ждал. /init сам вытащил формат ответа {"data", "error"} и loguru из кода, а ещё нашёл три проблемы, о которых я не просил. При этом он пишет по-английски и не знает того, чего нет в коде: про копейки в файле ни слова. Поэтому после /init я всегда дописываю руками то, что Claude сам не обнаружит.
Есть и второй режим. Если перед запуском выставить переменную CLAUDE_CODE_NEW_INIT=1, /init задаёт уточняющие вопросы и предлагает заодно настроить скиллы и хуки. Про переменные окружения у меня есть отдельный справочник.
Что писать в CLAUDE.md
Жёсткого формата нет, это обычный Markdown. Но Claude читает файл как контекст и не исполняет его так же строго, как настройки, поэтому от формулировок зависит, насколько точно он им следует. Anthropic даёт три правила: конкретность, краткость и отсутствие противоречий.

Вот файл моего демо-проекта целиком, на нём держатся все проверки в статье:
# Shop API
API маркетплейса: заказы и оплаты. Python 3.12, FastAPI, SQLAlchemy 2.0, PostgreSQL 16.
Подробные соглашения по эндпоинтам: @docs/api-conventions.md
<!-- Заметка для людей: раздел «Команды» сверять с Makefile после каждого релиза -->
## Команды
- Тесты: `make test`, один тест: `uv run pytest tests/test_orders.py::test_get_order -q`
- Линтер и формат: `make lint` (меняет файлы на месте)
- Миграции: `make migrate`
## Правила
- Каждый эндпоинт возвращает `{"data": ..., "error": ...}`, ошибка это код в snake_case
- Логи только через `loguru`, `print()` и `logging` не использовать
- Перед коммитом запусти `make test` и `make lint`
- Коммиты на русском
## Не трогать без явной просьбы
- `deploy/`: Dockerfile собирает прод
- `alembic/versions/`: старые миграции не редактировать, только новые
В нём пять блоков, и каждый закрывает свой тип вопросов.
Пара строк о проекте. Стек и назначение. Claude не держит весь код в голове и читает файлы по мере надобности, поэтому короткое описание помогает ему ориентироваться.
Команды. Тесты, линтер, сборка, запуск одного теста. Без этого блока Claude подбирает команду сам и иногда промахивается: pytest вместо uv run pytest, npm вместо pnpm.
Правила кода. Только то, что нельзя вывести из кода или что отличается от привычного по умолчанию. «Пиши чистый код» бесполезно, «отступ 2 пробела» работает.
Запреты с причиной. «Не трогать deploy/: Dockerfile собирает прод». С причиной Claude видит, где кончается правило, и не применяет его вслепую.
Ссылки на подробности. Длинные соглашения выносятся в отдельный файл и подключаются через @, об этом ниже.
Обрати внимание на HTML-комментарий в начале файла. Claude Code вырезает такие комментарии до того, как отправить файл в контекст, так что заметки для коллег токенов не тратят. Я попросил Claude процитировать это место, и он увидел там пустую строку.

Как разбить большой файл: импорты и правила .claude/rules
Когда файл подбирается к 200 строкам, его пора делить. Есть два способа, и работают они по-разному.
Импорт через @. Строка @docs/api-conventions.md подставляет файл целиком в контекст вместе с основным файлом. Путь считается от файла, где стоит импорт, вложенность до четырёх уровней. Это удобно для порядка, но контекст не экономит: импортированный файл грузится всегда.
Правила в .claude/rules/. Каждый файл в этой папке посвящён одной теме. Правило без настроек грузится в начале сессии, как основной файл. А правило с полем paths подключается, только когда Claude открывает подходящий файл. Вот правило для тестов из демо:
---
paths:
- "tests/**/*.py"
---
# Тесты
- Вызывай приложение через `TestClient(app)`, без поднятого сервера
- Сравнивай ответ целиком, вместе с `error`
- Моки только для внешних HTTP-сервисов
Я попросил Claude открыть тест и перечислить правила, которые он видит. Он нашёл все четыре источника и отдельно отметил, что tests.md подгрузился в момент чтения файла теста.

Личные правила для всех проектов можно сложить в ~/.claude/rules/. Если правило нужно не всегда, а под конкретную задачу (выкатка, релиз, миграция), лучше оформить его скиллом или плагином: скилл грузится, только когда он нужен.

Как Claude работает с AGENTS.md
AGENTS.md это общий формат инструкций для агентов кода, его читают Codex, Cursor и другие. С версии 2.1.277 Claude Code тоже читает AGENTS.md сам, без импортов и символических ссылок. Правило такое: если в рабочей папке и выше нет CLAUDE.md или CLAUDE.local.md, Claude берёт AGENTS.md.
Я проверил на копии проекта, где лежит только AGENTS.md на три строки. /context all показывает его среди файлов инструкций.

Если у тебя есть оба файла, по умолчанию Claude читает только CLAUDE.md. Чтобы держать один файл на все агенты, Anthropic предлагает импорт в первой строке этого файла, а ниже дописать то, что нужно только Claude:
@AGENTS.md
## Claude Code
Для изменений в src/billing/ сначала включай plan mode.
Вторая настройка живёт в /config, пункт Project instructions. Значение claude-md-and-agents-md заставляет Claude читать оба файла. Так устроен и этот блог: правила лежат в AGENTS.md, и их одинаково читают Claude Code и Codex.
Как проверить, что Claude видит инструкции
Три команды закрывают почти все вопросы.
/context all. Раздел Memory files показывает каждый загруженный файл с размером в токенах, как на кадрах выше. Если файла нет в списке, Claude его не видит. Исключение: файлы из вложенных папок здесь не появляются, они грузятся по требованию.
/memory. Список всех файлов инструкций с путями. Отсюда же любой файл открывается в редакторе, даже если его ещё нет: Claude создаст его при выборе.
/doctor prompt-audit. Появился в версии 2.1.283. Claude проверяет CLAUDE.md, AGENTS.md, правила и скиллы на устаревшие формулировки, противоречия и ссылки на несуществующие файлы, затем показывает отчёт и предлагает правки. Сами файлы он не меняет, пока ты не попросишь.
Аудит моего демо нашёл одну мелочь: в файле упомянута папка alembic/versions/, которой в репозитории нет. Он честно пометил находку низкой уверенностью: папка может появиться позже.

Ещё один способ подходит для отладки правил с paths: хук InstructionsLoaded пишет в лог, какой файл инструкций загрузился и почему. Как устроены хуки, я разбирал в гайде по хукам Claude Code.
Какие ошибки портят файл инструкций
Большинство этих проблем я встречал у себя. Вот что чаще всего ломает работу.
Слишком длинный файл. Весь CLAUDE.md из корня попадает в контекст в каждой сессии, а файл больше 4 МБ Claude Code пропускает целиком. Длинный файл не только ест токены, но и хуже соблюдается. Держи файл короче 200 строк, а частное выноси в правила с paths.
Противоречия между файлами. Если в ~/.claude/CLAUDE.md написано «отступ табами», а в проектном «два пробела», Claude может выбрать любое. Иерархии «проект важнее» здесь нет, файлы просто складываются. Раз в пару месяцев проверяй их через /doctor prompt-audit.
Правило, которое обязано сработать. Инструкции из этого файла Claude выполняет по возможности, гарантий тут нет. Если действие должно выполняться всегда, например форматирование после каждой правки, сделай хук. Если команду нужно запретить, используй permissions.deny в настройках разрешений.
Копия документации. Claude и так знает FastAPI и React. Пересказ документации фреймворка только раздувает файл. Пиши то, чем твой проект отличается от типичного.
Расчёт, что импорт экономит контекст. Файл через @ грузится вместе с основным, так что сокращает он только сам основной файл, но не контекст. Экономят правила с paths и скиллы.
CLAUDE.local.md в проекте на AGENTS.md. Личный CLAUDE.local.md считается за CLAUDE.md, и Claude перестаёт читать AGENTS.md. Если хочешь оба, переключи Project instructions на claude-md-and-agents-md.
Устаревшие инструкции. Поменял стек или команду сборки, обнови файл. Неверная инструкция вредит сильнее, чем её отсутствие: Claude будет уверенно запускать команду, которой больше нет.
Чем CLAUDE.md отличается от auto memory
В Claude Code две системы памяти. CLAUDE.md пишешь ты: это правила. Auto memory пишет сам Claude: твои поправки, предпочтения, контекст проекта, которого нет в коде. В начале 2026 года auto memory была экспериментом, теперь она включена по умолчанию в локальных сессиях.
Заметки Claude складывает в ~/.claude/projects/<проект>/memory/, а в каждую сессию попадают первые 200 строк или 25 КБ индекса MEMORY.md. Выключить можно в /memory или переменной CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Если попросить «запомни, что мы используем pnpm», Claude запишет это в auto memory. Чтобы правило попало в файл инструкций, так и скажи: «добавь в CLAUDE.md».
Я использую обе системы. Правила команды держу в файле инструкций, потому что они лежат в Git и их видят коллеги. Auto memory оставляю для того, что касается только меня. Подробнее о ней в разборе памяти Claude Code.

Частые вопросы о CLAUDE.md
Можно ли писать CLAUDE.md на русском?
Да. Весь CLAUDE.md в моём демо на русском, и Claude соблюдал каждое правило: копейки, формат ответа, проверки перед коммитом. Если хочешь, чтобы Claude всегда отвечал по-русски, добавь об этом отдельное правило в ~/.claude/CLAUDE.md.
Сохранится ли CLAUDE.md после /compact?
Сохранится. После сжатия контекста Claude Code заново читает CLAUDE.md из корня проекта с диска. CLAUDE.md из вложенных папок и правила с paths вернутся, когда Claude снова откроет подходящий файл. Пропадают только инструкции, которые ты давал в чате, поэтому важное лучше сразу записать в файл.
Что делать, если в монорепо подтягиваются чужие CLAUDE.md?
Добавь в .claude/settings.local.json настройку claudeMdExcludes со списком путей или glob-шаблонов. Claude перестанет загружать эти файлы, а исключение останется только на твоей машине. Политику организации так отключить нельзя. Остальные настройки разобраны в гайде по settings.json.
Как подключить CLAUDE.md из папки, добавленной через --add-dir?
По умолчанию Claude Code их не читает. Запусти его с переменной CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1, и он загрузит из дополнительных папок CLAUDE.md, CLAUDE.local.md и правила из .claude/rules/. Чтобы не писать её каждый раз, положи переменную в блок env настроек.
Главное о файле инструкций в 4 пунктах
- Файл инструкций даёт Claude Code то, чего нет в коде: команды, соглашения и запреты. На демо одна строка про копейки уберегла от суммы, ошибочной в сто раз.
- Файлы четырёх уровней складываются в один контекст, поэтому противоречия между ними Claude решает наугад.
- Держи каждый файл короче 200 строк. Частное выноси в
.claude/rules/сpaths, разовые процедуры в скиллы, а обязательные действия в хуки. - Начинай с
/init, проверяй загрузку через/context all, а раз в пару месяцев запускай/doctor prompt-audit.
Больше гайдов по настройке агента в разделе о Claude Code.
Читайте также
- Память Claude Code: auto memory, rules и CLAUDE.md: как Claude сам ведёт заметки и где они хранятся
- Разрешения в Claude Code: allow, deny и sandbox: что запретить жёстко, когда инструкции мало
- Как экономить токены в Cursor и Claude Code: почему длинный CLAUDE.md обходится дорого
- 10 воркфлоу Claude Code на каждый день: готовые сценарии, под которые стоит настроить CLAUDE.md