Файл правил проекта для ИИ: что писать в CLAUDE.md и что выбросить

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

Без него вы объясняете одно и то же в каждой новой сессии. С ним — один раз.

Главное ограничение

Файл висит в контексте всегда, даже когда вы просите поправить одну строчку в CSS. Каждая лишняя строка стоит денег и внимания модели. Мой рабочий ориентир для проектного файла — 30–60 строк. Что не влезло, уезжает в отдельные файлы правил и подгружается по необходимости.

Отсюда главный фильтр при написании: «понадобится ли это в большинстве сессий?». Нет — вычёркиваем.

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

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

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

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

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

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

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

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

Кладёте в корень как CLAUDE.md, заполняете за десять минут.

Разбор по разделам

Что это. Одна строка. Модель должна понимать, с чем имеет дело: телеграм-бот, лендинг, парсер выдачи. От этого меняется тон предложений и выбор решений.

Стек. Спасает от угадывания. Иначе ассистент честно предложит вам решение под другой фреймворк — просто потому, что нужных файлов в проекте пока не видно.

Команды. Самый полезный раздел. Ассистент постоянно хочет что-то запустить и проверить. Нет записанной команды запуска — он начнёт перебирать варианты из package.json или дёргать вас вопросами. Пишите точные строки, которые сами набираете в терминале.

Деплой. Куда уезжает код, есть ли CI. Хватит трёх строк. Спасает от совета vercel deploy там, где стоит обычный VPS с systemd.

Структура. Только если она неочевидна из названий папок. Стандартный Next.js описывать незачем, ассистент видит его сам.

Правила. Ссылка на модульные файлы. Сам список правил в главный файл не тащим.

Чего в файле быть не должно

• Пересказ дерева каталогов. Ассистент прочитает его быстрее, чем вы напишете.
• Токены, пароли, ключи. Файл лежит в git и уедет в репозиторий.
• Общие пожелания в духе «пиши чистый код» и «следуй best practices». Пустые строки контекста.
• Документация проекта. Для этого есть README, у него другой читатель — человек.
• Устаревшие команды. Неверная информация вреднее её отсутствия: ассистент уверенно сделает неправильное.

Два уровня: глобальный и проектный

Когда я приводил в порядок окружение на трёх машинах (комп, ноут, VPS), разделение вышло такое.

Глобальный ~/.claude/CLAUDE.md — оглавление и критические правила, 30–50 строк. Рядом модули: rules/workflow.md с процессом работы через issues, rules/machines.md с описанием инфраструктуры. Туда же хуки: session-start.sh подтягивает задачи в статусе In Progress при старте сессии.

Проектный CLAUDE.md держит только специфику конкретного репозитория. Всё общее живёт наверху и не дублируется.

Весь набор конфигов лежит в отдельном приватном репозитории claude-config и раскатывается на машины. Один источник правды вместо трёх расходящихся копий.

Модульные правила

Папка .claude/rules/ — место для длинных инструкций: соглашения по коммитам, схема базы, стиль текстов, порядок релиза. Каждая тема — отдельный файл. В CLAUDE.md остаётся строка-указатель.

Выигрыш простой. Главный файл не разрастается. Тяжёлые правила подтягиваются тогда, когда до них дошло дело.

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

Проверка первая: откройте новую сессию и дайте типовую задачу. Ассистент спрашивает то, что уже написано в файле, — формулировка нечёткая. Начал искать команду запуска — раздел «Команды» заполнен плохо.

Проверка вторая, регулярная. После каждого «опять пришлось объяснять то же самое» дописывайте одну строку. Файл растёт от реальных сбоев, и в этом его ценность.

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

Возьмите шаблон выше, положите в корень активного проекта, заполните «Что это», «Стек» и «Команды». Остальное дописывайте по мере того, как будете спотыкаться. Три заполненных раздела уже дают заметную разницу в первой же сессии.