CLAUDE.md - персистентная память проекта

Статья #4 в серии «Оптимизация контекста в Claude Code»

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

Проблема? Каждая строка CLAUDE.md стоит токенов в каждой сессии. Я видел CLAUDE.md на 30 килобайт с примерами кода, которые вообще не использовались. Это как платить аренду за склад, в котором никто не работает.

За полгода работы с Claude я эволюционировал от монолитного CLAUDE.md (в котором были примеры кода и история проекта) к модульной системе с пятиуровневой иерархией и .claude/rules/. В одном проекте размер сократился с 28KB до 3KB, при этом полнота информации выросла благодаря структурированию. В этой статье покажу как.

Пятиуровневая иерархия: от общего к специфичному

Claude Code не просто читает один CLAUDE.md. Он строит контекст из пяти уровней, от самого общего к самому конкретному.

Какова эта иерархия?

Ключевая механика: Claude комбинирует эти файлы, от общего контекста к специфичному, с переопределением конфликтующих правил. Правило из /project/src/api/CLAUDE.md переопределяет правило из /project/CLAUDE.md, которое в свою очередь дополняет правила из вашего user-level файла.

Я обнаружил эту иерархию на практике. В проекте с Turborepo, работая в /packages/api/, Claude использовал camelCase вместо snake_case из root CLAUDE.md. Сначала я был в шоке. Потом понял - это работает nesting. В подпапке лежал свой CLAUDE.md, который уточнял правила для API-слоя, не дублируя общие инструкции из корня проекта.

Как упоминалось в Context Engineering - новая парадигма, CLAUDE.md - один из четырёх детерминистических паттернов управления контекстом. В отличие от Skills (on-demand injection) или Hooks (lifecycle automation), персистентная память работает постоянно, формируя базовый слой понимания проекта.

Философия краткости: каждая строка - это инвестиция

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

Главный принцип разделения: CLAUDE.md всегда загружен, потому что он формирует базовый контекст проекта. Skills загружаются только когда вы их вызываете - это on-demand context injection. Если инструкция нужна менее чем в половине сессий, она не должна быть в CLAUDE.md. Это distinction критично для понимания context engineering, и я буду ссылаться на него дальше по тексту.

Есть ещё один трюк для экономии токенов: стиль написания. Императивный формат (“Use TypeScript strict mode”) потребляет меньше токенов, чем пояснительный (“We chose TypeScript strict mode because it helps catch bugs early and improves code quality”). Почему и зачем - это для документации. CLAUDE.md - это телеграмма, а не письмо.

Структура эффективного CLAUDE.md

Что должно быть (максимальная плотность информации):

• Название и назначение проекта (1-2 строки)
• Технический стек (язык, фреймворки, версии)
• Ключевые команды (build, test, lint, run)
• Архитектурные решения и WHY (кратко: 1-2 предложения на каждое)
• Naming conventions и code style
• Структура проекта (где что лежит)

Что не должно быть?

Длинные пояснения “почему” переносите в /docs/. Примеры кода - в Skills. TODO и временные заметки - в Git commits. История проекта - в Wiki. Полные ссылки на документацию - только путь или название, без URL.

У меня был проект на Next.js SaaS, где CLAUDE.md разросся до 500 строк. Половина файла была примерами использования API. Четверть - историей технических решений. Я потратил полдня на рефакторинг: перенёс примеры в Skill под названием api-patterns, историю - в /docs/decisions.md. Контекстное окно выросло ощутимо, скорость ответов увеличилась, а Claude стал точнее следовать инструкциям. Меньше шума, больше сигнала.

.claude/rules/ - модульная система v2.0.64+

Начиная с версии v2.0.64, Claude Code поддерживает .claude/rules/. Это механизм path-specific rules. Вместо одного монолитного CLAUDE.md вы создаёте модульные правила, которые загружаются только когда Claude работает с соответствующими файлами.

Представьте: у вас fullstack проект с фронтендом на React и бэкендом на Node.js. Раньше весь контекст загружался всегда - даже если вы работали только с UI-компонентами, Claude получал инструкции для database migrations и API endpoints. С .claude/rules/ вы разбиваете это:

.claude/rules/
├── frontend.md    # globs: ["src/components/**", "src/hooks/**"]
├── backend.md     # globs: ["src/api/**", "src/services/**"]
├── testing.md     # globs: ["**/*.test.ts", "**/*.spec.ts"]

Каждый файл содержит frontmatter с glob-паттернами, определяющими когда загружать эти правила:

---
globs:
  - "src/components/**"
  - "src/hooks/**"
---

# Frontend Rules

Use React 18 with TypeScript strict mode.
Components: functional with hooks, no class components.
State management: Zustand for global, useState for local.

Преимущества над монолитным CLAUDE.md:

• Модульная организация: каждая часть проекта имеет свой контекст
• Лаконичность base CLAUDE.md: только общие правила, без специфики
• Экономия токенов: в типичном workflow загружается только релевантный контекст

Я начал использовать .claude/rules/ в конце января 2026, и это было like opening a new dimension. Вместо одного огромного файла, который нужно постоянно редактировать и в котором легко потеряться, я теперь имею модульную систему: работаю с компонентами - загружаются frontend rules, пишу тесты - загружаются testing rules. Автоматически. Без моего участия.

Антипаттерны и как их избежать

За годы работы я насобирал коллекцию антипаттернов. Ошибок, которые делал сам и видел у других.

Антипаттерн #1: Bloated CLAUDE.md

Файл на 500+ строк, содержит примеры кода, историю решений, развёрнутые пояснения “почему мы выбрали X”.

Чем это плохо?

Overhead на каждую сессию становится критичным. Контекстное окно сужается. Claude начинает терять фокус на актуальной задаче. Чем больше базового контекста, тем меньше места для вашего кода и диалога.

Решение простое: разбить на модули. Примеры - в Skills, история - в /docs/, пояснения - кратко или в wiki. Используйте .claude/rules/ для специфичных инструкций.

В одном проекте я перенёс большую часть контекста в структуру .claude/rules/. Сессии стали быстрее, Claude начал выполнять задачи с меньшим количеством уточняющих вопросов. Меньше контекстного шума - выше качество вывода.

Антипаттерн #2: CLAUDE.md как enforcement

Многие думают: “Если я напишу ‘Always use TypeScript’, Claude всегда будет это соблюдать”. Нет.

Claude может нарушить инструкцию. Например, если контекст задачи требует JavaScript, или если забыл про правило из-за перегруженного контекста. CLAUDE.md направляет поведение модели, но не контролирует его жёстко. Это suggestions, не гарантии.

Для гарантий используйте Hooks. Shell-команды, которые исполняются на lifecycle events Claude Code. Например, pre-commit hook может автоматически проверять TypeScript strict mode или запускать линтер. Подробнее об этом паттерне в статье Context Engineering - новая парадигма.

Я потратил полчаса на поиск ошибки в Django REST API проекте, думая что Claude не читает CLAUDE.md. Оказалось, я ожидал enforcement там, где получал suggestion. Claude просто сгенерировал JSON вместо классов Pydantic, хотя в CLAUDE.md было написано использовать Pydantic, потому что это было логичнее для конкретной задачи. Я понял: CLAUDE.md это не закон, это совет. Для законов есть CI/CD и hooks.

Антипаттерн #3: Дублирование правил

Одно и то же правило находится в user-level CLAUDE.md и в project-level CLAUDE.md. Пример: в ~/.claude/CLAUDE.md написано “Use 2 spaces for indentation”, и в /project/CLAUDE.md то же самое.

Это не просто избыточность - это риск рассинхронизации. Если вы обновите одно место, забудете другое, Claude получит противоречивые инструкции.

Решение: разделяйте личные предпочтения (user-level) и командные стандарты (project-level). Если правило применяется везде - в user CLAUDE.md. Если специфично для проекта - в project. Не дублируйте.

Антипаттерн #4: Устаревшие правила

CLAUDE.md ссылается на удалённые файлы, deprecated библиотеки, старые версии зависимостей. Пример: “Use Webpack 4 configuration in /config/webpack.js”, но проект уже мигрировал на Vite, а файл удалён. Claude следует мёртвым инструкциям, генерируя код для несуществующего setup.

Что делать:

• Указывайте версии явно: “Node.js 20.x LTS”, “React 18+”
• Регулярный review CLAUDE.md при обновлении стека (раз в квартал или после major updates)
• Используйте Git: коммитьте изменения CLAUDE.md вместе с обновлением зависимостей

Практические кейсы: как это работает в реальности

Теория - это хорошо, но давайте посмотрим на три реальных сценария использования CLAUDE.md.

Кейс 1: Стартап с одним разработчиком (Next.js SaaS)

Один разработчик работает на fullstack Next.js проект, платформу онлайн-курсов с 50+ компонентами и активной разработкой. Вот как он структурировал CLAUDE.md: простой файл на уровне проекта, 1.5KB.

Что включено:

• Tech stack: Next.js 15, TypeScript, Tailwind CSS, Prisma ORM
• Команды: npm run dev, npm test, npx prisma migrate dev
• Ключевые правила: use App Router, server components by default, client components только с ‘use client’
• Структура: /app для routes, /components для UI, /lib для utilities

Что не включено: история выбора Next.js (в /docs/decisions.md), примеры компонентов (в Skill nextjs-patterns), team guidelines (нет команды).

Результат: базовый контекст на 1.5KB вместо потенциальных 10KB+, время загрузки сессии не растёт с добавлением новых кейсов.

Кейс 2: Большая команда, монорепо (Turborepo, 5 пакетов)

Команда из 10 разработчиков, Turborepo с пятью микросервисами и общими библиотеками.

Как они решили структурировать контекст? Root CLAUDE.md содержал общие стандарты - TypeScript, ESLint config, commit conventions. Каждый пакет имел свой файл: /packages/api/CLAUDE.md описывал специфику REST API (OpenAPI, validation с Zod), /packages/frontend/CLAUDE.md - React + Material UI conventions, /packages/auth/CLAUDE.md - OAuth flows, JWT handling.

Плюсы очевидны. Модульность - каждая команда владеет своим контекстом. Нет конфликтов правил между пакетами. Без иерархии обе команды были бы привязаны к одному root CLAUDE.md - спорить о версиях TypeScript, правилах стилизации, паттернах обработки ошибок.

Skills, как описано в Context Engineering - новая парадигма, помогают разгрузить CLAUDE.md от детальных примеров.

Кейс 3: .claude/rules/ для разделения фронтенда и бэкенда

Fullstack проект. Один разработчик переключается между UI и API. Раньше он генерировал React компоненты с непоследовательными паттернами (className вместо css-modules), потому что контекст был смешанный.

Теперь структура выглядит так:

.claude/rules/
├── frontend.md   # React, стилизация, компоненты
├── backend.md    # Express, database, API design
├── testing.md    # Jest, testing patterns

Каждый файл содержит glob-паттерны: frontend.md активен для src/components/**, backend.md для src/api/**. Claude автоматически загружает правильные инструкции в зависимости от того, с какими файлами вы работаете.

Теперь с .claude/rules/ frontend.md загружается только для src/components/** - нет путаницы.

Взаимодействие с другими компонентами

CLAUDE.md не существует в изоляции - он часть экосистемы context engineering в Claude Code. Вот как он взаимодействует с другими паттернами.

Как разделить базовый контекст и специфичные гайды?

CLAUDE.md даёт базовые, постоянные инструкции (persistent context), а Skills - детальные гайды по требованию (on-demand injection). Вспомним принцип из раздела “Философия краткости”: если инструкция нужна менее чем в половине сессий, она создаёт шум в базовом контексте.

Пример: в CLAUDE.md написано “Use Prisma ORM”, а Skill prisma-migrations содержит подробный гайд по созданию миграций, seed данных, rollback стратегии. Вы вызываете его только когда работаете с базой данных.

CLAUDE.md + Subagents: каждый subagent - изолированный экземпляр Claude Code с собственным контекстным окном (подробнее о subagents в следующих статьях серии). Он наследует CLAUDE.md из того места, где запущен. Это мощно: можете запустить subagent в /packages/api/ и он автоматически получит и root CLAUDE.md, и специфичный для API.

CLAUDE.md + Hooks: первый - suggestions, второй - enforcement через lifecycle events. CLAUDE.md говорит “предпочитай TypeScript”, Hook на pre-commit гарантирует, что весь код проходит tsc --noEmit. Два слоя контроля: мягкий (guidance) и жёсткий (automation).

Я научился различать: CLAUDE.md для базовых, частых правил, которые формируют понимание проекта. Skills для специфичных, редких инструкций, которые нужны эпизодически. Hooks для гарантий, где suggestion недостаточно. Это выровняло мой context engineering workflow.

Подробнее о Skills и Hooks читайте в Context Engineering - новая парадигма.

Миграция и оптимизация: когда пора рефакторить

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

• < 2KB: оптимум - лаконично, плотно, эффективно
• 2-5KB: хорошо, достаточно контекста для большинства проектов
• 5-10KB: может быть избыточно, требует review
• > 10KB: это точно переполнение, требуется срочный рефакторинг

Если вы в зоне 5KB+, задайте себе вопросы:

• Есть ли примеры кода? Перенести в Skills
• Есть ли длинные пояснения “почему”? Сократить до 1-2 предложений или перенести в /docs/
• Есть ли специфичные для частей проекта правила? Использовать .claude/rules/
• Есть ли дублирование с user-level CLAUDE.md? Убрать

Процесс рефакторинга:

1. Audit: прочитайте весь CLAUDE.md, пометьте что используется редко
2. Extract: создайте Skills для детальных гайдов
3. Modularize: используйте .claude/rules/ для path-specific контекста, разбейте монолит на несколько модулей с чёткими зонами ответственности
4. Compress: сократите пояснения до императивных инструкций
5. Test: проверьте что Claude всё ещё понимает проект корректно

CLAUDE.md imports: начиная с последних версий, можно переиспользовать правила между проектами через import-механизм. Если у вас несколько проектов с общим tech stack, вынесите общие правила в shared файл и импортируйте. Формат импорта:

---
imports:
  - "~/.claude/shared-rules/typescript.md"
  - "~/.claude/shared-rules/testing.md"
---

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

Заключение

CLAUDE.md - это не просто инструкция для Claude, это асинхронная коммуникация с будущей версией себя. Каждая строка должна весить своё в золоте: если информация не нужна в большинстве сессий, её не должно быть здесь.

Три главных takeaway:

1. Пятиуровневая иерархия (enterprise - user - project - subdirectory - rules) позволяет масштабировать от одного разработчика до большой команды, не создавая хаос в правилах.
2. Используйте .claude/rules/ v2.0.64+ для модульной системы, которая загружает контекст только когда нужно.
3. Не ожидайте железного соблюдения правил из CLAUDE.md. Для гарантий используйте Hooks, CI/CD, pre-commit проверки.

Actionable next steps:

• Если ваш CLAUDE.md больше 5KB, отведите час на рефакторинг - результат окупит вложенное время
• Если вы ещё не используете .claude/rules/, попробуйте разбить project-level правила по типам (frontend/backend/testing)
• Проверьте нет ли дублирования между user CLAUDE.md и project CLAUDE.md - синхронизируйте или разделите зоны ответственности

Связь с серией: Первая статья дала концепцию Four Patterns управления контекстом; эта статья показала, как масштабировать персистентную память через иерархию и модульность. Следующие статьи в серии будут погружаться в Skills (on-demand context), Subagents (изолированные экземпляры), Hooks (lifecycle automation). Вместе это создаёт полную систему context engineering.

Я видел, как хороший CLAUDE.md меняет качество работы с Claude. Это не просто файл - это мост между вами и Claude, между прошлым и будущим состоянием проекта. Стройте его хорошо.