CLAUDE.md для Claude Code: короткие правила, которые можно проверить

Project rules

Goal

• Keep changes limited to the requested feature.

Before editing

• Read package.json and the files named in the task.
• Do not read or print .env files.

Checks

• Run npm test after code changes.
• Run npm run lint when TypeScript files change.
• Report each command, its exit code, and every changed file path.

Scope and conflicts

• Rules in packages/payments/CLAUDE.md apply only under packages/payments/.
• Inside that directory, the local rule wins when it directly conflicts with this root file.
• Security and secret-handling rules in this root file always apply.

Forbidden

• Do not run deploy, publish, or destructive Git commands.
• Do not add API keys or personal data to the repository.

Этого достаточно для первого прохода. Команды, которых нет в `package.json`, не стоит добавлять «на будущее»: агент будет тратить время на несуществующую проверку.

Разделите цель, границы и стиль

Сначала выпишите четыре разных типа строк:

Фраза «пиши качественный код» не имеет наблюдаемого результата. Замените её на конкретный запрет или команду. Если правило нельзя проверить по diff, команде или файлу, перенесите его в раздел с пояснениями, а не выдавайте за обязательный контракт.

Не храните секреты в инструкциях

CLAUDE.md попадает в историю Git и читается агентом вместе с проектом. Поэтому в него нельзя помещать API Key, токены CI, реальные email-адреса, содержимое .env или скопированные ответы API. Напишите только границу:

- Never open, print, or commit `.env`, `*.pem`, or files under `secrets/`.
- Use the placeholder `API_KEY=your_api_key_here` in examples.

Если для теста нужен ключ, передайте его через окружение или секретное хранилище CI. Не просите Claude Code вставлять его в prompt или handoff.

Что делать при конфликте правил

Правило должно быть локальным настолько, насколько локальна его причина. Общие ограничения проекта держите в корневом CLAUDE.md, а требования конкретного пакета — рядом с этим пакетом. При конфликте сначала найдите все инструкции, которые видит Claude Code, и уберите дубликат; не пытайтесь решить конфликт ещё одним абзацем в корневом файле.

Практический порядок такой:

1. Откройте ближайший к изменяемому файлу CLAUDE.md и корневые инструкции.
2. Сверьте, нет ли двух разных команд для одной проверки.
3. Оставьте одно правило с более узкой областью действия.
4. Зафиксируйте приоритет в одной строке, если его нельзя выразить расположением файлов.

Например, в корневом файле можно написать: Rules in packages/payments/CLAUDE.md apply only under packages/payments/ and win there, except for root security rules. Это даёт локальному пакету конкретную область действия, но не позволяет отменить общий запрет на чтение секретов.

Подробное объяснение архитектуры, список исключений и справочные ссылки вынесите в docs/. В CLAUDE.md оставьте ссылку и команду, которой можно проверить актуальность.

Проверьте правило на маленькой задаче

Не начинайте с большого рефакторинга. Дайте Claude Code обратимую задачу, например переименовать локальную переменную в одном тестовом файле:

1. Запишите ожидаемый файл и запрет на остальные изменения.
2. Попросите агент изменить только этот файл.
3. Запустите git diff --check и git diff --stat.
4. Выполните тест, указанный в CLAUDE.md.
5. Отклоните результат, если изменился другой файл или не был показан код выхода команды.

Так вы проверяете именно правило, а не способность модели выполнить большой проектный план. После успешного малого теста можно расширять область, сохраняя те же наблюдаемые проверки.

Свяжите правила с вашим API workflow

Claude Code может работать через Anthropic-compatible API. Для отдельного workflow используйте собственный API Key и сверяйте текущие Base URL и модель с документацией BetterToken для Claude Code. BetterToken предоставляет API-доступ и Dashboard с данными использования; он не превращает CLAUDE.md в хранилище секретов и не заменяет настройки самого Claude Code.

Источники

• Memory в Claude Code
• Документация BetterToken для Claude Code