CLAUDE.md: что это, пример и 6 правил, чтобы Claude Code слушался

Автор: Silvana · Дата: 16.09.2026 · Verified: 16.09.2026 · Reading time: 12 минут · Prerequisite: установленный Claude Code

Актуально на 16 сентября 2026. Проверено по документации Claude Code (разделы «How Claude remembers your project» и «Best practices»).

Кратко

• CLAUDE.md — обычный markdown-файл, который Claude Code читает в начале каждой сессии. Это постоянные инструкции: команды сборки, правила кода, структура проекта, «всегда делай X».
• Файл живёт на четырёх уровнях: организация → ~/.claude/CLAUDE.md (личный) → ./CLAUDE.md в проекте → ./CLAUDE.local.md (личный для проекта, не в git). Всё найденное склеивается в один контекст, а не перекрывает друг друга.
• Документация просит держать файл короче 200 строк, писать проверяемые формулировки («2 пробела отступ», «перед коммитом npm test«) и не держать противоречий. Длинный и расплывчатый файл Claude выполняет хуже.
• Многошаговые процедуры — не в CLAUDE.md, а в скиллы; правила для части кода — в .claude/rules/ с полем paths.
• Рядом есть автоматическая память (auto memory): заметки, которые Claude пишет сам по вашим поправкам. CLAUDE.md пишете вы, память — Claude.

Что такое CLAUDE.md

Каждая сессия Claude Code начинается с пустого контекста. Чтобы не объяснять проект заново, есть два механизма, и оба загружаются при старте разговора:

	CLAUDE.md	Auto memory (автопамять)
Кто пишет	вы	Claude
Что внутри	инструкции и правила	выводы из ваших поправок, предпочтения
Область	проект, пользователь или организация	один репозиторий (общая для всех worktree)
Загружается	каждую сессию, целиком (файл больше 4 МиБ пропускается)	каждую сессию, первые 200 строк или 25 КБ индекса
Для чего	стандарты кода, рабочие процессы, архитектура	ваши предпочтения, поправки, контекст, которого нет в коде

Важная оговорка из документации: и CLAUDE.md, и память — это контекст, а не жёсткая конфигурация. Claude воспринимает их как указания, а не как запрет. Если действие нужно именно заблокировать (например, принудительный push в основную ветку), для этого есть хуки PreToolUse и настройки permissions.deny — они срабатывают независимо от того, что решил Claude.

Где лежит файл и в каком порядке читается

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

Уровень	Путь	Для чего	Кто видит
Организация (managed)	macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md	стандарты компании, требования безопасности	все пользователи машины; отключить нельзя
Пользователь	~/.claude/CLAUDE.md	личные предпочтения для всех проектов	только вы
Проект	./CLAUDE.md или ./.claude/CLAUDE.md	архитектура, стандарты, рабочие процессы команды	команда через git
Локально в проекте	./CLAUDE.local.md	ваши адреса песочниц, тестовые данные; добавить в .gitignore	только вы, этот проект

Как происходит загрузка:

• Claude Code читает CLAUDE.md и CLAUDE.local.md из текущей папки и из всех папок выше неё. Запустили в foo/bar/ — подхватятся foo/bar/CLAUDE.md и foo/CLAUDE.md.
• Файлы не перекрывают друг друга, а склеиваются: от корня к рабочей папке. Внутри одной папки CLAUDE.local.md идёт после CLAUDE.md.
• CLAUDE.md в подпапках при старте не грузятся — они подключаются, когда Claude открывает файлы из этих подпапок.
• HTML-комментарии <!-- ... --> вырезаются до попадания в контекст: можно оставлять заметки для людей, не тратя токены. Комментарии внутри блоков кода сохраняются.
• Проверить, что именно загрузилось: команда /context в сессии, раздел «Memory files». Команда /memory показывает все места, где могут лежать файлы, и позволяет открыть их в редакторе.

Стартовый файл можно не писать руками: /init анализирует репозиторий и создаёт CLAUDE.md с командами сборки, тестов и найденными соглашениями. Если файл уже есть, /init предлагает правки, а не перезаписывает его. /init также умеет читать правила Cursor (.cursor/rules/, .cursorrules) и Copilot (.github/copilot-instructions.md) и переносить подходящее в CLAUDE.md.

Что писать в CLAUDE.md, а что — нет

Документация формулирует критерий просто: CLAUDE.md — это то, что вы иначе объясняли бы заново каждую сессию. Добавляйте строку, когда:

• Claude второй раз делает одну и ту же ошибку;
• код-ревью поймало то, что Claude должен был знать про этот репозиторий;
• вы печатаете в чат ту же поправку, что и в прошлой сессии;
• новому коллеге понадобился бы тот же контекст.

Оставляйте только факты, нужные в каждой сессии: команды сборки и тестов, соглашения, раскладка проекта, правила вида «всегда X». Чего в файле быть не должно:

• Многошаговые процедуры (как выкатить релиз, как прогнать миграцию) — это скилл: он загружается только когда нужен.
• Правила для одной части кода (например, только для API-обработчиков) — это .claude/rules/ с полем paths, чтобы правило грузилось при работе с такими файлами.
• Всё, что Claude и так видит в коде — структуру папок, названия функций, историю git. Это занимает контекст и ничего не добавляет.

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

Ниже — образец в духе документации: короткие разделы, проверяемые формулировки, без лишних слов. Подставьте свои команды и пути.

# Проект: веб-приложение (Next.js + Postgres)

## Команды
- Установка: `pnpm install`
- Dev-сервер: `pnpm dev` (порт 3000)
- Тесты: `pnpm test` — запускать перед каждым коммитом
- Линт: `pnpm lint --fix`

## Структура
- API-обработчики: `src/app/api/**/route.ts`
- Компоненты UI: `src/components/` (один компонент — один файл)
- Схема БД и миграции: `prisma/`

## Правила кода
- TypeScript strict, без `any`; для неизвестного типа — `unknown` + type guard
- Отступ 2 пробела, точки с запятой, одинарные кавычки
- Названия: camelCase для функций, PascalCase для компонентов

## Git
- Ветки: `feature/`, `fix/`, `refactor/`
- Коммиты на английском, в повелительном наклонении («Add», «Fix»)
- В `main` — только через PR, прямых пушей нет

## Что не делать
- Не менять `prisma/schema.prisma` без отдельного подтверждения
- Не коммитить `.env` и ключи

## Дополнительно
- Обзор проекта: @README.md
- Правила API: @docs/api-guidelines.md

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

6 правил из документации, чтобы файл работал

1. До 200 строк на файл. Чем длиннее CLAUDE.md, тем больше он съедает контекста и тем хуже Claude ему следует. Разросшийся файл делите: часть — в .claude/rules/ с привязкой к путям, часть — в скиллы.
2. Структура: заголовки и списки. Claude сканирует файл так же, как человек: разделы с маркерами читаются лучше, чем сплошной абзац.
3. Конкретика, которую можно проверить. «Отступ 2 пробела» вместо «форматируй код правильно»; «перед коммитом запускай npm test» вместо «тестируй изменения»; «обработчики API лежат в src/api/handlers/» вместо «держи файлы в порядке».
4. Без противоречий. Если два правила спорят, Claude выберет любое. Периодически перечитывайте основной файл, вложенные CLAUDE.md и .claude/rules/ и убирайте устаревшее. В монорепозитории чужие CLAUDE.md можно исключить настройкой claudeMdExcludes.
5. Правила для части кода — в .claude/rules/ с paths. Один файл — одна тема (testing.md, api-design.md). Файл с YAML-шапкой paths: ["src/api/**/*.ts"] загружается только когда Claude работает с такими файлами. Файлы без paths грузятся всегда, наравне с .claude/CLAUDE.md. Личные правила для всех проектов — в ~/.claude/rules/.
6. Личное — в CLAUDE.local.md или в импорте из домашней папки. Адреса песочниц, тестовые аккаунты, ваши привычки не должны попадать в общий репозиторий. CLAUDE.local.md добавляют в .gitignore; если работаете в нескольких worktree одного репозитория, удобнее импорт @~/.claude/my-project-instructions.md.

Если Claude не следует CLAUDE.md

Четыре частые причины из раздела «Troubleshoot» документации:

• Файл не загрузился. Проверьте /context, раздел «Memory files»: файл должен быть в списке. Если его нет — он лежит не там или исключён настройкой claudeMdExcludes.
• Файл слишком большой или расплывчатый. Сократите до фактов, процедуры вынесите в скиллы, узкие правила — в rules с paths.
• Есть конфликтующие инструкции между уровнями (личный файл против проектного, вложенные файлы). Найдите и оставьте одну версию.
• Инструкции «потерялись» после /compact. Корневой CLAUDE.md проекта сжатие переживает: после /compact Claude перечитывает его с диска. Пропадает то, что было сказано только в разговоре, лежит во вложенном CLAUDE.md подпапки или в правиле с paths, — они вернутся, когда Claude снова откроет соответствующие файлы. Инструкции из чата, которые должны жить долго, переносите в CLAUDE.md.

Отдельно про память: если Claude «помнит» что-то не то, откройте /memory — автопамять хранится в ~/.claude/projects/<проект>/memory/ как обычные markdown-файлы, их можно править и удалять. Отключить автопамять можно переключателем в /memory или переменной CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Из практики: файл на 54 КБ против файла на 12 КБ

В одном из наших проектов CLAUDE.md разросся до 54 КБ: туда попали процедуры публикации, чек-листы, история решений. Пересобрали по принципу из документации — в CLAUDE.md остались только факты и правила «всегда/никогда», процедуры ушли в скиллы, узкие правила — в отдельные файлы, история — в архив. Итог: 12 КБ, и файл стал тем, чем должен быть, — картой проекта, а не его летописью.

CLAUDE.md и AGENTS.md

• Если репозиторий уже использует AGENTS.md для других агентов, не дублируйте текст: создайте CLAUDE.md с одной строкой @AGENTS.md и добавьте ниже только то, что нужно именно Claude Code. Симлинк ln -s AGENTS.md CLAUDE.md тоже работает (на Windows проще импорт).
• Команда /import переносит в Claude Code конфигурацию другого агента: инструкции, MCP-серверы, команды, субагентов и скиллы (Claude Code v2.1.213 и новее).

Словарь

• Контекст (context window) — всё, что модель «видит» в текущем разговоре: ваши сообщения, файлы, инструкции.
• Скилл (skill) — отдельная папка с инструкцией для конкретной задачи; подключается, когда её вызывают или когда Claude решает, что она подходит.
• Worktree — дополнительная рабочая копия одного git-репозитория в отдельной папке.
• Монорепозиторий — один репозиторий с несколькими проектами или командами внутри.

Источники

• Claude Code Docs — How Claude remembers your project: https://code.claude.com/docs/en/memory
• Claude Code Docs — Best practices: https://code.claude.com/docs/en/best-practices