CLAUDE.md (claude md): что это, пример файла и шаблоны под стеки

Обновлено 15 минут чтения

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 может выполнить и ты можешь проверить. Документация приводит тот же приём: «Run npm test before 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

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

  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 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

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

  1. Файл вообще загрузился? Запусти /context all и найди его в 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 года (откроется в новой вкладке) о том, как он пишет код вместе с 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 не запускается. Отправьте себе ссылку на этот список.

  1. Разработка
    Создатель скиллов

    Помогает создавать скиллы для Claude Code с верной структурой и документацией

    skill-creator · anthropics

  2. Утилиты
    Создание собственных скиллов

    Помогает создавать и редактировать скиллы и проверять их до публикации.

    writing-skills · obra

  3. Утилиты
    Создание GIF для Slack

    Создаёт анимированные GIF для Slack, которые быстро грузятся.

    slack-gif-creator · anthropics

«Создание собственных скиллов»: отмечен редакцией к этой статье; «Создание GIF для Slack»: близко к «Создание собственных скиллов».

Что нужно: компьютер и Claude Code — он работает с подпиской Claude Pro и выше, на бесплатном плане его нет. Как поставить Claude Code →

Читать дальше