Архитектура Claude Code: как управлять контекстом, Subagents и писать эффективный CLAUDE.md

Ваш CLAUDE.md — это хлам. Пора это признать

Вы открываете проект. Видите папку node_modules, src, и этот файл — CLAUDE.md. Вы гордитесь им. Там вся философия проекта, соглашения по именованию, история решений. Вы думаете: "Теперь AI поймет мой код". А он тупит. Предлагает ерунду. Тратит токены на анализ ваших мудрых мыслей вместо того, чтобы писать код.

Проблема не в Claude. Проблема в том, что вы не понимаете, как он работает. Claude Code 3.5 (актуальная версия на март 2026) — это не просто текстовый генератор. Это сложная архитектура с кэшированием контекста, под-агентами и системой приоритетов. И вы ломаете ее своим прекрасным документацией.

Как Claude Code на самом деле читает ваш проект

Забудьте про человеческое чтение. Claude Code сканирует контекст в три этапа, и ваш CLAUDE.md мешает на каждом.

1 Слой 1: Prompt Caching — что кэшируется навсегда

Claude Code не анализирует весь проект каждый раз. Он кэширует промпты. Система определяет, какие файлы «важные», и сохраняет их эмбеддинги. При следующем открытии — быстро подтягивает из кэша.

Что попадает в кэш? Файлы, которые часто меняются (ваш текущий worktree), конфигурационные файлы (package.json, Dockerfile), и — внимание — первые 2000 символов CLAUDE.md. Да, только начало. Остальное игнорируется.

# Где живет кэш Claude Code (macOS, март 2026)
~/Library/Caches/Claude/code_prompt_cache_v3.db

# Посмотреть, что закэшировано
sqlite3 ~/Library/Caches/Claude/code_prompt_cache_v3.db "SELECT * FROM cache LIMIT 5;"

Если ваш CLAUDE.md начинается с истории проекта на 5000 слов — в кэш попадает только эта история. Архитектурные решения, которые в конце файла, никогда не прочитаются.

2 Слой 2: Subagents — кто на самом деле пишет код

"Claude Code" — это не один агент. Это система из трех под-агентов, которые работают параллельно. Ваш промпт разбивается и распределяется между ними.

Когда вы даете огромный CLAUDE.md, Architect тратит свой контекстный бюджет на его анализ. Coder получает меньше токенов для понимания реального кода. Результат — поверхностные решения.

3 Слой 3: Контекстное окно — что видит агент прямо сейчас

Самое важное. Claude Code работает с скользящим контекстным окном. Он видит не весь проект, а текущий фокус: открытые файлы, последние изменения, активную функцию.

Ваш CLAUDE.md, если он в корне, всегда в контексте. Он съедает токены, которые нужны для анализа кода. Это как пытаться решать математическую задачу, когда кто-то читает вам вслух историю математики.

Так нужен ли CLAUDE.md? Да. Но другой

Полный отказ от контекста — тоже ошибка. Нужен файл, который работает с архитектурой Claude Code, а не против нее.

Забудьте все, что вы знали. Новые правила на март 2026:

• Максимум 500 слов. Если больше — агент проигнорирует.
• Только actionable информация: имена ключевых модулей, соглашения по именованию (например, "все хуки начинаются с `use`"), критичные зависимости.
• Никакой истории, философии, планов на будущее.
• Используйте маркеры для Subagents: [ARCHITECT], [CODER], [REVIEWER].

# КАК НЕ НАДО
Наш проект начался в 2023 году с целью изменить мир...
Мы выбрали микросервисную архитектуру, потому что...

# КАК НАДО
[ARCHITECT]
- Сервис А зависит от Сервиса B через gRPC
- База данных: PostgreSQL, схема `core_v2`
[CODER]
- Хуки начинаются с `use` (useAuth, useQuery)
- Компоненты: PascalCase, файлы: kebab-case
[REVIEWER]
- Обязательно проверять типы TypeScript
- Избегать `any`, использовать `unknown`

Такой файл займет в кэше мало места, даст каждому Subagentу именно его контекст, и не будет мешать Coder'у работать.

Skills и Hooks: как заставить Subagents работать на вас

Skills — это не макросы. Это прямые инструкции для Subagents. В версии 3.5 появились Hooks — события, которые запускают Skills автоматически.

Пример: вы хотите, чтобы Architect анализировал каждое новое API endpoint. Раньше нужно было вручную запускать skill. Теперь можно привязать к hook'у.

{
  "skills": {
    "analyze_endpoint": {
      "description": "Проанализировать архитектуру нового endpoint",
      "subagent": "architect",
      "command": "claude-analyze --type=api-endpoint"
    }
  },
  "hooks": [
    {
      "event": "file_created",
      "pattern": "src/routes/*.ts",
      "skill": "analyze_endpoint"
    }
  ]
}

Эта конфигурация заставит Architect автоматически проверять каждый новый файл route. Coder не отвлекается.

Где это настроить? В ~/.claude/code_config.json. Если файла нет — создайте. Claude Code 3.5 ищет его автоматически. Подробнее о Skills я писал в статье про максимизацию Claude Code.

План: перестройка вашего проекта под Claude Code за 30 минут

1 Удалите старый CLAUDE.md

Просто удалите. Или переименуйте в CLAUDE_OLD.md. Если есть важная информация — выжмите из нее 500 слов самого важного.

2 Создайте новый CLAUDE.md по шаблону

[ARCHITECT]
Кратко: 2-3 пункта о главных зависимостях и решениях.

[CODER]
- Стиль кода: например, "используйте async/await, а не promises"
- Критичные пути: например, "логика оплаты в /src/payment"

[REVIEWER]
- Что проверять в первую очередь: "утечки памяти в useEffect"
- Известные проблемы: "избегать функции X из-за бага в библиотеке Y"

3 Настройте кэширование для важных файлов

В ~/.claude/code_config.json добавьте:

{
  "prompt_caching": {
    "always_cache": ["src/core/types.ts", "src/config/constants.ts"],
    "never_cache": ["*.log", "tmp/*"]
  }
}

Так вы гарантируете, что ключевые типы и константы всегда в кэше, а логи — никогда.

4 Создайте Skills для рутинных задач

Определите, что вы делаете чаще всего. Code review? Рефакторинг? Генерация тестов? Опишите это в Skills, привяжите к Subagents. Идеи для рабочих процессов можно подсмотреть здесь.

5 Очистите кэш и перезапустите

# Очистка кэша Claude Code (macOS/Linux)
rm -f ~/Library/Caches/Claude/code_prompt_cache_v3.db
# Перезапуск Claude Code
pkill -f "Claude Code" && open -a "Claude Code"

Теперь система начнет с чистого листа, с вашей новой конфигурацией.

Типичные ошибки, которые сведут на нет всю работу

• Слишком много Skills. Claude Code будет тратить время на их анализ. 5-7 ключевых Skills достаточно. Остальное — через контекст.
• Игнорирование Hooks. Если не используете Hooks, вы теряете автоматизацию. Подпишитесь хотя бы на file_created и before_commit.
• Микроменеджмент Subagents. Не пытайтесь контролировать каждый шаг. Дайте Architect 15% токенов и доверьтесь. Если будете указывать слишком детально — сломаете его естественный flow.
• Хранение конфигов в проекте. ~/.claude/code_config.json — глобальный. Не кладите его в репозиторий проекта. Иначе настройки будут конфликтовать между проектами. Используйте DotTools для управления конфигами окружения.

Последний совет: перестаньте думать за Claude

Самая большая ошибка — давать агенту слишком подробные инструкции. "Сделай вот так, потому что я так думаю". Вы ломаете его способность находить неочевидные решения.

Claude Code 3.5 на базе Anthropic Opus 4.6 имеет контекст 1M токенов и команды агентов. Но это не значит, что нужно заполнять все токены. Лучший контекст — минимальный, но точный.

Дайте проблему. Дайте границы (технологии, время). И остановитесь. Subagents сами распределят работу. Architect найдет паттерн, который вы не видите. Coder напишет код, который вы не ожидали. Reviewer найдет баг, который вы пропустили.

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

И да, удалите тот старый CLAUDE.md. Прямо сейчас.

Подписаться на канал