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

CLAUDE.md — файл, в котором Клоду объясняют правила конкретного проекта: как он устроен, какими командами запускается, что здесь принято, а что нет. Читается автоматически, писать в него надо меньше, чем кажется.

Короткий ответ

Кладёте CLAUDE.md в корень проекта, пишете обычным текстом правила — Клод подхватывает его сам в начале работы. Просить не нужно, подключать тоже.

Главное правило: коротко. Файл читается при каждой задаче и расходует контекст. Инструкция на пять экранов работает хуже, чем на один: агент следует началу и выборочно — остальному.

Что туда писать

Проверенный минимум:

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

Одно-два предложения: что это и из чего состоит.

## Команды

- Разработка: npm run dev
- Тесты: npm test
- Сборка: npm run build

## Соглашения

- Комментарии по-русски, код по-английски
- Новые зависимости обсуждаем до установки
- Правки в конфигурации — отдельным коммитом

## Чего не делать

- Не коммитить напрямую в main
- Не менять формат данных без миграции
- Не трогать сгенерированные файлы

Этого достаточно. Всё, что специфично для отдельных задач, лучше выносить в скиллы — они подключаются только когда нужны и не висят в контексте постоянно.

Где он лежит

Основных мест два, и разница практическая:

В корне проекта — правила этого проекта, уезжают в репозиторий вместе с кодом. Приезжают ко всем, кто его клонирует.

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

Правило то же, что с уровнями конфигурации MCP: личное — в пользовательский файл, общекомандное — в проектный. Секреты — ни в тот, ни в другой: проектный лежит в репозитории, а личный легко попадает в бэкапы.

CLAUDE.md или AGENTS.md

Вопрос возникает сразу, потому что файлы делают одно и то же.

AGENTS.md — открытый формат, который читают Codex, OpenCode, Claude Code и OpenClaw. Один файл на разные инструменты.

CLAUDE.md — формат Клода. Работает только с ним, зато без оговорок про совместимость.

Практический выбор:

• Проект командный, агенты у людей разные — AGENTS.md. Прочитают все.
• Работаете один и только с Клодом — CLAUDE.md, разницы не почувствуете.
• Оба сразу — не надо. Два файла с пересекающимися правилами рано или поздно разойдутся, и агент получит противоречие.

CLAUDE.md и скиллы — разные роли

Их часто ставят в один ряд, хотя работают они по-разному.

CLAUDE.md читается всегда — это фон, общие правила проекта.

Скилл подключается по ситуации — когда агент видит, что задача подходит под его описание.

Отсюда способ делить: правило касается всей работы в проекте — в CLAUDE.md; правило про конкретный тип задачи — в скилл. Формат коммитов — в файл, инструкция по сборке недельного отчёта — в скилл.

Если сложить всё в CLAUDE.md, он раздуется и начнёт хуже работать именно как фон.

Почему длинный файл работает хуже

Неочевидная механика, из-за которой ломаются ожидания.

Файл читается при каждой задаче, то есть постоянно занимает часть контекста. Чем он длиннее, тем меньше места остаётся под саму работу — и тем выборочнее агент следует правилам.

Практический предел: один экран. Если не влезает, значит часть правил относится к конкретным задачам и им место в скиллах.

Что делать, когда контекст всё-таки переполняется, — разбор ошибки context overflow.

Как проверить, что читается

1. Впишите одно проверяемое правило — например, конкретный формат заголовков коммитов.
2. Дайте задачу, где это правило применяется.
3. Посмотрите, соблюдено ли без напоминания.

Не соблюдено — три причины по частоте: файл не в корне, правило сформулировано как пожелание («желательно»), или файл настолько длинный, что до правила дело не дошло.

Коротко

Один короткий файл в корне проекта, который читается сам. Держите его на экран: команды, соглашения, чего не делать. Всё, что относится к отдельным задачам, выносите в скиллы, а если в команде разные агенты — берите AGENTS.md вместо него.

Чем это отличается от механизмов у других инструментов — в сравнительном разборе.