CLAUDE.md (claude md): что это, пример файла и шаблоны под стеки
CLAUDE.md (в поиске его пишут и «claude.md», и «claude md», файл один и тот же) — это Markdown-файл с инструкциями, который Claude Code читает в начале каждой сессии: команды сборки и тестов, соглашения, грабли проекта. Каждая сессия начинается с чистого контекста. Вчера ты объяснил, какой командой запускать тесты и почему нельзя трогать старые миграции, а сегодня Claude может снова об этом не знать: автопамять сохраняет не всё. CLAUDE.md закрывает эту дыру.
Сразу ниже готовый пример файла для проекта на Next.js, дальше по порядку: где лежит файл, как создать его командой /init, шаблоны под Python, Node.js, Go, Rust и текстовый проект, что в файл не писать. Правила загрузки и размещения файлов сверены с документацией Claude Code 12.11.2026.
Пример 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/...`, сообщения коммитов на английском
- Не коммить и не пушь, пока я не попросил
## Грабли
- Миграции в `supabase/migrations/` не редактируем, только добавляем новые файлы
- Картинки статей живут в хранилище, в `public/` их не кладём
## Compact Instructions
- Сохраняй список изменённых файлов и команды, которыми гонял тесты
Что здесь сделано сознательно:
- Импорты вместо пересказа. Строки
@README.mdи@package.jsonподтягивают файлы целиком, поэтому переписывать npm-скрипты руками не нужно. Цена приёма: оба файла целиком уходят в контекст каждой сессии. Если README длинный, лучше выписать три нужные команды. - Проверяемые правила. «Один тест через
npx vitest run» Claude может выполнить и ты можешь проверить. Документация приводит тот же приём: «Runnpm testbefore committing» вместо «Test your changes». - Без капслока и IMPORTANT. Каждое правило записано обычной фразой, без выделения. В актуальной документации Anthropic IMPORTANT и ALL CAPS отнесены к приёмам, которые были нужны старым моделям: текущие модели следуют ясно написанной строке, а лишнее выделение чаще заставляет применять правило слишком рьяно. Если Claude всё равно пропускает строку, причина обычно в том, что файл разросся и строка в нём потерялась, либо правило не терпит исключений и его место в хуке.
- Блок про сжатие. В документации предлагают добавить в CLAUDE.md раздел «Compact Instructions»: в нём пишут, что сохранять при сжатии контекста.
- Короткий файл. Официальный ориентир: меньше 200 строк на один CLAUDE.md. Длинный файл съедает контекст, и Claude хуже следует правилам.
Личные настройки, которые не нужны команде, клади в CLAUDE.local.md в корне проекта:
# Мои настройки для этого проекта
- Моя песочница: https://staging-moe-imya.example.com
- Тестовый аккаунт для ручных проверок: qa@example.com
Что такое CLAUDE.md простыми словами
Когда к проекту подключается новый разработчик, ты рассказываешь ему, как собрать проект, где лежат обработчики API, как называть ветки и какие грабли уже собраны. CLAUDE.md хранит ровно такую записку, только читает её Claude, и пересказывать её каждое утро не нужно.
Сразу про границу. Claude воспринимает CLAUDE.md как контекст, а не как жёсткую настройку. Содержимое файла приходит в модель пользовательским сообщением после системного промпта, и строгого исполнения никто не гарантирует, особенно если инструкции размытые или спорят друг с другом. Если действие нужно заблокировать при любом раскладе, документация советует хук PreToolUse.
Официальная подсказка, когда дописывать файл: Claude второй раз повторяет ту же ошибку, ревью ловит то, что он должен был знать про этот код, или ты набираешь в чате то же уточнение, что и в прошлой сессии.
Где лежит CLAUDE.md
Файлов может быть несколько, и у каждого своя зона действия. Вот они в порядке загрузки, от самого общего к самому частному:
- Политика организации. На macOS
/Library/Application Support/ClaudeCode/CLAUDE.md, на Linux и WSL/etc/claude-code/CLAUDE.md, на WindowsC:\Program Files\ClaudeCode\CLAUDE.md. Такой файл раскатывает IT-отдел, и личными настройками его не отключить. - Личный файл
~/.claude/CLAUDE.md. Твои привычки для всех проектов сразу. - Файл проекта
./CLAUDE.mdили./.claude/CLAUDE.md. Общие правила команды, живут в git вместе с кодом. - Локальный файл
./CLAUDE.local.md. Личные настройки для одного проекта: адрес твоей песочницы, любимые тестовые данные. Его добавляют в.gitignore.
Claude Code берёт CLAUDE.md и CLAUDE.local.md из папки, где ты его запустил, и из всех папок выше. Файлы склеиваются, и ни один не отменяет другой: сначала идут верхние папки, потом ближние к месту запуска, а внутри одной папки CLAUDE.local.md встаёт после CLAUDE.md. Файлы из подпапок на старте не читаются. Они подгружаются, когда Claude открывает файлы в этих подпапках.
Ещё две мелочи. Блочные HTML-комментарии вида <!-- заметка для людей --> вырезаются до того, как текст попадёт в контекст, так что пометки для коллег токенов не тратят. А проверить, какие файлы Claude увидел, можно командой /context all: список лежит в разделе Memory files. Без all в полноэкранном режиме этот список сворачивается.
Как создать 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 под разные стеки
Шаблоны ниже мои, это примеры, а не официальные образцы: команды типовые, пути придуманы для иллюстрации. Бери блок, меняй команды и папки на свои, а то, чего нет в твоём проекте, вычёркивай. Каждый шаблон короткий по той же причине, что и пример выше: длинный файл Claude выполняет хуже.
- Python. В шаблоне команды
pytestиruff check. Что важно записать: версию интерпретатора, где живёт бизнес-логика, правила для миграций. - Node.js и TypeScript. В шаблоне команды
npm testиnpx tsc --noEmit. Что важно записать: строгость типов, где проверяется вход, формат ошибок. - Go. В шаблоне команды
go test ./...иgo vet ./.... Что важно записать: структуру пакетов, как оборачивать ошибки. - Rust. В шаблоне команды
cargo testиcargo clippy. Что важно записать: как работать с ошибками, правила для новых зависимостей. - Текстовый проект без кода. Команд в шаблоне нет. Что важно записать: тон, стоп-слова, структуру материала.
Python-сервис
# Сервис на Python
## Команды
- Окружение: `python -m venv .venv`, затем `pip install -r requirements.txt`
- Тесты: `pytest -q`; один файл: `pytest tests/test_orders.py`
- Линтер: `ruff check .`
## Код
- Версия Python: [укажи свою], аннотации типов в новых функциях
- Бизнес-логика в `app/services/`, обработчики запросов только вызывают её
- Настройки читаем из переменных окружения, значений по умолчанию для секретов нет
## Грабли
- Миграции в `migrations/` не редактируем, добавляем новые
- Тесты не ходят во внешние сервисы, для них есть фикстуры в `tests/conftest.py`
API на Node.js и TypeScript
# API на Node.js и TypeScript
## Команды
- Зависимости: `npm ci`
- Запуск: `npm run dev`
- Проверка типов: `npx tsc --noEmit`
- Тесты: `npm test`, линтер: `npm run lint`
## Код
- TypeScript strict, без `any`
- Вход проверяем схемой в контроллере, сервисы получают уже проверенные данные
- Ошибки отдаём в одном формате: `{ error: { code, message } }`
## Git
- Ветки `feat/...` и `fix/...`
- Не коммить и не пушь, пока я не попросил
Сервис на Go
# Сервис на Go
## Команды
- Сборка: `go build ./...`
- Тесты: `go test ./...`; один пакет: `go test ./internal/orders`
- Проверка: `go vet ./...` и `gofmt -l .`
## Код
- Код живёт в `internal/`, публичного API у модуля нет
- Ошибки оборачиваем с контекстом: `fmt.Errorf("создание заказа: %w", err)`
- `context.Context` идёт первым аргументом в функциях, которые ходят в сеть или базу
- Тесты пишем таблицами
Крейт на Rust
# Крейт на Rust
## Команды
- Сборка: `cargo build`
- Тесты: `cargo test`
- Проверка: `cargo clippy -- -D warnings` и `cargo fmt --check`
## Код
- Ошибки возвращаем через `Result`, `unwrap()` допустим только в тестах
- Новые зависимости не добавляем без моего согласия
- У публичных функций есть комментарий `///`
Текстовый проект без кода
# Блог компании
## Голос
- Пишем на «ты», абзацы по 2–4 предложения
- Не используем слова «инновационный», «уникальный», «передовой»
- Каждая статья заканчивается одним конкретным действием для читателя
## Структура
- Суть сразу после заголовка, без вступления «в современном мире»
- Заголовки второго уровня повторяют вопрос читателя
## Чего не делаем
- Не выдумываем цифры и цитаты: нет данных, так и пишем
Что не писать в CLAUDE.md
Документация Anthropic советует держать в 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
Прежде чем переписывать правила, пройди по списку:
- Файл вообще загрузился? Запусти
/context allи найди его в Memory files. Если его там нет, Claude его не видит: проверь, лежит ли файл в одном из мест, которые читаются для твоей сессии. - Правила не спорят? Если два файла говорят разное про одно и то же, Claude может выбрать любое. Пересмотри корневой файл, вложенные CLAUDE.md и
.claude/rules/. - Файл не разросся? Если Claude упорно делает то, что запрещено, документация первой называет длину: правило теряется в длинном файле. Режь.
- Формулировка однозначна? Если Claude спрашивает то, на что в CLAUDE.md уже есть ответ, перепиши строку конкретнее.
- Правило пропало после
/compact? Корневой CLAUDE.md переживает сжатие: Claude перечитывает его с диска. Вложенные файлы возвращаются, когда Claude снова откроет файлы в их папке. Пропадает то, что ты говорил только в чате, так что важное переноси в файл. - Действие обязано выполняться всегда? Тогда нужен хук. Хуки запускаются на фиксированных событиях и не зависят от решения модели.
Что за «CLAUDE.md от Карпаты»
В подсказках поиска встречается запрос про CLAUDE.md от Карпаты. У Андрея Карпаты (Andrej Karpathy) есть пост на X от 26 января 2026 года (откроется в новой вкладке) о том, как он пишет код вместе с Claude, и готового CLAUDE.md в этом посте нет. Там он перечислил, где модели ошибаются в коде: делают неверные допущения и не переспрашивают, переусложняют код и API, не убирают за собой мёртвый код, правят комментарии и код, которые к задаче не относятся. И добавил, что всё это происходит несмотря на несколько простых попыток исправить ситуацию инструкциями в CLAUDE.md.
Файл, который ходит под его именем, лежит в стороннем репозитории multica-ai/andrej-karpathy-skills (откроется в новой вкладке) на 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.
Что поставить первым
Скиллы ставятся на компьютере, на телефоне Claude Code не запускается. Отправьте себе ссылку на этот список.
- РазработкаСоздатель скиллов
Помогает создавать скиллы для Claude Code с верной структурой и документацией
skill-creator· anthropics - УтилитыСоздание собственных скиллов
Помогает создавать и редактировать скиллы и проверять их до публикации.
writing-skills· obra - УтилитыСоздание GIF для Slack
Создаёт анимированные GIF для Slack, которые быстро грузятся.
slack-gif-creator· anthropics
Читать дальше
- Лучшие скиллы для Claude Code: топ-15 по скачиваниям с примерамиТоп-15 скиллов для Claude Code по скачиваниям за 90 дней: что делает каждый, пример запроса и команда установки. Код, тесты, ревью, планы.
- Скачать Claude на компьютер и телефон: Windows, Mac, iOS, AndroidСкачать Claude Desktop для Windows, macOS, Linux, iPhone и Android: официальные ссылки, требования, как не попасть на подделку, что с регионом.
- Claude для программирования: чат, Claude Code, IDE и API — какой способ выбратьКак программировать с Claude: чат для быстрых вопросов, Claude Code для проекта, расширения IDE и API. Что выбрать под задачу и какие скиллы подключить.