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

Большой файл с пожеланиями не делает работу Claude Code предсказуемой. Рабочее правило должно отвечать на три вопроса: что агент делает, чего не делает и какой командой человек проверит результат. Если workflow использует API, откройте актуальную инструкцию BetterToken для Claude Code, настройте собственный API Key и выполните короткую проверку: в Dashboard должны появиться ожидаемые модель, status и расход токенов. Ключ храните в окружении, а не в CLAUDE.md.

Ниже — минимальный CLAUDE.md для проекта, где агент меняет TypeScript-код, но не должен трогать секреты и запускать публикацию:

## 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, не стоит добавлять «на будущее»: агент будет тратить время на несуществующую проверку.

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

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

Тип	Проверяемая формулировка	Что считать успехом
Цель	«Добавить endpoint для чтения профиля»	Меняется только нужный модуль, запрос отвечает 200
Граница	«Не менять миграции и публичный API»	git diff --stat не содержит этих файлов
Проверка	«После изменения запустить npm test»	Команда завершилась с кодом 0
Стиль	«Использовать существующие имена функций»	Нет новых синонимов и лишнего рефакторинга

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

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

Если CLAUDE.md отслеживается и коммитится, он попадает в историю Git; Claude Code также читает его как проектную инструкцию. Поэтому в него нельзя помещать 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.

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

Актуальная документация Memory определяет, как Claude Code обнаруживает инструкции разной области. Правило «локальное требование действует в пакете, но не отменяет корневую безопасность» ниже — выбранный контракт этого проекта, а не универсальное встроенное исключение 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. Отклоните результат, если изменился другой файл или не был показан код выхода команды.

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

Источники

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