Claude CodeГайд

CLAUDE.md: как писать инструкции для Claude Code

Разбираю CLAUDE.md на демо-проекте: четыре уровня файлов, /init, импорты и правила с paths, AGENTS.md и проверку через /context all.

CLAUDE.md: как писать инструкции для Claude Code

Кажется, что 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 отдельно предупредил, что правила требуют прогнать 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 вместе с размером в токенах.

Терминал: таблица Memory files с CLAUDE.md, api-conventions.md и CLAUDE.local.md
Claude видит три файла инструкций, все вместе занимают около 460 токенов. Пользовательский CLAUDE.md я отключил флагом, чтобы кадр был чистым. Скриншот: терминал / matveev.tech

Где что держать, я решаю просто. Всё, что касается проекта и пригодится коллеге, идёт в проектный CLAUDE.md и коммитится. Личное, вроде адреса своей тестовой базы, уходит в CLAUDE.local.md. Привычки, которые не зависят от проекта, живут в ~/.claude/CLAUDE.md.

Как создать файл инструкций командой /init

Писать файл с нуля не нужно. Команда /init изучает репозиторий и собирает черновик файла: команды из Makefile и package.json, структуру проекта, заметные соглашения. Если файл уже есть, /init предлагает улучшения и ничего не перезаписывает.

Я запустил /init на демо-проекте. Claude прочитал Makefile, pyproject.toml, код и тесты и написал файл на 30 строк.

Терминал: CLAUDE.md, который сгенерировала команда /init, с разделами Project, Commands, Architecture и gotchas
/init нашёл команды, формат ответа и логгер, а заодно заметил, что миграций и uv.lock в репозитории нет. Скриншот: терминал / matveev.tech

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

Есть и второй режим. Если перед запуском выставить переменную CLAUDE_CODE_NEW_INIT=1, /init задаёт уточняющие вопросы и предлагает заодно настроить скиллы и хуки. Про переменные окружения у меня есть отдельный справочник.

Что писать в CLAUDE.md

Жёсткого формата нет, это обычный Markdown. Но Claude читает файл как контекст и не исполняет его так же строго, как настройки, поэтому от формулировок зависит, насколько точно он им следует. Anthropic даёт три правила: конкретность, краткость и отсутствие противоречий.

Раздел Write effective instructions в документации Claude Code с рекомендацией держать CLAUDE.md короче 200 строк
Anthropic советует держать каждый CLAUDE.md короче 200 строк: длинный файл съедает контекст и хуже соблюдается. Скриншот: документация Claude Code

Вот файл моего демо-проекта целиком, на нём держатся все проверки в статье:

# 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 отвечает, что между строкой с импортом и разделом «Команды» пусто
Комментарий <!-- … --> до модели не дошёл, а файл из импорта загрузился отдельным блоком. Скриншот: терминал / matveev.tech

Как разбить большой файл: импорты и правила .claude/rules

Когда файл подбирается к 200 строкам, его пора делить. Есть два способа, и работают они по-разному.

Импорт через @. Строка @docs/api-conventions.md подставляет файл целиком в контекст вместе с основным файлом. Путь считается от файла, где стоит импорт, вложенность до четырёх уровней. Это удобно для порядка, но контекст не экономит: импортированный файл грузится всегда.

Правила в .claude/rules/. Каждый файл в этой папке посвящён одной теме. Правило без настроек грузится в начале сессии, как основной файл. А правило с полем paths подключается, только когда Claude открывает подходящий файл. Вот правило для тестов из демо:

---
paths:
  - "tests/**/*.py"
---

# Тесты
- Вызывай приложение через `TestClient(app)`, без поднятого сервера
- Сравнивай ответ целиком, вместе с `error`
- Моки только для внешних HTTP-сервисов

Я попросил Claude открыть тест и перечислить правила, которые он видит. Он нашёл все четыре источника и отдельно отметил, что tests.md подгрузился в момент чтения файла теста.

Терминал: Claude перечисляет правила для тестов из .claude/rules/tests.md, CLAUDE.md, api-conventions.md и CLAUDE.local.md
Правило с paths пришло в контекст только после того, как Claude открыл файл из tests/. Промпт в первой строке сокращён. Скриншот: терминал / matveev.tech

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

Karpathy skills для Claude Code: 4 правила против мусора
Четыре правила Андрея Карпаты, которые можно положить в CLAUDE.md или поставить скиллом.

Как 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 показывает его среди файлов инструкций.

Терминал: таблица Memory files, в которой единственный файл AGENTS.md
В проекте без CLAUDE.md Claude Code сам подхватил AGENTS.md. Скриншот: терминал / matveev.tech

Если у тебя есть оба файла, по умолчанию 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/, которой в репозитории нет. Он честно пометил находку низкой уверенностью: папка может появиться позже.

Терминал: отчёт /doctor prompt-audit с одной находкой про несуществующую папку alembic/versions
Аудит сверил каждую команду из CLAUDE.md с Makefile и нашёл только упоминание несуществующей папки. Скриншот: терминал / matveev.tech

Ещё один способ подходит для отладки правил с paths: хук InstructionsLoaded пишет в лог, какой файл инструкций загрузился и почему. Как устроены хуки, я разбирал в гайде по хукам Claude Code.

Свои CLAUDE.md, скиллы и находки по настройке 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 Code: полный гайд по settings.json
Где лежат настройки Claude Code и что в них менять, когда одного CLAUDE.md мало.

Частые вопросы о 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.

Читайте также

CTO говорит

Разбираю релизы моделей и инструментов: что вышло и стоит ли переходить.

Читать в Telegram

Ещё в разделе Claude Code

Весь раздел