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

CLAUDE.md — это файл с инструкциями по проекту, который Claude Code читает в начале каждой сессии. Положите его в корень репозитория и опишите внутри, чем проект собирается, чем запускаются тесты и каких соглашений держаться в коде. После этого агент перестанет спрашивать одно и то же в каждом новом диалоге и предлагать решения, которые в вашей кодовой базе не приняты. Формат предельно простой: обычный Markdown, обязательных полей нет, заголовки любые.

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

Одна оговорка перед началом: Claude Code обновляется часто, набор команд и поддерживаемых файлов пополняется. Если какая-то деталь ниже ведёт себя у вас иначе, сверяйтесь с документацией той версии, которая стоит у вас.

Что такое CLAUDE.md и как Claude Code его использует

Разница между инструкцией в чате и инструкцией в CLAUDE.md — в том, живёт ли она дольше одной сессии. Всё, что вы напишете в диалоге, исчезнет вместе с его контекстом: в следующий раз агент снова не будет знать, что тесты у вас запускаются не через npm test, а через скрипт в воркспейсе. CLAUDE.md подключается к контексту при старте, поэтому правило из него работает в каждом диалоге, пока вы его оттуда не уберёте.

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

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

Где создавать CLAUDE.md: проект, дом, подпапки

Файл не один, и это главное, что стоит понять про него с самого начала. Claude Code читает инструкции из нескольких мест, и у каждого своя роль.

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

./CLAUDE.local.md — личные заметки по этому проекту, которые не нужны остальным: ваши временные обходные пути, ваши предпочтения по стилю ответа. Этот файл нужно внести в .gitignore, иначе он уедет в репозиторий и перестанет быть личным.

~/.claude/CLAUDE.md — ваш собственный файл на все проекты. Сюда идёт то, что не зависит от кодовой базы: на каком языке вам отвечать, насколько подробно комментировать изменения, какие инструменты у вас установлены. Правила уровня «в этом проекте не используем any» здесь не к месту — в другом проекте они окажутся вредными.

CLAUDE.md в подпапках — инструкции для части репозитория. В монорепозитории это основной способ не раздувать корневой файл: общие вещи в корне, специфика пакета — рядом с пакетом.

Как Claude Code ищет и объединяет файлы по иерархии

Здесь прячется поведение, из-за которого у людей «не применяются» правила.

Во-первых, при запуске Claude Code идёт от текущей папки вверх по дереву и подбирает файлы инструкций, которые встретит по пути, вплоть до корня файловой системы. Поэтому агент, запущенный из apps/api, увидит и apps/api/CLAUDE.md, и корневой файл проекта. А запущенный из корня — только корневой.

Во-вторых, файлы в подпапках подключаются не все сразу, а по необходимости: инструкции из packages/ui/CLAUDE.md попадут в контекст тогда, когда агент станет работать с файлами из packages/ui. Это сделано ровно для того, чтобы монорепозиторий на двадцать пакетов не съедал контекст двадцатью файлами правил. Побочный эффект: если вы положили файл в подпапку и ждёте, что правило подействует сразу в начале диалога, — оно не подействует, пока дело не дойдёт до кода в этой папке.

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

Что писать внутри: минимальный рабочий пример

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

# Проект

Сервис выдачи сертификатов. Монорепозиторий: `apps/api` — Fastify,
`apps/web` — Next.js, общий код в `packages/shared`.

## Команды

- `npm run dev` — поднимает api и web одновременно
- `npm run test -w apps/api` — тесты только api
- `npm run lint` — ESLint и Prettier

## Соглашения

- TypeScript в strict, `any` не использовать
- Обращения к базе только через репозитории в `packages/shared/db`
- Новые эндпоинты описывай схемой Zod, руками входные данные не проверяй

## Чего не делать

- Не менять существующие миграции в `apps/api/migrations`, только добавлять новые
- Не запускать линтер с `--fix` по всему проекту: в диффе будет не ваша правка

Что делает этот файл полезным, кроме самого факта существования.

Команды выписаны буквально. Строка npm run test -w apps/api стоит десяти абзацев про то, что проект — монорепозиторий: агент просто скопирует её, вместо того чтобы пробовать npm test в корне и разбираться, почему не вышло.

Правила сформулированы как требования, а не как описания. «Обращения к базе только через репозитории» и «в проекте есть слой репозиториев» читаются агентом по-разному: первое — указание, второе — факт к сведению. Пишите инструкции повелительно, это заметно влияет на то, выполняются ли они.

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

Чего в файл писать не стоит: общих напутствий вроде «пиши читаемый код» — они не меняют поведение; дублирования README — агент и так умеет его открыть; и, отдельным пунктом, любых секретов. Проектный CLAUDE.md коммитится, а ключи и токены передаются через переменные окружения — как это устроено, разобрано в переменных окружения в Bash.

Подключение внешних файлов через @путь

Если документация у вас уже написана, переписывать её в CLAUDE.md не нужно. Внутри файла можно сослаться на другой документ через @ с путём, и его содержимое подключится к инструкциям:

# Проект

Сервис выдачи сертификатов, стек — Fastify и Next.js.

Правила ревью: @docs/code-review.md
Схема базы: @packages/shared/db/SCHEMA.md
Личные настройки: @~/.claude/my-style.md

Пути работают и относительные от файла, и домашние через ~. Последняя строка — удобный приём: личные предпочтения лежат вне репозитория, а подключаются к общему файлу, и в git при этом уезжает только ссылка.

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

/init и /memory: команды для работы с файлом

Писать файл с нуля руками необязательно. В запущенном Claude Code есть команда, которая собирает первую версию сама:

/init

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

Вторая команда открывает файлы инструкций на редактирование, не выходя из агента:

/memory

Удобно, когда правило придумалось по ходу диалога: не нужно искать, какой из файлов где лежит.

Третий способ — самый быстрый. Сообщение, начинающееся с #, агент воспринимает не как задачу, а как правило, которое нужно запомнить, и спрашивает, в какой файл его положить:

# тесты запускай через npm run test -w apps/api, в корне их нет

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

Чем CLAUDE.md отличается от AGENTS.md

Коротко: CLAUDE.md — файл Claude Code, AGENTS.md — открытый формат, который понимают многие агенты, от Codex и OpenCode до редакторов вроде Cursor и Zed. Содержимое у них по смыслу одно и то же: инструкции по проекту обычным Markdown.

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

ln -s AGENTS.md CLAUDE.md

Полезно знать и обратную совместимость: OpenCode по умолчанию понимает соглашения Claude Code и подхватывает CLAUDE.md в проекте, если рядом нет AGENTS.md, а также домашний ~/.claude/CLAUDE.md. То есть при переезде с Claude Code на OpenCode файл инструкций переносить не нужно. Правила приоритета между этими файлами, список инструментов, читающих AGENTS.md, и переменные, которыми совместимость отключается, разобраны отдельно: AGENTS.md: как написать инструкции для Codex и OpenCode.

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

Файл разросся, и правила перестали выполняться. Самая распространённая проблема. Чем длиннее файл, тем хуже применяется каждое отдельное требование, — а длинным он становится сам, потому что дописывать в него легко, а вычищать некому. Лечится ревизией: всё, что нужно изредка или только для одной подсистемы, выносится в отдельный документ и подключается через @, а в корневом файле остаётся то, что применимо всегда.

Правило есть, но сформулировано как описание. «Мы используем Zod для валидации» — это сведение, «описывай входные данные схемой Zod» — указание. Разница в поведении агента ощутимая.

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

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

В файле лежат секреты. Проектный CLAUDE.md коммитится в репозиторий, а значит, ключ из него отправится вместе с кодом. Для личных значений есть CLAUDE.local.md в .gitignore и переменные окружения.

Если же агент не доходит до чтения инструкций вовсе и падает на запуске, дело не в файле — частые причины собраны в разборе Claude Code не запускается: 7 частых ошибок.

Как подключить Claude Code из России и начать с CLAUDE.md

CLAUDE.md бесполезен, пока сам агент не работает, а напрямую из России API Anthropic не отвечает. Решается это подменой адреса: Claude Code настраивается переменными окружения, в которых указывается совместимый эндпоинт, и дальше работает как обычно. Готовый адрес и ключ с оплатой в рублях даёт AI для кода от PurpleSchool — одним ключом пользуются и Claude Code, и другие агенты, баланс токенов общий.

Пошаговая установка со всеми переменными и проверкой подключения разобрана отдельно: Claude Code в России: как подключить и настроить без VPN. А когда агент запустится, начните не с чтения документации, а с /init в корне проекта: дальше файл будет расти сам, из ваших же поправок.