CLAUDE.md для проекта: файл, из которого агент берёт правила

Каждая новая сессия агента начинается с чистого листа. Он заново гадает, чем запускать тесты, куда деплоится проект и какая тут база. Вы объясняете. Через день объясняете снова. CLAUDE.md закрывает именно эту дыру.

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

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

Уровней два, и они складываются:

• Глобальный — ~/.claude/CLAUDE.md. Общие правила для всех проектов на машине: как вы работаете, где ведёте задачи, что проверить при старте.
• Проектный — CLAUDE.md в корне репо. Специфика конкретного кода. Лежит в git, едет вместе с проектом, работает у всех, кто его клонирует.

У меня глобальный отвечает за процесс: issue-driven воркфлоу и проверка доски в GitHub Projects при старте сессии. Проектный — только за факты о коде. Такое разделение держит оба файла короткими.

Шаблон, который можно скопировать

Кладите в корень как CLAUDE.md и заполняйте:

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

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

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

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

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

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

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

Самый ценный блок здесь — «Команды». Агент перестаёт угадывать между npm test, pnpm test и make test и просто берёт вашу строку.

Блок «Структура» заполняйте с оговоркой «только если не очевидно». Стандартный src/, tests/, docs/ агент разберёт сам за пару секунд. Описывать стоит странности: почему логика лежит в двух местах, какая папка мёртвая, где генерируемый код трогать руками запрещено.

Чего в файл лучше не класть

• Секреты. Файл лежит в git. Токены и пароли — мимо.
• Пересказ дерева папок. Дублирование того, что читается инструментами, съедает контекст без пользы.
• Абстрактные пожелания вроде «пиши чистый код». Пустая строка в промпте.
• Простыни на 300 строк. Чем длиннее файл, тем хуже он соблюдается. Правило в конце файла на сотню пунктов имеет мало шансов сработать.

Полезный критерий: если строку можно проверить (команда запустилась, файл создан в нужной папке) — она рабочая. Если строку нельзя проверить — она украшение.

Правила выносите в отдельные файлы

Когда проектных договорённостей становится много, CLAUDE.md распухает. Лечится папкой .claude/rules/ — по файлу на тему, а в CLAUDE.md остаётся ссылка на неё.

У меня так живут два файла: workflow.md с issue-driven процессом (задача → issue → ветка → PR) и machines.md с описанием инфраструктуры, потому что я работаю с трёх машин под Windows и Ubuntu, и пути с командами там разные. Агент читает нужный файл по ситуации, вместо того чтобы держать всё сразу.

Правило вместо хука: где проходит граница

Часть автоматизации логичнее вешать на хуки в settings.json — они выполняются гарантированно, потому что их запускает не модель. Но у меня хуки из settings.json на Windows не срабатывают, работают только через плагины. Пришлось обойти: нужное поведение — проверка доски при старте сессии — переехало строкой в глобальный CLAUDE.md.

Разница честная. Хук — это гарантия. Строка в CLAUDE.md — просьба, которую агент выполняет в большинстве случаев. Для проверки доски такой надёжности достаточно. Для чего-то критичного вроде запрета на пуш в main я бы искал способ сделать хук.

Держите файл живым

CLAUDE.md стареет быстрее кода. Поменяли команду деплоя — файл врёт, и агент уверенно делает не то. У меня работает простое правило: заметил, что объясняю агенту одно и то же второй раз — иду и дописываю строку. Заметил, что строка устарела — удаляю. Файл растёт от реальных граблей.

Отдельно веду pinned issue, где обсуждаю сам фундамент: что в глобальном файле, что в rules, что сломалось. Это удобнее, чем вспоминать по памяти, зачем полгода назад появилась странная строчка.

С чего начать сегодня

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