Файл CLAUDE.md: память проекта

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

Что это и где лежит

CLAUDE.md — обычный markdown-файл. Claude Code загружает его в контекст при старте сессии, вместе с системными инструкциями. Расположение определяет область действия:

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

Проверить, что файл загрузился, можно командой /context: он будет в списке «Memory files». Команда /memory открывает файлы памяти в редакторе.

С чего начать: /init

Команда /init анализирует проект и генерирует стартовый CLAUDE.md с командами сборки, тестов и найденными соглашениями. Если файл уже есть, /init предложит улучшения, а не перезапишет. Она также подхватывает правила из .cursor/rules и .github/copilot-instructions.md, если они есть. Если в репозитории уже используется AGENTS.md для других агентов, достаточно импортировать его: строка @AGENTS.md в CLAUDE.md подставит содержимое.

Сгенерированный файл — черновик. Самое ценное в CLAUDE.md — то, что агент не может вывести из кода: почему что-то сделано именно так, какие ловушки уже встречались, что запрещено.

Что писать, а что нет

Документация даёт понятную таблицу.

Включать:

• команды, которые агент не угадает: как запустить тесты одного модуля, как собрать под staging;
• правила стиля, отличающиеся от умолчаний;
• инструкции по тестированию и предпочитаемый раннер;
• этикет репозитория: именование веток, требования к PR;
• архитектурные решения, специфичные для проекта;
• особенности окружения: обязательные переменные, локальные сервисы;
• неочевидное поведение и типичные ловушки.

Не включать:

• всё, что агент прочитает в коде сам: структуру папок, список зависимостей;
• стандартные соглашения языка, которые модель и так знает;
• подробную документацию API — дайте ссылку;
• то, что часто меняется;
• длинные объяснения и туториалы;
• самоочевидное: «пиши чистый код».

Критерий для каждой строки: «если её убрать, агент начнёт ошибаться?» Если нет — убирайте. Раздутый CLAUDE.md хуже короткого: важные правила теряются в шуме, и агент начинает игнорировать половину. Ориентир из документации — до 200 строк. Команда /doctor для закоммиченного CLAUDE.md предлагает, что вырезать.

Пример для проекта

Файл для Next.js-приложения с Python-бэкендом в одном репозитории может выглядеть так:

# Проект: личный кабинет клиента

## Команды
- Фронтенд: `pnpm dev`, тесты `pnpm test -- <путь>` (не весь набор)
- Бэкенд: `uv run pytest tests/<модуль>`, миграции `uv run alembic upgrade head`
- Перед коммитом: `pnpm typecheck` и `uv run ruff check`

## Соглашения
- Используем pnpm, не npm
- API-обработчики живут в `backend/app/api/`, схемы — в `backend/app/schemas/`
- Компоненты — функциональные, без default export
- Переводы: строки только через `t()`, ключи в `locales/ru.json`

## Ловушки
- Тесты бэкенда требуют локальный Redis: `docker compose up redis`
- Не трогать `legacy/` — ждёт миграции, правки туда не принимаются

## Git
- Ветки `feature/<задача>`, коммиты на русском в повелительном наклонении
- PR без тестов на новую логику не принимаются

Обратите внимание на конкретность. «Запускай pnpm test -- <путь>» проверяемо; «тестируй изменения» — нет. Если два правила противоречат друг другу, агент выберет любое, поэтому файл стоит перечитывать после каждого крупного изменения в проекте.

Импорты и .claude/rules/

CLAUDE.md может подключать другие файлы синтаксисом @путь:

См. @README для обзора и @package.json для списка команд.
- Git-процесс: @docs/git-instructions.md

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

Для больших проектов есть папка .claude/rules/: по файлу на тему (testing.md, api-design.md, security.md). Правила без дополнительных пометок загружаются при старте наравне с CLAUDE.md. Правила с полем paths в front matter загружаются только когда агент работает с файлами по маске:

---
paths:
  - "backend/app/api/**/*.py"
---

# Правила для API
- Каждый эндпоинт валидирует вход через Pydantic-схему
- Ошибки — только через `AppError`, не голые исключения

Это и есть способ держать CLAUDE.md коротким: общее — в нём, частное — в правилах по маске. Личные правила для всех проектов кладут в ~/.claude/rules/.

Инструкции не равны запретам

Важно понимать, чем CLAUDE.md не является. Это контекст, а не конфигурация. Claude читает его и старается следовать, но гарантий нет — особенно для расплывчатых или противоречивых инструкций. Документация прямо говорит: чтобы заблокировать действие независимо от решения модели, нужен хук PreToolUse или правило deny в правах. «Не редактируй миграции» в CLAUDE.md — пожелание; хук, который возвращает код 2 на правку migrations/, — запрет.

Практическое правило: если инструкция должна срабатывать в определённый момент — перед коммитом, после каждой правки, — это хук. Если агент делает что-то правильно и без инструкции — инструкцию можно удалить. Если раз за разом пропускает одно правило — добавьте к этой строке «IMPORTANT», но только к ней: если выделять всё, не выделяется ничего.

Автоматическая память

Кроме CLAUDE.md есть второй механизм — автоматическая память. По ходу работы Claude сам записывает заметки: ваши поправки, предпочтения, контекст проекта, который не выводится из кода, ссылки на внешние ресурсы. Они хранятся в ~/.claude/projects/<проект>/memory/ с индексом MEMORY.md; первые 200 строк индекса загружаются в каждую сессию. Заметки можно читать и править как обычный markdown, а /memory показывает, что сохранено, и позволяет отключить механизм.

Разница простая: CLAUDE.md пишете вы — это правила; память пишет Claude — это наблюдения. Если вы говорите «всегда используй pnpm», Claude запишет это в память. Если хотите, чтобы правило было в CLAUDE.md, скажите «добавь это в CLAUDE.md» или впишите сами.

Когда пополнять

Документация даёт четыре сигнала: агент повторил одну и ту же ошибку; ревью поймало то, что агент должен был знать о проекте; вы второй раз пишете в чат одну и ту же поправку; новому коллеге понадобился бы тот же контекст. Каждый такой случай — строка в CLAUDE.md. Файл живёт в git, и команда пополняет его вместе; со временем он становится самым честным описанием того, как в проекте принято работать.