CLAUDE.md, которому Claude действительно следует в каждой сессии

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

Где лежит файл

Положите его в корневую папку проекта, прямо рядом с README:

my-project/
 - CLAUDE.md
 - README.md
 - package.json
 - src/
 - tests/

Закоммитьте его в Git, чтобы коллеги получали те же указания. Другое допустимое место — .claude/CLAUDE.md.

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

my-project/
 - CLAUDE.md
 - src/
   - frontend/
     - CLAUDE.md
   - backend/
     - CLAUDE.md

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

Замените благие намерения конкретикой

Инструкция, очевидная для вас, для агента может оказаться размытой. Такие строки звучат разумно:

• Пиши чистый код
• Следуй лучшим практикам
• Тестируй тщательно
• Сохраняй единообразие архитектуры

Но посмотрите на них глазами агента. Что значит «тщательно» в этом репозитории? Какие именно лучшие практики? Вы знаете, что имели в виду, а агенту приходится гадать, пока вы этого не скажете.

Вот как то же намерение выглядит для API на TypeScript:

• Обработчики маршрутов лежат в src/routes/.
• Запросы к базе данных живут в src/repositories.
• Тела запросов проверяются уже существующими схемами Zod.
• Ошибки отправляются через src/lib/api-error.ts.
• При исправлении бага добавляй регрессионный тест, воспроизводящий описанный сбой.

Это решения, а не пожелания, и агент может им следовать.

Перечислите настоящие команды

В проекте могут быть модульные, интеграционные и браузерные тесты и несколько способов запустить приложение. Фраза «запускай тесты после каждой правки» не говорит агенту, какие из них запускать. Представьте проект на pnpm и Vitest. Можно написать раздел с командами и указать, что они запускаются из корня репозитория:

• Установка зависимостей: pnpm install.
• Запуск dev-сервера: pnpm dev.
• Проверка типов: pnpm typecheck.
• Однократный прогон модульных тестов: pnpm exec vitest run.
• Прогон одного файла: pnpm exec vitest run <test-file>.

Каталог, из которого запускается команда, и любые предварительные условия важны не меньше самой команды. Запустите каждую сами, прежде чем добавлять. Скопированная команда, которая уходит в режим наблюдения или требует сервиса, о котором никто не написал, лишь подкинет новую проблему.

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

Запишите особенности, похожие на ошибки

Именно здесь файл отрабатывает своё место. Допустим, ваш API хранит деньги в целых центах, так что $19.99 проходит через систему как 1999. Без этого знания безобидная на вид правка может привести к несогласованным значениям. Хорошая заметка описывает и правило, и точку переиспользования:

• Суммы в API и базе данных — целые центы.
• Переводит в отображаемую валюту только UI, и делать это нужно через существующую formatMoney() в src/lib/money.ts.

Или, допустим, старый мобильный клиент зависит от странного поведения. Запись о совместимости может сообщать, что POST /subscriptions возвращает HTTP 200 на повторные запросы, что старые мобильные клиенты на это полагаются и что так должно остаться, если только задача явно не меняет контракт API. Последняя оговорка важна. Она оставляет место для намеренных изменений, чтобы историческая заметка не превратилась в необъяснимое правило, которое никто не может пересмотреть.

Одна строка о том, зачем что-то существует, может остановить ненужное «исправление».

Превратите повторяющиеся поправки в указания

Представьте, что Claude подключает новую библиотеку для дат, хотя в проекте уже есть общий форматтер. Можно сказать: «Не добавляй лишних зависимостей». Проблема в том, что в следующий раз вы будете спорить, что считать «лишним».

Более сильная версия называет проверку, указывает на код и объясняет путь для исключений:

• Прежде чем добавить зависимость времени выполнения, поищи в package.json и src/lib/ то, что уже решает задачу.
• Для дат используй src/lib/date.ts.
• Если новый пакет действительно нужен, объясни, с чем не справляются существующие инструменты.

Но будьте разборчивы. Одна странная задача не всегда оправдывает постоянное правило. Неплохая проверка — будет ли эта поправка важна через месяц.

Не держите там краткосрочную работу

Некоторые заметки устаревают в тот же день, когда написаны:

Представьте заметку вроде «сегодня занимаемся багом в оформлении заказа, сломанный аккаунт — test-user-42, сначала увеличь таймаут».

Если она останется в CLAUDE.md после исправления бага, она собьёт с толку одну из будущих сессий. Держите инструкции под конкретную задачу в отдельных файлах. Claude Code также поддерживает правила с привязкой к путям внутри .claude/rules/, и это подходит для указаний, которые касаются только отдельных частей дерева.

Шаблон для начала

Начните с основ, которые нужны ассистенту, прежде чем трогать ваш код: назначение проекта, команды запуска, принятые в команде соглашения и способ проверить результат. Этот каркас покрывает всё перечисленное, а детали заполняете вы:

Project overview
 - Briefly explain what this project does and its main technologies.

Useful commands
 - Set up the project: [command]
 - Run locally: [command]
 - Run tests: [command]
 - Check formatting and linting: [command]

Mention where to run these commands and any required setup.

Where things live
 - Point to the main source code, tests, and important documentation.
 - Include locations that may be difficult to find or easy to confuse.

Project conventions
 - Describe the patterns to follow and existing helpers to reuse.
 - Focus on decisions that aren't obvious from reading the code.

Things to watch out for
 - Explain unusual behavior that must be preserved.
 - Identify generated files and how they should be updated.
 - Give a short reason for each restriction.

Checking changes
 - Explain how to choose and run the relevant checks.
 - Ask Claude to report what it checked and anything it couldn't verify.

Заполнять каждый раздел не обязательно. Если разделу нечего сказать полезного, удалите его. Замените заглушки настоящими командами и путями, прежде чем полагаться на файл.

Если вы нашли ещё одну привычку, которая делает CLAUDE.md лучше, попробуйте её и оставьте, только если она переживёт несколько реальных сессий.