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.
Как проверить, что читается
- Впишите одно проверяемое правило — например, конкретный формат заголовков коммитов.
- Дайте задачу, где это правило применяется.
- Посмотрите, соблюдено ли без напоминания.
Не соблюдено — три причины по частоте: файл не в корне, правило сформулировано как пожелание («желательно»), или файл настолько длинный, что до правила дело не дошло.
Коротко
Один короткий файл в корне проекта, который читается сам. Держите его на экран: команды, соглашения, чего не делать. Всё, что относится к отдельным задачам, выносите в скиллы, а если в команде разные агенты — берите AGENTS.md вместо него.
Чем это отличается от механизмов у других инструментов — в сравнительном разборе.