CLAUDE.md and Project Memory

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

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

Стартовать проще всего командой /init: агент просканирует репозиторий и сгенерирует черновик CLAUDE.md — команды сборки, структуру, замеченные конвенции. Черновик обязательно вычитайте: /init пишет то, что видит в коде, а не то, что важно команде. Настоящая ценность файла — правила, которых в коде нет: «не трогать legacy-каталог», «миграции только через скрипт», «тесты обязательны перед коммитом». Именно такие строки экономят вам десятки одинаковых замечаний агенту.

Хороший CLAUDE.md отвечает на вопросы, которые агент не может вывести из кода. Проверенная практикой структура:

# Команды
- npm run dev — dev-сервер на :3000
- npm run test:unit — юнит-тесты, запускать перед каждым коммитом
- npm run db:migrate — миграции только через этот скрипт

# Конвенции
- Импорты через алиас @/, не относительные ../../
- Коммиты по Conventional Commits, файлы в git add поимённо

# Грабли
- src/legacy/ не рефакторить без отдельной задачи
- .env не читать и не логировать

Каждая строка здесь — сжатое правило действия: что запускать, чему следовать, чего не делать. Такой файл агент действительно применяет.

Теперь антипаттерн. CLAUDE.md загружается в каждую сессию, то есть каждая строка — постоянный налог на контекстное окно. Файл на две тысячи строк с историей проекта, философией архитектуры и копиями документации приводит к обратному эффекту: агент тонет в тексте, а важные запреты теряются среди воды. Держите файл коротким и императивным. Если агент систематически игнорирует правило — не дублируйте его трижды, а перепишите конкретнее: вместо «пиши аккуратные тесты» — «каждый новый публичный метод получает тест в соседнем каталоге tests». Относитесь к CLAUDE.md как к коду: правило, которому агент не следует, — это баг формулировки, и его надо чинить, а не копипастить.

Память пополняется прямо по ходу работы. Начните сообщение с символа # — Claude Code предложит сохранить его как правило и спросит, в какой файл записать: проектный или личный. Это главный инструмент против повторяющихся замечаний: поймали агента на ошибке — тут же превратили исправление в правило. Команда /memory открывает файлы памяти в редакторе, когда нужна правка покрупнее.

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

# Архитектура
Обзор слоёв и границ модулей — см. @docs/architecture.md

# Тестовая стратегия
@docs/testing.md

# Личные заметки (файл вне git)
@~/.claude/notes-my-project.md

Импорты решают дилемму «коротко или полно»: основной файл остаётся компактным списком правил, а детальные регламенты живут в docs/ и подключаются по ссылке. Бонус — эти же документы читает команда, у вас один источник истины вместо двух расходящихся копий.

Паттерн зрелой команды: CLAUDE.md ревьюится как код, изменения проходят через PR, а каждое послемортемное «агент опять сделал X» заканчивается новым правилом или уточнением старого. Через месяц такой дисциплины агент ведёт себя как разработчик, прочитавший весь onboarding.

CLAUDE.md — долгая память, контекстное окно — рабочая. Смешивать их — типовая ошибка: решения, принятые в диалоге, живут ровно до /clear или переполнения окна. Если в длинной сессии вы согласовали схему API или выбрали библиотеку — зафиксируйте это письменно: в CLAUDE.md, если это правило навсегда, или в файл плана (PLAN.md, notes/), если это артефакт конкретной задачи.

Практика для многодневных задач выглядит так. В начале — план в файле с чек-боксами по шагам. После каждого шага — отметка в плане и коммит. При разбухании контекста — /compact с указанием, что сохранить, либо /clear и продолжение с опорой на план: агент перечитает файл и восстановит картину за секунды. Флаги claude -c и claude -r возвращают вас в прошлые сессии, но полагаться только на них не стоит — файл плана надёжнее и виден всей команде.

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