CLAUDE.md, который действительно работает

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

Что это и как загружается

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

Проверить, что файл загрузился, можно командой /context: в списке Memory files должны быть все ваши CLAUDE.md. Если файла там нет, Claude его не видит, сколько бы вы ни спрашивали, «почему ты не следуешь правилам».

Иерархия файлов

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

Файлы не переопределяют друг друга, а склеиваются: все найденные загружаются в контекст по порядку, и тот, что ближе к рабочей папке, читается последним. Если вы запустили Claude в apps/web/, загрузятся CLAUDE.md из корня репозитория и из apps/web/. А CLAUDE.md в подпапках ниже рабочей загружаются по требованию — когда Claude начинает читать файлы в этих подпапках.

Для агентства это означает удобную схему: в корне монорепозитория — общие правила (стек, ветки, как оформлять PR), в apps/mobile/CLAUDE.md — особенности мобильного приложения, в packages/ui/CLAUDE.md — правила дизайн-системы. Разработчик, работающий над мобильным приложением, не тратит контекст на правила бэкенда.

Если в большом монорепозитории родительские CLAUDE.md других команд мешают, их можно исключить настройкой claudeMdExcludes в .claude/settings.local.json — по пути или glob-шаблону.

Что писать, а что нет

Ключевая мысль из документации: CLAUDE.md загружается в каждую сессию и расходует контекст. Поэтому для каждой строки задайте вопрос: «если её убрать, Claude начнёт ошибаться?» Если нет — убирайте. Раздутый CLAUDE.md приводит к тому, что Claude игнорирует и важные правила, потому что они теряются в шуме. Ориентир — до 200 строк на файл.

Что стоит включать:

• команды, которые нельзя угадать по коду: pnpm test:unit -- --run, а не просто «запускай тесты»;
• стиль, отличающийся от умолчаний языка: «ES-модули, не CommonJS», «2 пробела»;
• как устроен репозиторий: именование веток, формат PR, кто ревьюит;
• архитектурные решения, специфичные для проекта: «обработчики API лежат в src/api/handlers/»;
• особенности окружения: обязательные переменные, локальный Redis для интеграционных тестов;
• неочевидные грабли: «npm run build без NODE_OPTIONS=--max-old-space-size=4096 падает».

Чего включать не стоит:

• всё, что Claude узнает, прочитав код: описание файлов, список зависимостей, обзор архитектуры;
• стандартные соглашения языка, которые модель и так знает;
• подробную документацию API — дайте ссылку;
• то, что часто меняется;
• «пиши чистый код» и прочие само собой разумеющиеся вещи.

Инструкции должны быть конкретными, чтобы их можно было проверить. «Форматируй код правильно» — плохо. «Перед коммитом запускай pnpm lint && pnpm typecheck» — хорошо. Если Claude упорно пропускает одно правило, выделите только его словом «ВАЖНО». Если выделить все — не сработает ни одно.

Когда файл вырос, /doctor предлагает сокращения: он вычёркивает то, что Claude может вывести из кода, и оставляет грабли, обоснования и соглашения, которые отличаются от умолчаний.

Пример для проекта агентства

Вот CLAUDE.md для веб-проекта на Next.js, в котором каждая строка отвечает на вопрос «без неё Claude ошибётся?»:

# Проект: личный кабинет клиента

## Команды
- Установка: `pnpm install` (не npm, lock-файл только pnpm)
- Тесты: `pnpm test` — unit, `pnpm test:e2e` требует запущенный `pnpm dev`
- Проверка перед коммитом: `pnpm lint && pnpm typecheck`

## Стиль
- Компоненты — функции, без классов; стили только через токены из `@acme/ui`
- Импорты через алиас `@/`, относительные пути глубже одного уровня запрещены

## Репозиторий
- Ветки: `feature/<номер-задачи>-кратко`, PR в `develop`, `main` только релизы
- Не редактировать `src/generated/` — генерируется из OpenAPI командой `pnpm codegen`

## Грабли
- Интеграционные тесты падают без `REDIS_URL`; локально это `redis://localhost:6379`
- При сжатии контекста сохраняй список изменённых файлов и команды проверки

Заметьте, чего здесь нет: описания папок, объяснения, что такое Next.js, и списка зависимостей — всё это Claude прочитает сам.

Импорты

CLAUDE.md может подключать другие файлы синтаксисом @путь/к/файлу. Импортированные файлы разворачиваются и загружаются вместе с CLAUDE.md при старте. Пути — относительно файла, в котором стоит импорт; вложенные импорты допустимы до четырёх уровней.

Обзор проекта — в @README, доступные скрипты — в @package.json.

# Дополнительно
- Работа с git: @docs/git-workflow.md

Чтобы упомянуть путь без импорта, возьмите его в обратные кавычки: `@README` останется текстом. Импорты внутри блоков кода тоже не срабатывают.

Два практических применения. Если репозиторий уже использует AGENTS.md для других агентов, не дублируйте: в CLAUDE.md пишете @AGENTS.md, а ниже — специфичное для Claude. И если вы работаете в нескольких worktree одного репозитория, личный CLAUDE.local.md есть только в одном из них; вместо него импортируйте файл из домашней папки: @~/.claude/my-project.md. Первый импорт за пределы рабочей папки Claude Code попросит подтвердить — это защита от файлов, которые кто-то закоммитил в общий проект.

Импорты помогают организовать текст, но не экономят контекст: всё импортированное загружается при старте.

Правила по путям: .claude/rules/

Когда инструкций много, их удобнее разложить по темам в папке .claude/rules/: testing.md, api-design.md, security.md. Файлы без дополнительной разметки загружаются при старте наравне с CLAUDE.md.

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

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

# Правила для API
- Каждый обработчик валидирует вход через zod-схему из `src/api/schemas/`
- Ошибки возвращаются в стандартном формате `{ error: { code, message } }`

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

Как поддерживать файл

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

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

Просматривать файл нужно регулярно: искать противоречия (если два правила спорят, Claude выберет любое), удалять устаревшее, проверять, что изменения действительно меняют поведение. Быстро добавить правило можно, попросив Claude: «добавь это в CLAUDE.md». Команда /memory открывает файлы для правки.

Отдельно про автопамять. Помимо CLAUDE.md, который пишете вы, Claude ведёт собственные заметки в ~/.claude/projects/<проект>/memory/: ваши поправки, предпочтения, решения, которые нельзя вывести из кода. Эти заметки локальны для вашей машины и в git не попадают. Если вы говорите «запомни, что мы используем pnpm», это уходит именно туда. Для командных правил просите добавить в CLAUDE.md явно.