Архитектура Claude Code: принципы и устройство системы (Часть 1 из 5)

Часть 1 из 5 · Серия «Архитектура Claude Code» → /claude-code-series

1. Введение

Программирование с помощью ИИ прошло путь от инструментов автодополнения вроде GitHub Copilot (Chen et al., 2021) через интегрированных в IDE ассистентов вроде Cursor (Cursor, 2026) до полностью агентных систем, которые автономно планируют многошаговые правки, выполняют shell-команды, читают и пишут файлы и итерируются на собственных результатах. Claude Code (Anthropic, 2026a) — агентный инструмент программирования, выпущенный Anthropic (Anthropic, 2026c). Его официальная документация описывает «agentic loop» (агентный цикл), который планирует и выполняет действия к цели, умеет вызывать инструменты, оценивать результаты и продолжать работу до завершения задачи¹. Этот переход от подсказок к автономному действию порождает архитектурные требования, каких нет у инструментов автодополнения. Такие требования задают пространство проектирования — набор повторяющихся вопросов о безопасности, управлении контекстом, расширяемости и делегировании, на которые должен ответить любой агент программирования. Наша работа использует анализ исходного кода Claude Code как одной промышленной системы, чтобы показать, как она отвечает на эти вопросы.

Несмотря на растущую популярность, Anthropic публикует документацию для пользователей, но не детальные архитектурные описания. Мы используем анализ исходного кода для описания архитектурных решений проектирования. Внутренний опрос Anthropic 132 инженеров и исследователей (Huang et al., 2025) сообщает, что около 27% задач, выполненных с помощью Claude Code, не были бы даже начаты без этого инструмента, — то есть архитектура даёт качественно новые рабочие процессы, а не просто ускоряет существующие.

¹ https://code.claude.com/docs/en/how-claude-code-works.

Сначала мы выделяем пять человеческих ценностей/философий и тринадцать принципов проектирования, мотивирующих архитектуру (Section 2), а затем организуем анализ в три части:

1. Анализ пространства проектирования (Design-space analysis). Мы выделяем повторяющиеся вопросы проектирования (где живут рассуждения, как структурирован итерационный цикл, какую позицию по безопасности занимать, как разделена поверхность расширений, как управляется контекст, как работа делегируется субагентам и как сохраняются сессии) и разбираем ответы Claude Code через семикомпонентную высокоуровневую структуру и пятислойную архитектуру подсистем, прослеживая каждое решение к конкретным исходным файлам (Section 3). Цель анализа — построить глубокое понимание механизма системы, чтобы лучше проектировать более мощные агентные системы.
2. Архитектурное сравнение с OpenClaw (Architectural contrast with OpenClaw). Помимо анализа самого Claude Code, мы сравниваем его философию проектирования с OpenClaw (Steinberger and OpenClaw Contributors, 2026) — open-source системой ИИ-агентов в виде многоканального шлюза персонального ассистента — по шести измерениям проектирования. Это показывает, как одни и те же повторяющиеся вопросы дают разные ответы в разных контекстах развёртывания (Section 10) и выявляет общие принципы и ключевые различия между коммерческим и open-source ПО. Сравнение помогает увидеть, как контекст развёртывания, цели продукта, требования безопасности и пользовательские допущения формируют архитектурный выбор. Изучая, где системы сходятся и где расходятся, мы даём практические рекомендации для проектирования будущих, более сильных агентных систем.
3. Открытые направления для будущих агентных систем (Open directions for future agent systems). Опираясь на анализ пространства проектирования и сравнение с OpenClaw, Section 12 называет шесть открытых направлений: разрыв «наблюдаемость — оценка», межсессионная устойчивость (cross-session persistence), эволюция границ harness, масштабирование горизонта, управление (governance) и оценочная оптика. Каждое направление опирается на эмпирическую, архитектурную и политическую литературу. Как оценочная оптика анализ также раскрывает открытый вопрос: агентная система Claude Code существенно усиливает краткосрочные возможности программистов и конечных пользователей, но предлагает ограниченные механизмы, явно поддерживающие долгосрочное развитие человека, более глубокое понимание и устойчивую согласованность кодовой базы.

Ядро агентного цикла — while-true-цикл с управлением состоянием. Окружающие подсистемы безопасности, расширяемости, управления контекстом, делегирования и устойчивости составляют большую часть реализации. Анализ на уровне исходного кода² позволяет нам выделить проектные решения, границы подсистем и компромиссы реализации прямо из самой системы, а не выводить их по описаниям продукта.

² Наш анализ основан прежде всего на исходном коде и дополнен официальной документацией Anthropic и избранным анализом сообщества. Section B описывает доказательную базу и методологию.

Сквозной пример (Running example). Чтобы удержать архитектуру конкретной, мы прослеживаем задачу «Fix the failing test in auth.test.ts» через Section 3–Section 9. Этот пример показывает, как казалось бы простой запрос пользователя активирует несколько архитектурных слоёв: вызов инструментов, проверки разрешений, выбор контекста, итеративное исправление, делегирование и сохранение сессии.

Организация статьи. Section 2 называет человеческие ценности и принципы проектирования, мотивирующие архитектуру. Section 3 вводит высокоуровневую архитектуру и вопросы проектирования, на которые она отвечает. Sections 4–9 разбирают решения каждой из крупных подсистем. Section 10 противопоставляет анализ OpenClaw, Section 11 даёт обсуждение, а Section 12 обозревает открытые вопросы для будущих агентных систем. Sections 13 и 14 описывают связанные работы и выводы. Section B раскрывает доказательную базу и методологию.

2. Философии, принципы и архитектурные мотивации

Промышленные агенты программирования строятся людьми для людей, и архитектурные решения, которые они воплощают, отражают то, что их создатели считают важным. В этом разделе мы называем человеческие ценности, мотивирующие дизайн Claude Code, прослеживаем их через повторяющиеся принципы проектирования и ставим вопросы пространства проектирования, организующие анализ в Sections 3–9.

Система ценностей Anthropic для безопасных агентов заявляет центральное напряжение: «Агенты должны уметь работать автономно — их независимые действия и есть их главная ценность. Но люди должны сохранять контроль над тем, как достигаются их цели» (Anthropic, 2025a). «Конституция» Claude разрешает это напряжение не жёсткими процедурами, а «культивированием здравого смысла и здоровых ценностей, которые можно применять по контексту» (Anthropic, 2026b). Эти принципы вместе с эмпирическими данными о том, как разработчики на самом деле используют инструмент (Huang et al., 2025; McCain et al., 2026), указывают на пять человеческих ценностей, формирующих архитектуру.

2.1. Пять ценностей и философий

Human Decision Authority (Полномочия человека на принятие решений). Конечные полномочия на принятие решений о действиях системы остаются за человеком. Иерархия субъектов (Anthropic, затем операторы, затем пользователи) формализует, кто и какими правами обладает (Anthropic, 2026b). Система спроектирована так, чтобы человек сохранял осознанный контроль: наблюдал за действиями в реальном времени, одобрял или отклонял предлагаемые операции, прерывал совместимые текущие операции и проверял результат постфактум. Когда Anthropic обнаружил, что пользователи одобряют около 93% запросов на разрешение (Hughes, 2026), реакцией была не добавка новых предупреждений, а переформулирование задачи: определить границы (песочницы, классификаторы авто-режима), внутри которых агент свободен, — вместо одобрений на каждое действие, которые пользователи перестают читать, как только привыкают (Dworken and Weller-Davies, 2025).

Safety, Security, and Privacy (Безопасность, защита, приватность). Система защищает людей, их код, данные и инфраструктуру от вреда, даже когда человек невнимателен или ошибается. Эта ценность отличается от Human Decision Authority: там речь о праве выбора человека, здесь — об обязательстве системы защищать, даже когда это право проваливается. Фреймворк безопасных агентов Anthropic отдельно называет защиту взаимодействий агента и приватности в долгих взаимодействиях ключевыми обязательствами (Anthropic, 2025a). Модель угроз авто-режима (Hughes, 2026) явно выделяет четыре категории риска: чрезмерное рвение (overeager behavior), честные ошибки, prompt injection и рассогласование модели (model misalignment).

Reliable Execution (Надёжное исполнение). Агент делает то, что человек на самом деле имел в виду, остаётся согласован во времени и позволяет проверить работу перед объявлением успеха. Ценность охватывает как корректность одного хода («правильно ли понят запрос?»), так и надёжность на долгом горизонте («остаётся ли согласованность через границы контекстного окна, возобновления сессий и делегирование между агентами?»). Продуктовая документация Anthropic (Anthropic, 2026d) описывает трёхфазный цикл, который агент повторяет до выполнения задачи: собрать контекст, выполнить действие, проверить результат. Руководство по проектированию агентов (Schluntz and Zhang, 2024) отмечает, что «основанная на окружении правда» на каждом шаге оценивает прогресс. Руководство по harness-дизайну (Rajasekaran, 2026) также предупреждает: «агенты склонны уверенно хвалить собственную работу», даже когда качество среднее, — отсюда необходимость разделения генерации и оценки.

Capability Amplification (Усиление возможностей). Система существенно увеличивает то, чего человек может достичь на единицу усилий и стоимости. Внутренний опрос Anthropic (Huang et al., 2025), обсуждаемый в Section 1, указывает на качественно новые рабочие процессы, а не просто на ускорение существующих: около 27% задач не были бы даже начаты без инструмента. Создатели описывают систему как «Unix-утилиту, а не традиционный продукт», построенную из мельчайших кирпичей, «полезных, понятных и расширяемых» (Cherny and Wu, 2025). Архитектура вкладывается в детерминистскую инфраструктуру (управление контекстом, маршрутизация инструментов, восстановление), а не в каркасы принятия решений (явные планировщики или state graphs), исходя из того, что всё более сильные модели больше выигрывают от богатой операционной среды, чем от фреймворков, ограничивающих их выбор.

Contextual Adaptability (Контекстная адаптивность). Система подстраивается под конкретный контекст пользователя (проект, инструменты, конвенции, уровень навыка), и отношения улучшаются со временем. Архитектура расширений (CLAUDE.md, навыки, MCP, хуки, плагины) даёт настраиваемость на разных уровнях контекстной стоимости (Sections 6 и 7). Лонгитюдные данные (McCain et al., 2026) показывают, что отношения «человек — агент» эволюционируют: доля авто-одобрений растёт с примерно 20% при менее чем 50 сессиях до более 40% к 750-й сессии. Эту картину, описанную как автономия, «сконструированная совместно моделью, пользователем и продуктом», отражает дизайн, ориентированный на траектории доверия, а не на фиксированные состояния доверия. Передача MCP в Agentic AI Foundation в составе Linux Foundation (The Linux Foundation, 2025) отражает экосистемное измерение этой ценности.

Table 1. Принципы проектирования, обслуживаемые ценности и вопросы проектирования

Table 1 Design principles, the values they serve, and the design-space question each answers. Principles map to multiple values; implementations appear in the sections indicated.

2.2. Принципы проектирования

Эти ценности операционализированы через тринадцать принципов проектирования — каждый отвечает на повторяющийся вопрос, который должен решить промышленный агент программирования. Table 1 сводит принципы; последующие разделы (Section 3–Section 9) прослеживают каждый к конкретным реализационным решениям.

Эти принципы можно прочитать на фоне трёх крупных альтернативных семейств. Первое — rule-based orchestration (оркестрация на основе правил): фреймворки вроде LangGraph (LangChain, Inc., 2024) кодируют логику решений как явные state graphs с типизированными рёбрами, выбирая каркас вместо минимального harness. Второе — container-isolated execution (изолированное в контейнере исполнение): SWE-Agent и OpenHands (Yang et al., 2024; Wang et al., 2024b) полагаются на изоляцию Docker, а не на слоистую политику. Третье — version-control-as-safety (система контроля версий как защита): инструменты вроде Aider (Gauthier, 2024) используют git-откат как главный механизм безопасности, а не оценку deny-first. Набор принципов Claude Code выделяется сочетанием минимального каркаса решений со слоистой политикой, суждения на ценностях с deny-first по умолчанию и прогрессивного управления контекстом с составной расширяемостью.

2.3. От ценностей к архитектуре

Каждая ценность прослеживается через свои принципы к конкретным архитектурным решениям:

Figure 1 High-level system structure of Claude Code. The system decomposes into seven functional components: user, interfaces, the agent loop, a permission system, tools, state & persistence, and an execution environment. All entry surfaces converge on the same agent loop.

Рисунок 1. Высокоуровневая структура системы Claude Code. Система раскладывается на семь функциональных компонентов: пользователь, интерфейсы, агентный цикл (agent loop), система разрешений (permission system), инструменты (tools), состояние и устойчивость (state & persistence) и среда исполнения (execution environment). Все точки входа сходятся в одном агентном цикле.

          ┌──────────────────┐
          │ Permission       │
          │ System       ✓   │
          └──────────────────┘
             Propose │ ▲ Allow
             Action  │ │ Ask / Deny
                     ▼ │
┌──────┐  Prompt / ┌────────┐       ┌──────┐      ┌──────────────┐
│ User │─Command──▶│Inter-  │Request│Agent │ Tool │ Tools        │
│      │  Task     │faces   │──────▶│Loop  │─────▶│ </>          │
│  👤  │◀─Progress─│  </>   │◀──────│  ⟲   │Result│              │
└──────┘           └────────┘       └──────┘      └──────────────┘
                                      │  ▲                │
                                  Load│  │Persist         ▼
                                      ▼  │         ┌──────────────┐
                                  ┌──────────┐     │ Execution    │
                                  │ State &  │     │ Environment  │
                                  │ Persist. │     │ Files/Shell/ │
                                  │   🗄     │     │ Web / MCP    │
                                  └──────────┘     └──────────────┘

• Human Decision Authority мотивирует deny-first-оценку, graduated trust spectrum, append-only state (проверяемая история), externalized programmable policy и values-over-rules (Sections 5–7 и 9).
• Safety, Security, and Privacy мотивирует defense in depth, deny-first defaults, reversibility-weighted assessment, externalized policy и isolated subagent boundaries (Sections 5 и 8).
• Reliable Execution мотивирует context-as-scarce-resource, append-only durable state, graceful recovery, isolated subagent boundaries и defense in depth (Sections 4 и 7–9).
• Capability Amplification мотивирует minimal scaffolding, composable extensibility, reversibility-weighted risk и graceful recovery (Sections 4–6).
• Contextual Adaptability мотивирует transparent file-based memory, composable extensibility, graduated trust spectrum и externalized programmable policy (Sections 5–7).

Эти отображения также раскрывают, чего архитектура не делает: она не накладывает явных графов планирования на рассуждение модели, не предоставляет единого унифицированного механизма расширения и не восстанавливает всё сессионно-ограниченное состояние доверия при возобновлении. Эти отсутствия согласуются с набором принципов выше.

2.4. Оценочная оптика: долгосрочное сохранение возможностей

Пять ценностей описывают, чему архитектура служит. Статья применяет и шестую заботу — сохраняет ли архитектура долгосрочные возможности человека, — как оценочную оптику. Забота реальна: собственное исследование Anthropic 132 инженеров и исследователей (Huang et al., 2025) документирует «парадокс надзора», при котором чрезмерная опора на ИИ рискует атрофией навыков, нужных для самого надзора, а независимое исследование (Shen and Tamkin, 2026) находит, что разработчики в условиях ИИ-поддержки показывают на 17% ниже по тестам на понимание. Тем не менее эта забота слабо отражена как драйвер проектирования в архитектуре или в заявленных ценностях Anthropic. Мы поэтому считаем её не равнозначной ценностью, а сквозной: как вопрос ко всем пяти ценностям в Section 11 — приходит ли краткосрочное усиление ценой долгосрочного понимания, согласованности кодовой базы и здоровья конвейера разработчиков.

3. Обзор архитектуры

Построение промышленного агента программирования требует ответов на несколько повторяющихся вопросов: где должны жить рассуждения, сколько движков исполнения нужно, какую позицию по безопасности занимать и какой ресурс считать обязывающим ограничением. Архитектуру Claude Code можно читать как один набор ответов. На уровне реализации система состоит из семи компонентов, связанных главным потоком данных: пользователь отправляет запрос через один из интерфейсов, который кормит общий агентный цикл. Цикл собирает контекст, вызывает модель Claude, получает ответы, которые могут содержать запросы на использование инструментов, маршрутизирует эти запросы через систему разрешений и отправляет одобренные действия к конкретным инструментам, взаимодействующим со средой исполнения. На всём протяжении процесса механизмы состояния и устойчивости записывают транскрипт диалога, управляют идентичностью сессии и поддерживают операции resume, fork и rewind.

3.1. Вопросы проектирования и сквозной пример

Описание организовано вокруг четырёх вопросов, повторяющихся для промышленных агентов программирования, — каждый опирается на один или несколько принципов из Table 1. Для каждого вопроса мы даём ответ Claude Code, заметку о правдоподобных альтернативах и постепенную демонстрацию через Sections 4–9.

Где живут рассуждения? (Where does reasoning live?) В Claude Code модель рассуждает о том, что делать; harness отвечает за выполнение действий. Модель выдаёт tool_use-блоки как часть ответа, harness их разбирает, проверяет разрешения, отправляет к реализациям инструментов и собирает результаты (query.ts). Модель никогда не обращается напрямую к файловой системе, не запускает shell-команды и не делает сетевые запросы. У разделения есть последствие для безопасности: поскольку рассуждение и энфорсмент занимают разные ветки кода, скомпрометированная или adversarially-манипулированная модель не может обойти песочницу, проверки разрешений или правила deny-first, реализованные в harness. Единственный интерфейс модели с внешним миром — структурированный протокол tool_use, который harness валидирует перед исполнением. Анализ сообщества на извлечённом исходнике оценивает, что лишь около 1.6% кодовой базы Claude Code — это логика решений ИИ, остальные 98.4% — операционная инфраструктура. Это отношение показывает, насколько тонкий центральный слой рассуждений агента. Альтернативные дизайны вкладываются сильнее в рассуждение на стороне каркаса: Devin поддерживает явные планирующие и трекинговые структуры, а LangGraph (LangChain, Inc., 2024) маршрутизирует поток управления через state graphs, определённые разработчиком.

Сколько движков исполнения? (How many execution engines?) Claude Code использует единственную функцию queryLoop(), которая выполняется независимо от того, взаимодействует ли пользователь через интерактивный терминал, headless-вызов CLI, Agent SDK или IDE-интеграцию (query.ts). Меняется только рендеринг и слой пользовательского взаимодействия. Другие системы используют режим-специфичные движки: например, IDE-интеграция может идти по иному коду, чем CLI-инструмент, жертвуя единообразием ради поверхностной оптимизации.

Какова позиция безопасности по умолчанию? (What is the default safety posture?) Claude Code по умолчанию использует deny-first-с эскалацией к человеку: правила deny перекрывают ask, ask перекрывает allow, нераспознанные действия эскалируются к пользователю, а не тихо допускаются (permissions.ts). Несколько независимых слоёв безопасности (правила разрешений, хуки PreToolUse, классификатор авто-режима при включении, опциональная shell-песочница) работают параллельно, так что любой один слой может заблокировать действие (Section 5). Это сочетает принципы deny-first with human escalation и defense in depth with layered mechanisms из Table 1. Альтернативные подходы смещают границу доверия в другое место: SWE-Agent и OpenHands (Yang et al., 2024; Wang et al., 2024b) полагаются на контейнерную изоляцию для произвольного исполнения, а Aider (Gauthier, 2024) использует git-откат как главный щит.

Какое обязывающее ограничение ресурса? (What is the binding resource constraint?) В Claude Code это контекстное окно (200K токенов для старых моделей, 1M для серии Claude 4.6). Пять различных стратегий сокращения контекста выполняются перед каждым вызовом модели (query.ts), плюс ряд подсистемных решений (lazy loading инструкций, deferred tool schemas, subagent summary-only returns) ограничивают потребление контекста (Section 7). Пятислойный конвейер существует потому, что ни одна стратегия уплотнения не закрывает все типы давления на контекст. Budget reduction нацеливается на отдельные выходы инструментов, переполняющие лимиты размера. Snip управляет временной глубиной. Microcompact реагирует на накладные расходы кэша. Context collapse управляет очень длинными историями. Auto-compact как крайняя мера делает семантическое сжатие. Каждый слой работает в своём соотношении стоимость/выгода, и более ранние и дешёвые слои выполняются раньше более дорогих. Альтернативные архитектуры считают узким местом другие ресурсы: например, бюджет вычислений (ограничение числа вызовов модели или инструментов) или рабочую память (явный блокнот вместо истории диалога).

Сквозной пример. Чтобы закрепить принципы, мы протаскиваем через Sections 3–9 одну задачу: «Fix the failing test in auth.test.ts.» В этом разделе пользователь отправляет запрос через один из интерфейсов Claude Code. Следующие разделы прослеживают запрос через цикл запросов, ворота разрешений, пул инструментов, контекстное окно, делегирование субагентам и сохранение сессии.

Figure 2 Runtime turn flow showing the end-to-end execution of a single agentic turn: user prompt enters through context assembly, the model is called, tool requests pass through the permission gate, tool results feed back into the loop, and compaction manages context pressure.

Рисунок 2. Поток одного агентного хода на этапе выполнения: пользовательский prompt попадает через сборку контекста, вызывается модель, запросы инструментов проходят ворота разрешений, результаты инструментов возвращаются в цикл, а compaction управляет давлением контекста.

User Prompt  👤
     │
     ▼
┌──────────────────────────────┐
│ Context Assembly             │
│ (settings, history)          │
└──────────────────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────────────┐
│ Iter 1  🔶 ─▶ Tool Request 🛠 ─▶ Permission ✓ ─┐         │
│                                           Allow │        │
│                                                 ▼        │
│              Compact           ┌───────────────────┐     │
│             (context           │ Execute ─▶ Result │     │
│              pressure)         │ Sync / Subagent / │     │
│                                │ Background        │     │
│                                └───────────────────┘     │
│ Iter 2  🔶 ─▶ Tool Request 🛠 ─▶ Permission ✗            │
│                                           Deny ─▶        │
│                                  ┌──────────────────┐    │
│                                  │ Deny Feedback    │    │
│                                  └──────────────────┘    │
│              More Iterations                             │
│     …                                                    │
│ Iter N  🔶 ─▶ No Tool Use ─▶ Assistant Response          │
└──────────────────────────────────────────────────────────┘
     │
     ▼
User Reads & Replies 👤 </>

3.2. Высокоуровневая структура системы

Семикомпонентная модель (Figure 1) отображается прямо на исходные файлы:

1. User (Пользователь). Отправляет запросы, одобряет разрешения, просматривает вывод.
2. Interfaces (Интерфейсы). Интерактивный CLI, headless CLI (claude -p), Agent SDK и IDE/Desktop/Browser. Все поверхности кормят один и тот же цикл.
3. Agent loop (Агентный цикл). Итеративный цикл вызова модели, отправки инструментов и сбора результатов, реализованный как async-генератор queryLoop() в query.ts.
4. Permission system (Система разрешений). Оценка правил deny-first (permissions.ts), ML-классификатор авто-режима и перехват на основе хуков (types/hooks.ts).
5. Tools (Инструменты). До 54 встроенных инструментов (19 безусловных, 35 условных по feature flags и типу пользователя), собранных через assembleToolPool() (tools.ts) и объединённых с инструментами, предоставленными MCP. Плагины вкладываются косвенно через MCP-серверы и реестр навыков/команд.
6. State & persistence (Состояние и устойчивость). В основном append-only JSONL транскрипты сессий (sessionStorage.ts), глобальная история промптов (history.ts) и файлы sidechain субагентов.
7. Execution environment (Среда исполнения). Выполнение shell-команд с опциональной песочницей (shouldUseSandbox.ts), файловые операции, веб-запросы, подключения к MCP-серверам и удалённое выполнение.

Поток данных идёт по хребту слева направо: пользователь отправляет запрос через интерфейс, который попадает в агентный цикл. Цикл предлагает действия системе разрешений; одобренные доходят до инструментов, которые взаимодействуют со средой исполнения и возвращают tool_result в цикл. Состояние и устойчивость расположены рядом с циклом, записывая транскрипты и подгружая данные прошлых сессий.

Точка входа приложения main() в main.tsx инициализирует настройки безопасности (включая NoDefaultCurrentDirectoryInExePath для предотвращения Windows PATH hijacking), регистрирует обработчики сигналов для мягкого завершения и отправляет запрос в нужный режим исполнения.

Figure 3 Expanded layered architecture showing five subsystem layers: surface (Interactive CLI, Headless CLI, Agent SDK, IDE/Desktop/Browser, UI/renderer), core (agent loop, compaction pipeline), safety/action (permission system incl. auto-mode classifier, hook pipeline, extensibility, built-in tools, MCP tools, shell sandbox, subagent spawning), state (context assembly, runtime state, session persistence, CLAUDE.md + memory, sidechain transcripts), and backend (execution backends, external resources).

Рисунок 3. Расширенная слоистая архитектура: пять слоёв подсистем — surface (интерактивный CLI, headless CLI, Agent SDK, IDE/Desktop/Browser, UI/renderer), core (агентный цикл, compaction pipeline), safety/action (система разрешений вкл. auto-mode классификатор, hook pipeline, расширяемость, встроенные инструменты, MCP-инструменты, shell-песочница, запуск субагентов), state (сборка контекста, runtime-состояние, устойчивость сессий, CLAUDE.md + memory, sidechain-транскрипты) и backend (backends исполнения, внешние ресурсы).

3.3. Слоистая декомпозиция подсистем

Пятислойная декомпозиция (Figure 3) расширяет семикомпонентную модель в более тонкий вид, отображая каждый слой на конкретные директории исходника.

Surface layer (точки входа и рендеринг). Директория src/entrypoints/ содержит стартовые пути, включая SDK-точку входа с coreTypes.ts, controlSchemas.ts и coreSchemas.ts. Директория src/screens/ собирает полноэкранные раскладки, а src/components/ даёт строительные блоки UI через фреймворк ink. Интерактивный CLI запускает терминальный UI с real-time стримингом, диалогами разрешений и индикаторами прогресса. Headless CLI (claude -p) создаёт экземпляр QueryEngine для одноразовой обработки. Agent SDK выдаёт типизированные события через async-генераторы.

Core layer (агентный цикл, compaction pipeline). Async-генератор queryLoop() (query.ts) реализует итеративный агентный цикл, потребляющий собранный контекст из state-слоя и отправляющий запросы инструментов в safety/action-слой. Перед каждым вызовом модели compaction pipeline из пяти последовательных shapers (query.ts:365–453) управляет давлением контекста: budget reduction, snip, microcompact, context collapse и auto-compact (Sections 4.3 и 7.3).

Safety/action layer (система разрешений, хуки, расширяемость, инструменты, песочница, субагенты). Permission system (permissions.ts) реализует оценку правил deny-first с до семи режимов разрешений (включая внутренний bubble и gated-по-фичам auto) (types/permissions.ts) и интегрированный auto-mode ML classifier (yoloClassifier.ts), обеспечивающий двухступенчатую быструю фильтрацию и chain-of-thought-оценку безопасности инструмента (Section 5). Hook pipeline на 27 типов событий (coreTypes.ts; схемы вывода в types/hooks.ts) может блокировать, переписывать или аннотировать запросы инструментов: из них 5 связаны с безопасностью, а остальные 22 служат целям lifecycle и оркестрации (Section 6). Подсистема расширяемости позволяет плагинам и навыкам регистрировать инструменты и хуки в runtime. Сборка пула инструментов через assembleToolPool() (tools.ts) объединяет встроенные и MCP-предоставленные инструменты. Одобренные shell-команды проходят shell sandbox (shouldUseSandbox.ts), ограничивающий доступ к файловой системе и сети независимо от системы разрешений. Subagent spawning через AgentTool (AgentTool.tsx, runAgent.ts) отправляется через тот же buildTool()-factory, что и все другие инструменты, повторно заходя в queryLoop() с изолированным контекстным окном и возвращая родителю только сводку (Section 8).

State layer (сборка контекста, runtime-состояние, устойчивость, память, sidechains). Context assembly — это мемоизированный загрузчик состояния, а не маршрутизатор: getSystemContext() (context.ts) вычисляет общесессионный системный контекст, включая git-статус, а getUserContext() (context.ts) загружает иерархию CLAUDE.md и текущую дату. Оба кэшируются для переиспользования: системный контекст дополняется к system prompt, тогда как пользовательский контекст добавляется как user-context-сообщение. Директория src/state/ управляет runtime-состоянием приложения. Транскрипты сессии хранятся как преимущественно append-only JSONL-файлы по проект-специфичным путям (sessionStorage.ts). Подсистема CLAUDE.md + memory предоставляет четырёхуровневую иерархию инструкций (claudemd.ts) от managed-настроек до файлов, специфичных для директорий, плюс авто-записи, которые Claude создаёт по ходу диалога (Section 7.2). Sidechain-транскрипты (sessionStorage.ts:247) хранят диалог каждого субагента в отдельном файле, не давая контенту субагента раздуть родительский контекст (Section 8.3). Глобальная история промптов поддерживается в history.jsonl (history.ts). Операции resume и fork восстанавливают состояние сессии из транскриптов (conversationRecovery.ts).

Backend layer (движки исполнения, внешние ресурсы). Выполнение shell-команд с опциональной песочницей (BashTool.tsx, PowerShellTool.tsx), поддержка удалённого исполнения (src/remote/), соединения с MCP-серверами через несколько транспортов: stdio, SSE, HTTP, WebSocket, SDK и IDE-специфичные адаптеры (services/mcp/client.ts), а также 42 поддиректории инструментов в src/tools/, реализующие конкретную логику инструментов.

3.4. QueryEngine: уточнение

Документация класса в QueryEngine.ts гласит: «QueryEngine владеет жизненным циклом запроса и состоянием сессии для диалога. Он извлекает ядро логики из ask() в отдельный класс, пригодный и для headless/SDK-пути, и (в будущем) для REPL». Класс — conversation wrapper для неинтерактивных поверхностей, не сам движок. Конструктор принимает QueryEngineConfig с начальными сообщениями, abort-контроллером, кэшем состояния файлов и другим per-conversation состоянием. Его метод submitMessage() — async-генератор, оркестрирующий один ход. Общий путь кода запроса живёт в query() (query.ts), оборачивающем внутренний queryLoop(); QueryEngine делегирует к query().

Это различие архитектурно важно: интерактивный CLI также вызывает query(), минуя QueryEngine целиком. Общий путь кода — функция-цикл, а не класс-движок.

3.5. Слои разрешений и безопасности

Принцип safety-by-default реализован через семь независимых слоёв. Запрос должен пройти все применимые слои, и любой из них может его заблокировать:

1. Tool pre-filtering (tools.ts). Инструменты с общим запретом удаляются из обзора модели до любого вызова, не давая модели даже пытаться их вызвать.
2. Deny-first rule evaluation (permissions.ts). Правила deny всегда имеют приоритет над allow, даже когда allow-правило конкретнее.
3. Permission mode constraints (types/permissions.ts). Активный режим задаёт базовую обработку запросов, не попадающих под явное правило.
4. Auto-mode classifier. ML-классификатор оценивает безопасность инструмента, возможно отклоняя запросы, которые пропустила бы система правил.
5. Shell sandboxing (shouldUseSandbox.ts). Одобренные shell-команды могут всё равно выполняться в песочнице, ограничивающей доступ к файловой системе и сети.
6. Not restoring permissions on resume (conversationRecovery.ts). Session-scoped разрешения не восстанавливаются при resume или fork.
7. Hook-based interception (types/hooks.ts). Хуки PreToolUse могут менять решения о разрешениях; хуки PermissionRequest могут решать асинхронно параллельно с пользовательским диалогом (или до него — в координаторном режиме).

Слои подробно описаны в Section 5.

3.6. Контекст как узкое место: за пределами уплотнения

Помимо пятислойного конвейера compaction (подробно в Section 7), несколько других решений подсистем отражают ограничение «контекст как bottleneck»:

• CLAUDE.md lazy loading. Базовая иерархия CLAUDE.md загружается в начале сессии, но дополнительные файлы инструкций из вложенных директорий и условные правила загружаются только когда агент читает файлы в этих директориях — чтобы неиспользуемые инструкции не ели контекст.
• Deferred tool schemas. Когда ToolSearch включён, часть инструментов включает в начальный контекст только имена; полные схемы загружаются по требованию.
• Subagent summary-only return. Субагенты возвращают родителю только сводку, а не полную историю диалога (Section 8).
• Per-tool-result budget. Отдельные результаты инструментов ограничены настраиваемым размером, чтобы один многословный вывод не съел непропорционально много контекста.

Часть 2 — Agent loop и разрешения →