Claude Code — CLAUDE.md как правильно

CLAUDE.md - это просто markdown файл. Выглядит невинно. Но я переписывал его достаточно раз чтобы знать: разница между «файл есть» и «файл реально работает» - огромная.

Где живёт CLAUDE.md и кто кого перекрывает

Claude Code при запуске идёт вверх по дереву папок и собирает все CLAUDE.md которые найдёт. От широкого к специфичному:

Managed policy - /Library/Application Support/ClaudeCode/CLAUDE.md на macOS. Enterprise уровень. Большинство разработчиков никогда не увидят этот файл - да и хорошо.

User global - ~/.claude/CLAUDE.md. Загружается в каждой сессии для любого проекта. Сюда идут личные правила которые всегда работают: «никогда не запускать rm -rf без подтверждения», «использовать gh CLI для GitHub». Всё что ты хочешь везде и всегда.

Project root - ./CLAUDE.md. Самый частый случай. Коммитишь в репо, вся команда видит. Содержит стек, команды сборки, конвенции. Есть ещё альтернатива ./.claude/CLAUDE.md - выбери одно из двух. Если используешь оба - Claude загрузит любой который найдёт первым. Гарантированный сюрприз.

Local project - ./CLAUDE.local.md. Личные настройки которые не хочешь пушить в репо. Добавь в .gitignore самостоятельно - автоматически не добавится.

Subdirectory files - packages/api/CLAUDE.md. Не загружаются сразу. Claude читает их только когда начинает работать с файлами в той директории. Именно так монорепозитории становятся управляемыми - фронтенд и бэкенд живут по своим правилам не засоряя корневой файл.

Правило простое: более специфичный побеждает. Но не жди что конфликты разрешатся красиво - держи каждый файл в своей области ответственности и не допускай пересечений.

Когда файл вырос - разбивай его

Маленький сервис - 15 строк в CLAUDE.md. Реальный проект через полгода - что-то совсем другое. Для этого есть синтаксис @:

# Project overview
See @README.md for architecture details.

# Code conventions
@docs/coding-standards.md

Claude заменяет каждый @path содержимым файла при загрузке. Основной файл остаётся коротким - Claude получает всё.

Одна ловушка: первый раз когда Claude Code встречает внешние импорты - показывает диалог подтверждения. Если случайно откажешь - импорты останутся отключены навсегда и диалог не вернётся. Будь внимателен.

Ещё одна мелочь: уровни заголовков в импортируемых файлах не корректируются автоматически. Был GitHub issue об этом - закрыт как "not planned". Так что слежу за заголовками сам. 🙂

Path-Scoped Rules - правила для конкретных папок

Для больших проектов есть директория .claude/rules/:

.claude/rules/
├── api-conventions.md
├── testing.md
├── migrations.md
└── frontend.md

Каждый файл может иметь globs в frontmatter - и тогда правила применяются только к файлам соответствующим паттерну:

---
globs: src/api/**/*.ts
---

# API conventions
- Все конечные точки должны проверять входные данные с помощью схем Zod.
- Используйте стандартный формат ответа об ошибке из src/api/errors.ts.
- Никогда не возвращайте необработанные объекты базы данных - всегда сопоставляйте их с DTO.

Важный момент: в документации раньше было написано что поле называется paths:. На практике работает только globs:. Потратил реальное время на отладку прежде чем нашёл GitHub issue с этим. Используй globs: - и всё будет работать. Запусти /memory чтобы проверить что реально загрузилось - сбои тут молчаливые.

Типичные ошибки

Раздутый файл

Это происходит с каждым проектом. Команда начинает с десяти строк. Через полгода - 400 строк, и Claude игнорирует половину из них.

Anthropic сами пишут что файлы длиннее 200 строк снижают соблюдение инструкций. Проблема не в объёме памяти - во внимании. Чем больше текста в начале сессии - тем хуже Claude следует любому конкретному правилу.

Вот как выглядит раздутый файл:

# Project overview
Это приложение Next.js, созданное с использованием TypeScript и Tailwind CSS.
По возможности мы используем React Server Components.
Разработка приложения началась в 2025 году, и с тех пор оно значительно разрослось.
В нашей команде 5 разработчиков, работающих в двух часовых поясах.
Наш менеджер по продукту - Лена, а технический руководитель - Иван.

Claude не нужно знать кто такая Лена. Срезай до:

# Project
Next.js 16, строгий режим TypeScript, Tailwind, компоненты React Server по умолчанию.

Одна строка. Всё что нужно.

Простой тест для каждой строки: если удалить эту строку - Claude сделает ошибку? Если нет - удаляй.

Правила запрещающие то чего Claude и так не делает

Видел файлы где половина правил выглядит вот так:

- Никогда не используйте `var`, всегда используйте `const` или `let`.
- Всегда используйте стрелочные функции для коллбэков.
- Никогда не используйте `any type`, используйте `unknown` вместо `unknown`.

Claude и без этого делает всё правильно. Двадцать таких правил просто съедают место для того что реально важно. Пиши правила только для проблем которые реально видел - не для воображаемых.

Конфликты между файлами

Глобальный файл говорит «использовать Prettier». Проектный говорит «использовать ESLint для форматирования». Нет никакого сообщения об ошибке. Claude просто выберет одно из двух - и ты не знаешь какое.

Относись к иерархии как к коду - проверяй конфликты когда добавляешь новые правила.

CLAUDE.md это не конфиг

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

Добавление IMPORTANT: или YOU MUST помогает - но не даёт гарантий. Если везде написано IMPORTANT - Claude не знает что из этого реально важно. 😄

Жёсткие стопы - в settings.json permissions, в линтере или в pre-commit хуке. Не в markdown файле.

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

Команды сборки и тестов - самое ценное. Как собрать проект, запустить тесты, сделать lint.

Неочевидная архитектура - то что нельзя вывести из кода. «Весь доступ к базе - через /src/repositories.» «Папка /legacy заморожена - не трогать.»

Конвенции которые отличаются от стандартных - только там где проект делает что-то необычное.

Gotchas - вещи которые уже стоили тебе времени. «Auth модуль использует кастомную JWT библиотеку - не jsonwebtoken.»

История проекта, обоснование решений и бизнес-логика - не сюда. Для этого есть комментарии в коде и ADR документы.

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

Клавиша # во время сессии. Поймал Claude на ошибке - нажми # и добавь правило прямо в разговоре не выходя из него. Anthropic называет это «compounding engineering» - каждая коррекция становится постоянным контекстом.

Сессия отладки = сигнал для обслуживания файла. Если Claude нарушает правило которое ты точно написал - файл скорее всего слишком длинный и правило потерялось в шуме. Не добавляй ещё одно правило сверху. Зайди и убери устаревшее.

Для нового проекта - запусти /init. Claude Code просканирует кодовую базу и сгенерирует стартовый CLAUDE.md. Результат обычно verbose - агрессивно сокращай. Но это лучше чем чистый лист.

Итог

CLAUDE.md - не магический файл который делает Claude умнее. Это onboarding документ который ты пишешь один раз для инструмента который начинает каждую сессию с нуля.

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

Идеального файла не существует - существует достаточно хороший который не мешает работе. 🛠️