Что писать в CLAUDE.md

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

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

Пример CLAUDE.md

Возьмём простую страницу с карточками. Разметка, стили и JavaScript находятся в одном index.html, страницу можно открыть прямо в браузере. Для такого проекта файл инструкций может выглядеть так:

# CLAUDE.md

## Проект
- Страница, стили и JavaScript находятся в `index.html`.

## Проверка
- Открыть `index.html` в браузере.
- Проверить страницу на широком и узком экране.

## Правила
- Сохранять текущие цвета и стиль карточек.
- Не удалять готовые блоки без подтверждения.
- После работы перечислять изменения и проверки.

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

Это пример для одного файла, а не универсальный шаблон. В вашем проекте могут быть отдельные папки и команды запуска. Запишите именно их; если тестов нет, не добавляйте выдуманную команду ради полноты.

Что стоит записывать

Главный фильтр: понадобится ли эта запись при следующих задачах? Полезны проверенные команды, важные пути и договорённости, которые агент не сможет надёжно вывести из кода. Особенно те, которые вам уже приходилось повторять.

Формулируйте правило так, чтобы было понятно, какое действие от агента ожидается:

"всё проверяй" → "после изменения карточек проверь страницу на широком и узком экране";
"не трогай важное" → "не удаляй готовые блоки без подтверждения: их содержимое уже согласовано".

В первом случае названа проверка, во втором - область ограничения и причина. Это полезнее длинного списка пожеланий вроде "работай аккуратно".

README.md объясняет человеку, что за проект перед ним и как начать работу. CLAUDE.md собирает инструкции для агента. Пересказывать весь README не нужно. А гипотезу "кажется, подпись съезжает из-за ширины карточки" оставьте в заметке текущей задачи, например PROJECT_NOTE.md. Это обычный файл с выбранным вами именем; при продолжении задачи попросите агента прочитать его.

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

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

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

Посмотрите, нет ли в проекте готового CLAUDE.md. Если есть, прочитайте его и дополните. Для нового файла выберите корень проекта; поддерживается и расположение .claude/CLAUDE.md, но создавать обе копии незачем.
Напишите несколько строк вручную или введите /init внутри Claude Code, открытого в папке проекта. Команда изучит проект и подготовит черновик; для существующего файла предложит улучшения.
Прочитайте результат. Сверьте команды и пути с проектом, удалите догадки. Например, если агент вписал команду тестов, которой у вас нет, уберите её. Ограничения, которые известны только вам, допишите сами.
Сохраните файл и откройте новую сессию в папке проекта. Введите /context: в разделе Memory files должен быть путь к вашему CLAUDE.md.

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

Загрузка и соблюдение

Файл в списке подтверждает загрузку, но не гарантирует соблюдение правил. Правильный ответ агента сам по себе загрузку не доказывает: сведения могли найтись в других файлах. Инструкция направляет работу, но не создаёт технического запрета на действие.

Куда записывать остальное

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

Сначала определите назначение записи, затем выбирайте файл.

Общее правило может касаться одной папки и всё равно быть нужным всей команде. .claude/rules/ помогает разделить такие инструкции по темам; ограничение конкретными путями настраивается отдельно. Для пары правил усложнять структуру не нужно.

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

Авто-память (auto memory) - отдельные заметки, которые Claude сохраняет по ходу работы, если механизм включён. Не оставляйте важное правило только на его усмотрение: прямо попросите добавить его в CLAUDE.md. Временная гипотеза о баге остаётся заметкой задачи.

Если в проекте уже есть AGENTS.md, не переписывайте его содержимое во второй файл. В CLAUDE.md можно подключить соседний файл строкой @AGENTS.md. Это особенно полезно при добавлении CLAUDE.local.md: личный файл может повлиять на прямое чтение AGENTS.md. Другие варианты описаны в документации.

Когда обновлять правила

Редактируйте файл вместе с проектом. Вынесли стили из index.html в отдельный файл - исправьте строку о структуре. Изменили способ проверки - замените старую инструкцию. Не дописывайте новое правило поверх противоречащего старого.

Повторяющуюся поправку можно поручить агенту: "Добавь в CLAUDE.md, что перед удалением готового блока нужно моё подтверждение". Затем прочитайте изменение: оно должно передавать вашу договорённость без новых ограничений от себя. Одной строки часто хватает.

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