CLAUDE.md: как один файл объясняет ИИ правила твоего проекта

Первые недели с Claude Code у меня уходили по одному сценарию: каждую новую сессию я заново объяснял, каким менеджером ставятся зависимости, какой командой гоняются тесты и куда всё это деплоится. Агент угадывал и промахивался. Лечится одним текстовым файлом в корне репозитория.

Что это за файл

CLAUDE.md — обычный markdown, который Claude Code подхватывает автоматически при старте сессии в этой папке. Содержимое попадает в контекст ещё до твоего первого сообщения. Это брифинг для нового сотрудника, который приходит с нулём знаний о проекте и с идеальной памятью на один разговор.

Ключевое: файл читается всегда. Тебе не нужно на него ссылаться, копировать в промпт или напоминать о нём.

Три уровня

Глобальный — ~/.claude/CLAUDE.md. Правила, общие для всех проектов. У меня там лежит инструкция проверять доску GitHub Projects в начале сессии: агент сам смотрит, какие задачи висят, и избавляет меня от вопроса «чем займёмся».

Проектный — CLAUDE.md в корне репозитория. Коммитится вместе с кодом, работает у всех, кто клонировал репо.

Локальный — CLAUDE.local.md, в .gitignore. Личные пути, порты, временные костыли на твоей машине.

Уровни складываются: глобальные правила плюс проектные плюс локальные. Чем ближе файл к проекту, тем он конкретнее.

Шаблон, который я копирую в новый проект

# [Название проекта]

## Что это
[Одна строка — что делает проект]

## Стек
- [Язык, фреймворк, БД, ...]

## Команды
- Запуск: `[команда]`
- Тесты: `[команда]`
- Деплой: `[команда]`

## Деплой
- Где: [VPS / Vercel / ...]
- Домен: [если есть]
- CI/CD: [GitHub Actions / ручной / ...]

## Структура
[Краткое описание ключевых папок, только если не очевидно]

## Правила
Специфичные для проекта правила — в .claude/rules/

Заполняется за десять минут. Дальше файл живёт и правится по мере того, как ловишь агента на повторяющихся промахах.

Почему он такой короткий

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

Мой критерий отбора: в CLAUDE.md попадает то, что агент не может выяснить из кода за пару секунд. Команда деплоя, домен, договорённость про ветки — да. Список папок, который виден по ls, — мусор.

Второй критерий: правило появляется после того, как агент ошибся. Пиши по факту, не впрок.

Детальные правила — отдельными файлами

Разрастаться CLAUDE.md начинает быстро. Тематику я выношу в .claude/rules/:

• workflow.md — issue-driven процесс: задача сначала становится issue на доске, потом кодом
• machines.md — инфраструктура: что где стоит на Windows-компе, ноуте и Ubuntu-VPS

В самом CLAUDE.md остаётся строка-указатель на папку. Основной файл держится компактным, детали подгружаются по мере надобности.

Когда файл выручает вместо хуков

Хуки в settings.json — это код, который выполняется гарантированно. У меня на Windows они молча не срабатывают, заводятся только через плагины. Пока разбираюсь с причиной, нужное поведение переехало в CLAUDE.md обычной фразой на русском.

Работает, с оговоркой. Хук выполняется системой; правило в markdown исполняет модель — иногда она его пропускает. Для критичных вещей (запрет на push в main, автоформат перед коммитом) держи хук. Для «проверь доску при старте» текста хватает.

Как понять, что файл работает

Три проверки:

1. Начни сессию в проекте и спроси, какой командой запускаются тесты. Правильный ответ без чтения файлов — файл прочитан.
2. Считай повторы. Объясняешь одно и то же второй раз — это кандидат в CLAUDE.md.
3. Агент нарушил записанное правило дважды — проблема в формулировке. Меняй расплывчатое «пиши аккуратный код» на проверяемое «перед коммитом прогони npm test».

Стартовый черновик можно получить командой /init — Claude просканирует репозиторий и соберёт первую версию. Дальше правишь руками.

Что туда точно не класть

• Секреты, токены, пароли: файл уходит в git
• Пересказ кода — структуру классов, список эндпоинтов. Агент прочитает исходник быстрее
• Абстрактные пожелания вроде «пиши качественно»: они ни на что не влияют
• Куски документации фреймворка

Итог простой: пятнадцать строк в корне проекта убирают половину повторяющихся объяснений. Начни с шаблона и добавляй по одной строке каждый раз, когда ловишь себя на повторе.