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: рекомендации по CLAUDE.md

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

Изучи 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

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

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

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

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

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

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

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

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

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

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

Бывает, что инструкция просто устарела. Тесты переехали, структура каталогов изменилась — пересмотрите связанные правила. Агенту трудно следовать документу о проекте, которого уже нет.

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

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

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

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

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

Для нашего примера это выглядит так:

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

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

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

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

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