CLAUDE.md: как настроить инструкции для Claude Code — с готовым примером

Claude Code может разобраться в коде проекта, но часть рабочих правил в нём не видна. Например, почему письма клиентам нельзя отправлять из тестовой среды, какие каталоги генерируются автоматически и какой проверкой команда подтверждает исправление ошибки. Если эти условия приходится объяснять в каждой новой задаче, их стоит записать в CLAUDE.md.

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

• Документация Anthropic

Ниже — учебный пример для небольшого веб-проекта. Его нужно адаптировать к своим каталогам и командам: это заготовка инструкции, а не конфигурация, проверенная на вашем приложении.

Какие правила действительно стоит записать

Представьте задачу: добавить поле «Компания» в форму заявки. Для её выполнения агенту недостаточно знать, что проект написан на TypeScript. Ему полезно понять, где лежит форма, куда поступают данные и как проверить отправку без реального обращения в отдел продаж.

Хорошее правило помогает принять конкретное решение. Сравните формулировки:

Последний столбец не подходит любому репозиторию. Его ценность именно в привязке к устройству проекта. Если компонента TextField у вас нет, правило надо изменить, иначе инструкция сама станет источником ошибок.

Чтобы собрать первый вариант, вспомните последние замечания к работе агента. Какие из них пригодятся и в следующей задаче? Если замечание касалось только одной кнопки, оставьте его в текущем задании. Если оно касается всех форм, ему найдётся место в правилах проекта.

Где создать CLAUDE.md

Для командных правил используйте `CLAUDE.md` в корне проекта. Личные общие предпочтения можно хранить в `~/.claude/CLAUDE.md`. Файлы из вложенных каталогов подключаются, когда Claude читает находящиеся там файлы. Руководство по контексту проекта.

• Руководство по контексту проекта

Для первого знакомства достаточно простой структуры:

project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

Если CLAUDE.md уже существует, сначала прочитайте его. Второй набор похожих правил сложнее поддерживать: при смене команды тестирования легко обновить один файл и забыть другой.

Проверьте также точное имя файла. В редакторе с автоматически скрытыми расширениями можно случайно создать `CLAUDE.md.txt`.

Как получить первоначальный вариант

В открытой сессии Claude Code выполните `/init`. Команда помогает подготовить исходный CLAUDE.md на основе проекта. Полученный текст требует проверки: убедитесь, что команды существуют, пути актуальны, а ограничения соответствуют вашей работе. Такой порядок рекомендует руководство Anthropic.

• руководство Anthropic

Если хотите сначала увидеть предложение без изменения файлов, можно поставить задачу так:

Изучи README, команды в package.json и структуру каталогов. Предложи текст CLAUDE.md для этого проекта. Укажи команды запуска и проверки, важные границы изменений и особенности, которые нельзя уверенно вывести из кода. Неизвестное вынеси в вопросы. Пока не создавай и не меняй файлы.

У такого запроса есть конкретный результат: текст, который можно сверить с проектом. Не принимайте сгенерированную инструкцию только потому, что она выглядит аккуратно. Например, `npm test` бесполезен, если в проекте вообще нет этого скрипта.

Готовый пример CLAUDE.md для веб-проекта

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

# Проект

Сайт услуг с формой заявки. Интерфейс на русском и английском.
Главный пользовательский сценарий: выбрать услугу и отправить заявку.

## Где искать код

- src/components/forms/ — поля и формы.
- src/server/leads/ — обработка заявок.
- src/i18n/ — словари интерфейса.
- tests/leads/ — тесты обработки заявок.

## Команды

- npm run dev — локальный запуск.
- npm run typecheck — проверка типов.
- npm run test:leads — тесты обработки заявок.
- npm run build — сборка приложения.

## Правила изменений

- Используй существующие компоненты форм и обработчики ошибок.
- Тексты интерфейса храни в словарях обеих локалей.
- Не добавляй зависимость, если задача решается средствами проекта.
- Сохраняй чужие незавершённые изменения.

## Проверка

- При изменении заявки проверь обязательные поля, неверный email
  и успешную отправку на тестовый приёмник.
- Для изменений TypeScript запускай npm run typecheck.
- При изменении обработки заявок запускай npm run test:leads.
- Для изменений интерфейса проверь затронутый экран в браузере.
- Если проверка недоступна, укажи причину и оставшуюся неопределённость.

## Среда

- Для проверки отправки используй только тестовый приёмник.
- Названия необходимых переменных описаны в .env.example.
- Не вставляй значения секретов в код, отчёты и документацию.

## Отчёт

Кратко опиши изменение, выполненные проверки и оставшиеся проблемы.
Отделяй результат тестов от предположений о работе приложения.

Начните с проверки раздела «Команды». Затем убедитесь, что правила проверки выполнимы. Если тестового приёмника нет, инструкция не создаст его: сначала нужно подготовить тестовую среду или описать доступный способ проверки.

Необязательно сохранять все разделы. Для библиотеки вместо формы заявки будут важны публичные функции и совместимость. Для сайта со статьями — структура контента, метаданные и работа внутренних ссылок.

Как проверить, что инструкция помогает

Разделите проверку на два шага: загрузился ли файл и изменилось ли поведение агента.

Выполните `/context` и проверьте список Memory files. Затем дайте небольшую задачу с понятным результатом. Anthropic прямо рекомендует проверять загрузку файла через эту команду. Настройка CLAUDE.md.

• Настройка CLAUDE.md

Для учебного сайта выше подойдёт такая задача:

Добавь необязательное поле «Компания» в форму заявки. До изменения найди существующий компонент поля и обработчик отправки. После изменения проверь, что заявку можно отправить как с компанией, так и без неё. Перечисли проверки, которые действительно выполнил.

При просмотре результата ответьте на три вопроса:

1. Использовал ли агент предусмотренный компонент и словари переводов?
2. Сохранил ли отправку без необязательного поля?
3. Привёл ли результаты проверок, которые можно сверить с выводом инструментов?

Если один из пунктов нарушен, разберите причину. Возможно, правило двусмысленно. Возможно, в коде есть второй похожий обработчик. Возможно, тесты не покрывают нужный сценарий. Дописывать ещё один запрет стоит после того, как стало понятно, что именно пошло не так.

Для собственных наблюдений достаточно небольшой таблицы: задача, ожидаемое действие, фактический результат и изменение правила. Это предложенный способ проверки, а не отчёт об эксперименте. Один успешный запуск не доказывает, что инструкция будет выполняться без ошибок в дальнейшем.

Что делать, если Claude игнорирует CLAUDE.md

Сначала убедитесь, что нужный файл загружен. Затем найдите инструкции по той же теме в других файлах проекта. По документации, обнаруженные CLAUDE.md объединяются в контексте; вложенный файл не стоит воспринимать как автоматическую отмену всех предыдущих правил. Порядок загрузки.

• Порядок загрузки

После этого проверьте саму формулировку. «Тщательно тестируй» оставляет широкий выбор. «После изменения обработчика заявки запусти такую-то команду» задаёт действие, результат которого можно увидеть.

Другая возможная проблема — устаревшая инструкция. После переезда тестов или изменения структуры каталогов просмотрите связанные правила. Агенту трудно следовать документу, который описывает уже несуществующий проект.

Наконец, уберите повторения и общие пожелания. Anthropic советует хранить в CLAUDE.md краткие, применимые к проекту инструкции и пересматривать их по результатам работы. Универсального объёма, который гарантирует исполнение, нет. Рекомендации по содержанию файла.

• Рекомендации по содержанию файла

Когда нужны rules и Skills

По мере роста проекта разделяйте инструкции по назначению. В `.claude/rules/` можно хранить тематические правила, в том числе связанные с определёнными путями. Skills подходят для отдельных повторяемых процедур, которые нужны по ситуации. Правила проекта, навыки Claude Code.

• Правила проекта
• навыки Claude Code

Практический ориентир для нашего примера:

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

Почему CLAUDE.md не заменяет ограничения доступа

Фраза «не отправляй письма реальным клиентам» полезна как описание рабочего порядка. Но технический запрет доступа настраивается отдельно. В Claude Code для разрешений есть `/permissions` и правила allow, ask, deny; текст CLAUDE.md не меняет эти разрешения. Документация по доступам.

• Документация по доступам

Для примера с формой разумно подготовить среду, в которой тестовая отправка физически направляется в тестовый приёмник. Тогда правильность адресата не зависит только от того, как агент истолкует абзац инструкции.