CLAUDE.md: как объяснить Claude Code устройство проекта и команды проверки

Разработчик открывает Claude Code для небольшой правки кабинета заказов. В одном сеансе приходится заново объяснять, что экран находится в apps/web, расчёт — в services/orders, общий формат ответа — в packages/contracts. Через неделю это объяснение повторяется. Такие устойчивые сведения лучше хранить рядом с проектом, чтобы они попадали в контекст новых сеансов.

Файл CLAUDE.md предназначен для проектных инструкций Claude Code. В него полезно помещать расположение ключевых частей кода, реальные команды проверки и правила, которые невозможно уверенно вывести из пары открытых файлов. Он не заменяет постановку текущей задачи: просьба «исправить округление в заказе O-17» относится к конкретному сеансу, а расположение тестов пригодится многим задачам.

Короткий файл для конкретного проекта

Представим монорепозиторий магазина с тремя пакетами. В корне можно положить такой CLAUDE.md. Названия путей и скриптов здесь относятся к примеру: перед использованием замените их на пути и команды своего репозитория. Смысл файла — дать агенту карту и способ доказать результат, а не длинную энциклопедию архитектуры.

# Проект: кабинет заказов

## Где искать код
- apps/web/src/orders/ — экран заказа и вызовы API.
- services/orders/src/ — расчёт и выдача заказа.
- packages/contracts/src/order.ts — общий формат ответа.

## Как менять существующее поведение
- Сначала проследи путь от экрана до обработчика API.
- Если меняется поле ответа, проверь общий контракт и оба потребителя.
- Не обновляй зависимости в задаче об одном обработчике.

## Проверка
- Веб: pnpm --filter @shop/web test
- Сервис: pnpm --filter @shop/orders test
- Перед сдачей назови изменённые файлы и результат обеих команд.

Первая секция помогает найти связанные части изменения. Вторая просит проследить путь данных перед правкой: если меняется поле ответа API, надо посмотреть его общий тип и потребителей. Третья содержит точные команды, которые команда проекта действительно использует для проверки. В собственном файле проверьте имена пакетов по package.json и запустите команды сами хотя бы один раз: устаревшая инструкция направит агента к ложному «зелёному» результату.

Где файл действует и как это проверить

Claude Code читает CLAUDE.md в рабочем каталоге и каталогах выше него при запуске. Поэтому корневой файл удобен для правил, общих для всего репозитория. Файл внутри services/orders/CLAUDE.md относится к этому участку: он подгружается, когда Claude читает или меняет файлы в каталоге. Это место для правил сервиса, например команды его контрактных тестов. Вложенный файл добавляется к общему контексту, а не стирает корневой. Противоречивые инструкции лучше исправить в файлах, чем надеяться на порядок их чтения.

После добавления корневого файла откройте новый сеанс в нужном каталоге и выполните /context: в списке Memory files должен появиться путь к CLAUDE.md. Для вложенного файла попросите Claude открыть файл из соответствующего каталога и проверьте сообщение о загрузке; он не обязан присутствовать в стартовом списке. Затем дайте небольшую задачу и проверьте обычным ревью, что агент нашёл нужные файлы и выполнил указанные команды. Наличие файла в контексте ещё не доказывает правильность правки.

Храните в корневом файле то, что действительно повторяется от задачи к задаче. Одноразовые пути, временные гипотезы и огромные перечни файлов быстро устаревают. Если правила касаются только одного каталога, перенесите их ближе к нему. Секреты, токены и личные URL не относятся к общему проектному файлу. Для требования, которое нужно технически запретить, одного текста инструкции недостаточно: Claude воспринимает CLAUDE.md как контекст, а не как механизм принудительного контроля.

Это отличается от ситуации, когда агент уже выбрал не тот модуль при конкретном баге. Тогда всё равно надо проследить реальный путь от пользовательского действия до обработчика. CLAUDE.md экономит повторное объяснение устройства проекта и команд, а доказательство для текущей правки остаётся в diff и тестах.

В платном курсе Vibecoding: Claude Code, Codex, Cursor и agentic development студент отрабатывает передачу контекста кодовой базы, проектные rules, постановку задачи и проверку изменений на существующем коде. Открытый урок «Rules и проектные инструкции» поможет начать с файла, а дальнейшая практика — связать его с тестами и ревью diff. Откройте программу и пробный урок.

По соседним задачам пригодятся разбор выбора неверного модуля, сужение чрезмерного diff и другие материалы по AI-разработке.