Разбор дизайна harness в Claude Code

В статье «Effective harnesses for long-running agents» Anthropic прямо утверждает: надёжность обеспечивает harness, а не модель; agent должен быть ограничен средствами «за пределами модели». Claude Code — продуктовая реализация этой идеи, и сама Anthropic прямо относит его к категории agentic harness. Это не маркетинговая формулировка: Claude Code, возможно, является наиболее подробно исследованным из публичных harness. Его исходный код открыт, сообщество подготовило обстоятельные исследовательские отчёты, а почти все ключевые механизмы из лекций курса — многоуровневая память, compaction контекста, permissions, hooks, subagent и сохранение session — получили полноценную продуктовую реализацию.

В этой статье мы разберём Claude Code через фреймворк пяти подсистем курса и сосредоточимся на том, как он реализует фундаментальные для harness идеи «управления контекстом», «предотвращения преждевременного объявления о завершении» и «детерминированных ограничений».

Позиционирование в одном предложении

В основе Claude Code лежит простой цикл while: вызвать модель, выполнить инструмент, увидеть результат и снова вызвать модель. Но подавляющая часть кода находится не в этом цикле, а в окружающих его системах — системе permissions, конвейере compaction контекста, механизмах расширения, оркестрации subagent и хранилище session. В этом и состоит сущность harness: цикл — лишь скелет, а надёжность определяет всё, что находится вокруг него.

Подсистема инструкций: многоуровневая система памяти

Система памяти Claude Code — его самый непосредственный вклад в теорию harness; она соответствует лекциям курса «Репозиторий должен стать единственным источником истины» и «Непрерывность контекста между session». Официальная документация «How Claude remembers your project» прямо говорит: каждая session начинается с совершенно нового окна контекста, а знания между session переносят два механизма — файлы CLAUDE.md (написанные вами инструкции) и auto memory (заметки, которые пишет сам Claude).

Официальная документация разделяет файлы CLAUDE.md на четыре области действия — от самой широкой к самой узкой в порядке загрузки:

• Уровень политики организации: централизованно управляется IT/DevOps (например, /etc/claude-code/CLAUDE.md) и содержит корпоративные стандарты.
• Пользовательский уровень ~/.claude/CLAUDE.md: личные предпочтения и правила, действующие во всех проектах.
• Уровень проекта ./CLAUDE.md или ./.claude/CLAUDE.md: проектный источник истины — структура, технологический стек и команды верификации; хранится в общем репозитории.
• Локальный уровень ./CLAUDE.local.md: личные предпочтения внутри проекта; обычно добавляется в .gitignore и не коммитится.

Есть ещё два механизма:

• Загрузка по требованию на уровне подкаталогов: CLAUDE.md из подкаталога не загружается при запуске, а попадает в контекст лишь тогда, когда Claude читает файл из этого каталога.
• Автоматическая память (auto memory): Claude самостоятельно записывает заметки на основе ваших исправлений и предпочтений; они общие для репозитория и действуют между worktree. В каждой session загружаются не более первых 200 строк или 25KB.

Эти четыре области действия образуют иерархию инструкций: в официальной документации сказано, что «чем конкретнее инструкции, тем позже они попадают в контекст» — инструкции проекта следуют за пользовательскими. Ценность этого решения в том, что в начале каждого разговора модели не приходится переваривать единый гигантский файл инструкций: они загружаются по месту, в зависимости от области действия. Это продуктовый ответ на вопрос лекции 4 «Почему один гигантский файл инструкций не работает».

Подсистема контекста: пятиуровневый конвейер compaction

Claude Code управляет контекстом с помощью пятиуровневого конвейера compaction (five-layer compaction pipeline), а не простого подхода «когда заполнится — сделать summary». Эта архитектурная деталь получена из разбора исходного кода в отчёте VILA Lab «Dive into Claude Code». В лекции 5 объясняется, почему длительные задачи теряют непрерывность; ответ Claude Code — многоступенчатая воронка: сначала выполняется compaction без потерь с отсечением избыточных результатов инструментов, затем — структурированное извлечение, и только в конце используется LLM-summary с потерями. Предохранительный механизм не допускает чрезмерной compaction.

Эту схему дополняет хранилище session с добавлением записей (append-oriented storage): вся история дописывается в history.jsonl, а /resume позволяет восстановить работу и создать ветвь fork. Благодаря этому принцип «перед завершением каждой session подготовить handoff» соблюдается не за счёт хорошей памяти, а за счёт дописываемого и воспроизводимого слоя хранения.

Подсистема инструментов: четыре механизма расширения

Claude Code разделяет поверхность расширения на четыре категории, каждая из которых решает свой тип задач. Это одна из наиболее полезных частей его дизайна:

• Skills: официальная документация определяет их как процедурные знания, описанные в SKILL.md, автоматически загружаемые по ключевым словам с progressive disclosure. Они подходят для предметных знаний о том, «как сделать определённую вещь».
• MCP: описанный в официальной документации протокол JSON-RPC подключает внешние системы; это стандартный интерфейс, позволяющий «рукам модели дотянуться до внешнего мира».
• Hooks: официальная документация описывает детерминированные скрипты, подключаемые к таким событиям жизненного цикла, как PreToolUse, PostToolUse и Stop.
• Plugin / Subagents: официальная документация описывает передачу сложных задач специализированным agent.

Ключевое решение — разделение ответственности: CLAUDE.md отвечает на вопрос «что», skills — «как», MCP — «куда подключаться», hooks — «когда принудительно применить». Если команда смешивает эти уровни — например, записывает в CLAUDE.md то, что должен делать MCP, — возникает описанная в курсе утечка контекста.

Обратная связь и верификация: детерминированные ограничения + разделение ролей человека и машины

Лекция 10 утверждает, что настоящая верификация требует прохождения полного процесса. В Claude Code этому соответствует двухконтурный механизм:

1. Система permissions (детерминированные ограничения). Permissions Claude Code — это не правило «спрашивать обо всём», а семь режимов и классификатор на основе ML: операции с низким риском разрешаются, а для высокорисковых операций система, в зависимости от политики, запрашивает подтверждение или отклоняет их (архитектурные подробности см. в разборе VILA Lab). Так идея «задать agent чёткие границы» из лекции 7 становится принудительным правилом runtime, а не просьбой в prompt.

2. Hooks (защита от преждевременного объявления о завершении). Hook PostToolUse может принудительно запустить проверки после выполнения инструмента и вернуть их результаты в контекст; hook Stop вмешивается, когда agent объявляет о завершении. Это и есть разделение «исполнителя» и «проверяющего»: Anthropic прямо отмечает в статье о harness, что agent уверенно хвалит собственную работу («confidently praised their work»), поэтому hooks внедряют детерминированные проверки вместо доверия самооценке модели.

3. Subagent (изоляция контекста). История диалога каждого subagent хранится в отдельном файле sidechain и не раздувает контекст родительского agent (см. разбор VILA Lab). Здесь объединены «границы задачи» и «изоляция контекста»: при разделении задач одновременно изолируется загрязнение контекста.

Наблюдаемость и сохранение session

Логи Claude Code представляют собой полную дописываемую историю в history.jsonl, а явные команды /compact, /clear и /init позволяют активно управлять состоянием контекста, не дожидаясь пассивно его заполнения. Команда /init даже превращает принцип из лекции 6 «agent должен инициализироваться перед каждой работой» в одну команду: согласно официальной документации, она автоматически анализирует кодовую базу и создаёт начальный CLAUDE.md с командами сборки, инструкциями по тестированию и инженерными соглашениями.

Сопоставление с фреймворком курса

Подсистема	Реализация Claude Code	Оценка
Инструкции	Иерархия областей действия (организация/пользователь/проект/локальная среда) + auto memory	Многоуровневая память — эталонная реализация
Инструменты	Четыре типа расширений: skills + MCP + hooks + subagents	Чёткое разделение ответственности — ключевое преимущество
Среда	Настройки проекта + settings.json	Пользователь самостоятельно описывает её в CLAUDE.md
Состояние	Дописываемое хранилище session + пятиуровневая compaction + resume/fork	Очень мощная реализация и ориентир для непрерывности длительных задач
Обратная связь	Классификатор permissions + принудительные проверки через hook PostToolUse	Превращает предотвращение преждевременного объявления о завершении в детерминированный механизм

Дизайнерские решения, которые стоит перенять

1. Разделяйте инструкции по области действия, а не складывайте их в один файл. CLAUDE.md на уровне каталога — элегантная реализация «загрузки по месту».
2. Compaction — многоступенчатая воронка: сначала без потерь, затем с потерями; не начинайте сразу с summary всего текста.
3. Используйте hooks для детерминированных проверок: runtime-принуждение, а не просьба в prompt, предотвращает преждевременное объявление о завершении.
4. Изолируйте контекст subagent: разделяйте одновременно задачи и контекст, чтобы результаты подзадач не загрязняли основной цикл.
5. Дописываемое и воспроизводимое хранилище session: надёжный handoff обеспечивает слой хранения, а не память.

Источники (оригинальные материалы / исходный код)

Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:

• Официальная документация Claude Code · Memory: новый контекст для каждой session, четыре области действия CLAUDE.md, загрузка по требованию из подкаталогов, auto memory (200 строк / 25KB), создание CLAUDE.md командой /init.
  https://code.claude.com/docs/en/memory
• Официальная документация Claude Code · Skills / MCP / Hooks / Sub-agents: определения четырёх механизмов расширения и событий (PreToolUse / PostToolUse / Stop).
  https://code.claude.com/docs/en/skills ｜ https://code.claude.com/docs/en/mcp ｜ https://code.claude.com/docs/en/hooks ｜ https://code.claude.com/docs/en/sub-agents
• VILA Lab «Dive into Claude Code» (отчёт с разбором исходного кода): пятиуровневый конвейер compaction, семь режимов permissions + ML-классификатор, sidechain для subagent и дописываемое хранилище session history.jsonl.
  https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
• Anthropic «Effective harnesses for long-running agents»: источник тезисов «надёжность обеспечивает harness, а не модель», о склонности agent уверенно хвалить собственную работу и об использовании hooks для верификации.
  https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• Обзор Claude Code Full Stack (сообщество; разделение CLAUDE.md / Skills / MCP / Subagents / Hooks): дополнительное чтение о разделении ответственности между механизмами расширения.
  https://jsmanifest.com/claude-code-full-stack-guide

Связанные лекции: лекция 3 «Как сделать репозиторий единственным источником истины» ｜ лекция 9 «Как не дать agent преждевременно объявить о победе» ｜ лекция 10 «Настоящая верификация требует прохождения полного процесса»