CLAUDE.md: что это и как написать

Каждая сессия Claude Code начинается с чистого контекста. Вчера ты объяснил, какой командой запускать тесты и почему нельзя трогать старые миграции, а сегодня Claude может снова об этом не знать: автопамять сохраняет не всё. CLAUDE.md закрывает эту дыру: это Markdown-файл с инструкциями, который Claude читает в начале каждой сессии.

Дальше по порядку: где лежит файл и в каком порядке Claude его собирает, как быстро создать его командой /init, что в него писать и чего не писать. В середине есть готовый пример для проекта на Next.js, его можно взять за основу.

Что такое CLAUDE.md простыми словами#

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

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

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

Где лежит CLAUDE.md#

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

1. Политика организации. На macOS /Library/Application Support/ClaudeCode/CLAUDE.md, на Linux и WSL /etc/claude-code/CLAUDE.md, на Windows C:\Program Files\ClaudeCode\CLAUDE.md. Такой файл раскатывает IT-отдел, и личными настройками его не отключить.
2. Личный файл ~/.claude/CLAUDE.md. Твои привычки для всех проектов сразу.
3. Файл проекта ./CLAUDE.md или ./.claude/CLAUDE.md. Общие правила команды, живут в git вместе с кодом.
4. Локальный файл ./CLAUDE.local.md. Личные настройки для одного проекта: адрес твоей песочницы, любимые тестовые данные. Его добавляют в .gitignore.

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

Ещё две мелочи. Блочные HTML-комментарии вида <!-- заметка для людей --> вырезаются до того, как текст попадёт в контекст, так что пометки для коллег токенов не тратят. А проверить, какие файлы Claude увидел, можно командой /context: список лежит в разделе Memory files.

Как создать CLAUDE.md командой /init#

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

Если в репозитории остались правила от других инструментов, /init вытащит из них полезное: правила Cursor из .cursor/rules/ или .cursorrules и инструкции Copilot из .github/copilot-instructions.md.

Есть и подробный режим. Задай переменную окружения CLAUDE_CODE_NEW_INIT=1 и запусти /init: команда спросит, что настраивать (CLAUDE.md, скиллы, хуки), изучит код через субагента, задаст уточняющие вопросы и покажет предложение до записи файлов. В этом режиме она читает ещё и AGENTS.md, .windsurfrules, .clinerules и правила Devin.

Черновик от /init годится только как старт. Самое ценное Claude из кода не выведет: почему в проекте принято именно так, где уже ломалось и какие команды запускать нельзя. Это дописываешь ты.

Редактировать файлы удобно через /memory. Команда показывает файлы памяти пользователя и проекта, в том числе ещё не созданные CLAUDE.md, и открывает выбранный в редакторе. Если файла ещё нет, она сначала его создаёт. Можно и попросить Claude словами: «добавь это в CLAUDE.md». А вот фраза «запомни, что тестам API нужен локальный Redis» сработает иначе: такую заметку Claude положит в автопамять, а не в CLAUDE.md.

Пример CLAUDE.md для реального проекта#

Ниже файл для типичного веб-проекта на Next.js и TypeScript с базой в Supabase. Пример мой, в документации такого шаблона нет: подставь свои команды, пути и договорённости. Сохрани его в корне репозитория как CLAUDE.md: относительные импорты отсчитываются от папки самого файла, и в .claude/CLAUDE.md строки @README.md и @package.json искали бы файлы внутри .claude/.

# Каталог статей: Next.js + TypeScript + Supabase

Обзор проекта: @README.md
Все npm-скрипты: @package.json

## Команды
- Установка зависимостей: `npm ci`
- Dev-сервер: `npm run dev`, нужен файл `.env.local` (образец в `.env.example`)
- Проверка типов: `npx tsc --noEmit`
- Один тест: `npx vitest run путь/к/файлу.test.ts`; весь набор без необходимости не гоняй

## Код
- TypeScript strict, без `any`
- Входные данные API проверяем Zod-схемами из `lib/validation/`
- К базе ходим только через `lib/db/`, из компонентов напрямую запросов нет
- Импорты через алиас `@/`

## Git
- Ветки `feat/...` и `fix/...`, сообщения коммитов на английском
- IMPORTANT: не коммить и не пушь, пока я не попросил

## Грабли
- Миграции в `supabase/migrations/` не редактируем, только добавляем новые файлы
- Картинки статей живут в хранилище, в `public/` их не кладём

## При сжатии контекста
- Сохраняй список изменённых файлов и команды, которыми гонял тесты

Что здесь сделано сознательно:

• Импорты вместо пересказа. Строки @README.md и @package.json подтягивают файлы целиком, поэтому переписывать npm-скрипты руками не нужно. Цена приёма: оба файла целиком уходят в контекст каждой сессии. Если README длинный, лучше выписать три нужные команды.
• Проверяемые правила. «Один тест через npx vitest run» Claude может выполнить и ты можешь проверить. Документация приводит тот же приём: «Run npm test before committing» вместо «Test your changes».
• Одно выделение. IMPORTANT стоит на одной строке. Документация советует ставить его на правило, которое Claude раз за разом пропускает, а если выделить так десяток строк, ни одна не будет выделяться.
• Блок про сжатие. В документации прямо предлагают писать в CLAUDE.md, что сохранять при сжатии контекста.
• Короткий файл. Официальный ориентир: меньше 200 строк на один CLAUDE.md. Длинный файл съедает контекст, и Claude хуже следует правилам.

Личные настройки, которые не нужны команде, клади в CLAUDE.local.md в корне проекта:

# Мои настройки для этого проекта
- Моя песочница: https://staging-moe-imya.example.com
- Тестовый аккаунт для ручных проверок: qa@example.com

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

Документация даёт на каждую строку один проверочный вопрос: «Если её убрать, Claude начнёт ошибаться?» Если нет, строку удаляй. На практике под нож идёт вот что:

• То, что видно из кода. Структура папок, список зависимостей, пересказ архитектуры. Именно такое предлагает вырезать проверка /doctor.
• Стандартные соглашения языка. Модель их и так знает.
• Подробная документация API. Лучше ссылка на неё.
• То, что часто меняется. Устаревшая строка хуже отсутствующей.
• Длинные объяснения, туториалы и описание каждого файла.
• Очевидности вроде «пиши чистый код».
• Секреты. Файл проекта уходит в git вместе с кодом, и токен из него увидит каждый, у кого есть доступ к репозиторию. Ключи храни в .env, а в CLAUDE.md пиши только, где лежит образец.
• Запреты, которые обязаны сработать. Строка «никогда не редактируй .env» остаётся просьбой. Гарантию даёт хук PreToolUse, который блокирует правку.
• Многошаговые процедуры и знания для одной части кода. Их место в скилле или в правиле с привязкой к путям.

Как не раздуть файл: импорты и .claude/rules#

CLAUDE.md умеет подключать другие файлы синтаксисом @путь/к/файлу. Относительный путь отсчитывают от файла, в котором стоит импорт, а не от рабочей папки. Импортированный файл может импортировать следующий, глубина ограничена четырьмя переходами. Внутри обратных кавычек и блоков кода импорт не срабатывает: `@README` останется просто текстом.

Импорты помогают навести порядок, но контекст не экономят: подключённые файлы загружаются на старте вместе с CLAUDE.md. Если импорт в файле проекта ведёт за пределы рабочей папки, в первый раз Claude Code покажет окно подтверждения со списком таких файлов. Импорты из личного ~/.claude/CLAUDE.md грузятся без вопроса, кроме сессий Cowork на десктопе.

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

---
paths:
  - "app/api/**/*.ts"
---

# Правила для API
- Каждый обработчик проверяет вход Zod-схемой
- Ошибки отдаём в одном формате: { error: { code, message } }

И верхняя граница: CLAUDE.md размером до 4 МиБ Claude Code загружает целиком, а файл крупнее пропускает. Упираться в неё незачем: чем короче файл, тем лучше Claude ему следует.

CLAUDE.md, скиллы и AGENTS.md: что куда класть#

CLAUDE.md загружается в каждой сессии. Сюда идёт то, что Claude должен знать всегда: команды сборки, соглашения, правила «всегда делай X» и «никогда не делай Y».

Скилл загружается по требованию. На старте Claude видит только его описание, а полный текст подтягивает, когда задача подходит или когда ты вызываешь скилл командой /имя. Если ты в третий раз вставляешь в чат один и тот же многошаговый порядок действий, его пора оформить скиллом. Что такое скиллы, разобрано в статье «Что такое Claude Skills и зачем они нужны», а как подключить их рядом с CLAUDE.md, в гайде «Claude Skills: как настроить Claude Code под свои задачи». Готовые скиллы лежат в каталоге claudeskills.ru, а свой удобно собрать со скиллом «Создатель скиллов».

AGENTS.md встречается в репозиториях, настроенных под другие агенты. Claude Code читает его сам, если в рабочей папке и выше нет ни CLAUDE.md, ни CLAUDE.local.md. Если есть оба файла, по умолчанию Claude читает только CLAUDE.md. Учти это, когда заводишь CLAUDE.local.md в репозитории на AGENTS.md: Claude Code увидит локальный файл как свой CLAUDE-файл и перестанет читать AGENTS.md. Изменить это можно в /config, параметр Project instructions: значение claude-md-and-agents-md включает чтение обоих. Прямое чтение AGENTS.md работает с версии Claude Code 2.1.277, а на Amazon Bedrock и с отключённой телеметрией с 2.1.281.

Если хочешь держать один общий файл для всех агентов, напиши в CLAUDE.md строку @AGENTS.md, а под ней правила только для Claude:

@AGENTS.md

## Claude Code
- Для изменений в `src/billing/` сначала режим планирования

Символическая ссылка CLAUDE.md → AGENTS.md тоже работает, но если кто-то в команде сидит на Windows, документация советует импорт: без включённого core.symlinks git выкачивает ссылку как обычный текстовый файл.

Автопамять не путай с CLAUDE.md. Её пишет сам Claude: твои поправки, предпочтения, контекст проекта, который не вывести из кода. Хранится она в ~/.claude/projects/<проект>/memory/, а в каждую сессию попадают первые 200 строк или 25 КБ индекса MEMORY.md. Включается и выключается через /memory.

Почему Claude не слушается CLAUDE.md#

Прежде чем переписывать правила, пройди по списку:

1. Файл вообще загрузился? Запусти /context и найди его в Memory files. Если его там нет, Claude его не видит: проверь, лежит ли файл в одном из мест, которые читаются для твоей сессии.
2. Правила не спорят? Если два файла говорят разное про одно и то же, Claude может выбрать любое. Пересмотри корневой файл, вложенные CLAUDE.md и .claude/rules/.
3. Файл не разросся? Если Claude упорно делает то, что запрещено, документация первой называет длину: правило теряется в длинном файле. Режь.
4. Формулировка однозначна? Если Claude спрашивает то, на что в CLAUDE.md уже есть ответ, перепиши строку конкретнее.
5. Правило пропало после /compact? Корневой CLAUDE.md переживает сжатие: Claude перечитывает его с диска. Вложенные файлы возвращаются, когда Claude снова откроет файлы в их папке. Пропадает то, что ты говорил только в чате, так что важное переноси в файл.
6. Действие обязано выполняться всегда? Тогда нужен хук. Хуки запускаются на фиксированных событиях и не зависят от решения модели.

Что за «CLAUDE.md от Карпаты»#

В подсказках поиска встречается запрос про CLAUDE.md от Карпаты. У Андрея Карпаты (Andrej Karpathy) есть пост на X от 26 января 2026 года (opens in new tab) о том, как он пишет код вместе с Claude, и готового CLAUDE.md в этом посте нет. Там он перечислил, где модели ошибаются в коде: делают неверные допущения и не переспрашивают, переусложняют код и API, не убирают за собой мёртвый код, правят комментарии и код, которые к задаче не относятся. И добавил, что всё это происходит несмотря на несколько простых попыток исправить ситуацию инструкциями в CLAUDE.md.

Файл, который ходит под его именем, лежит в стороннем репозитории multica-ai/andrej-karpathy-skills (opens in new tab) на GitHub, и ведёт его не Карпаты. Его авторы свели наблюдения из поста в четыре принципа: думать до кода, простота прежде всего, точечные правки, работа от проверяемой цели. Эти принципы можно добавить в свой CLAUDE.md, только помни, что это общие правила поведения. Команд сборки и граблей твоего репозитория в них нет, их всё равно пишешь ты.

С чего начать#

Запусти /init и получи черновик. Вычеркни всё, что Claude и так видит в коде, и допиши то, чего в коде нет: запреты, грабли, порядок проверки. Дальше обновляй файл по одному правилу: если Claude второй раз ошибся в одном и том же месте, эта поправка переезжает в CLAUDE.md. Если Claude Code у тебя ещё не стоит, начни с гайда по установке и первым шагам.

Частые вопросы#

Нужно ли коммитить CLAUDE.md в git?

Файл проекта нужно: он общий для команды, и документация советует держать его в git, чтобы коллеги его дополняли. Личные настройки для одного проекта клади в CLAUDE.local.md и добавь его в .gitignore.

Какой длины должен быть CLAUDE.md?

Ориентир из документации: меньше 200 строк на один файл. Всё, что нужно не в каждой сессии, выноси в правила с полем paths или в скиллы.

Сработает ли CLAUDE.md, если запустить Claude из подпапки?

Да. Claude Code читает CLAUDE.md из папки запуска и из всех папок выше, так что корневой файл репозитория тоже попадёт в контекст. Запустишь в foo/bar/, и загрузятся и foo/bar/CLAUDE.md, и foo/CLAUDE.md.