Архитектура Agent Harness в Claude Code: Технический разбор

Пока я строил собственную систему вызова инструментов, меня постоянно преследовал один вопрос: почему подключение инструментов ощущается значительно сложнее, чем составление промптов?

С самой моделью всё стало понятно быстро. Но как только мне понадобилось, чтобы она действовала — читала файлы, выполняла команды оболочки, общалась с внешними сервисами — каждое решение казалось потенциально разрушительным. Границы разрешений. Ограничения контекста. Диспетчеризация инструментов.

Затем, в конце марта 2026 года, исходный код Claude Code был случайно раскрыт через source map пакета npm в версии 2.1.88. Более 500 000 строк TypeScript — скопированы за несколько часов. Anthropic подтвердила, что это была ошибка упаковки, данные клиентов не пострадали, и начала рассылать уведомления DMCA.

Но архитектура стала общедоступной. И то, что она обнажила, было не моделью. Это был харнес.

Примечание об источниках: Изложенные здесь детали основаны на анализах сообщества, воспроизведениях с открытым исходным кодом, а также на публичной документации и инженерном блоге Anthropic — но не на самом утёкшем коде. Неточные детали отмечены отдельно.

Что такое харнес агента?

Определение и роль в агентных системах

Харнес агента — это всё, что находится между языковой моделью и реальным миром. Модель генерирует текст. Харнес определяет, чего этот текст может касаться.

Документация Anthropic для Claude Code описывает это прямо: Claude Code «предоставляет инструменты, управление контекстом и среду выполнения, которые превращают языковую модель в способного агента для написания кода». Модель рассуждает. Харнес действует.

Когда ваш агент читает файл, харнес решает, разрешено ли это чтение, что происходит с результатом и сколько из ответа поместится в следующий промпт. Модель никогда не обращается к файловой системе напрямую.

Почему проектирование харнеса важно для production

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

Инженерная команда Anthropic писала об этом: даже передовая модель, работающая в цикле на множестве контекстных окон, будет показывать низкие результаты без хорошо спроектированного харнеса. Агент пытается сделать слишком много сразу или преждевременно объявляет задачу выполненной. Харнес навязывает структуру этой тенденции.

Поверхность инструментов Claude Code

Основные категории инструментов

Согласно официальной документации Claude Code и публичным анализам, Claude Code предоставляет примерно 19 инструментов с контролем разрешений. Основные категории: чтение и редактирование файлов, выполнение команд оболочки (Bash), операции Git, веб-запросы, редактирование блокнотов и вызовы инструментов MCP. По оценкам аналитиков сообщества, их может быть около 40, если учитывать интеграцию с LSP, порождение дочерних агентов и внутренние инструменты координации.

Каждый инструмент изолирован независимо. Не «агент имеет доступ к файловой системе» — а «агент может использовать инструмент Read, у которого есть собственный шлюз разрешений, проверяющий цепочку правил перед любым выполнением».

Как регистрируются и диспетчеризируются инструменты

Модель решает, что нужно попробовать. Система инструментов решает, что разрешено. Архитектурно разделены.

Каждый вызов инструмента проходит через проверку разрешений до выполнения. По описаниям глубоких разборов сообщества, существует основная функция, которая оценивает правила запрет/спросить/разрешить именно в этом порядке — запрет всегда побеждает. Три возможных исхода: выполнить без запроса, запросить подтверждение у пользователя или заблокировать.

Взломанная модель не сможет обойти проверки безопасности с помощью убеждения. Харнесу всё равно, какой аргумент приводит модель. Правила есть правила.

Уровни разрешений

Модель разрешений Claude Code описывалась несколькими аналитиками сообщества примерно как три уровня:

Уровень 1 — Автоматическое одобрение: Действия только для чтения или изначально безопасные. Чтение файлов, текстовый поиск, навигация по коду. Они не изменяют состояние, поэтому выполняются без перебоев.

Уровень 2 — Запрос подтверждения: Действия, изменяющие состояние контролируемым образом. Редактирование файлов, определённые команды оболочки. В режиме авто (введённом в марте 2026 года), фоновый классификатор на базе Sonnet 4.6 оценивает, можно ли выполнить их без запроса. Классификатор видит запрос пользователя и вызов инструмента, но не прозаический вывод модели — намеренное проектное решение, чтобы модель не могла уговорить систему пропустить её через шлюз. Уровень 3 — Требуют явного одобрения или блокируются: Операции с высоким риском. Команды оболочки, способные непредсказуемо изменить состояние системы, операции за пределами рабочей директории, всё, что напоминает утечку данных.

Одна оговорка: трёхуровневая концепция взята из анализов сообщества, а не из официальной документации Anthropic. Официальная система использует правила allow/ask/deny и шесть режимов разрешений (default, acceptEdits, plan, auto, dontAsk, bypassPermissions). «Три уровня» — полезная ментальная модель, но упрощение.

Управление сессиями и контекстом

Как Claude Code отслеживает состояние сессии

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

Сессии сохраняются локально. Каждое сообщение, каждый вызов инструмента и каждый результат хранятся, что позволяет откатываться, возобновлять работу и создавать ответвления. Перед изменениями кода харнес делает снимки затронутых файлов, чтобы можно было откатиться.

Обрезка вывода и управление стоимостью токенов

Большие выводы инструментов — реальная проблема. Claude Code устанавливает максимум по умолчанию в 25 000 токенов для вывода инструментов MCP с предупреждением при 10 000 токенов. Авторы серверов могут аннотировать инструменты, чтобы разрешить более крупные результаты (до 500 000 символов), которые сохраняются на диск, а не удерживаются в контексте.

Об этом не задумываешься, пока агент не начнёт тихо терять информацию из-за обрезки результата инструмента. Явные, настраиваемые ограничения с дисковыми резервными вариантами — стоит взять на заметку.

Поведение при компактификации

Это меня подловило до того, как я понял механизм. Когда использование токенов достигает примерно 98% контекстного окна, Claude Code автоматически выполняет компактификацию: суммирует предыдущую историю для освобождения места. Критические метаданные сохраняются. Изображения и PDF удаляются.

Сложность в том, что компактификация может потерять важные детали. Практическое решение: помещать всё критичное в CLAUDE.md, который харнес перечитывает при каждом ходу.

Исследования Anthropic в области проектирования харнесов показали, что полные сбросы контекста — когда новый экземпляр агента берёт задачу из артефакта передачи — иногда работают лучше, чем компактификация для расширенных сессий. Больше сложности оркестрации, зато лучшая точность контекста.

Уровень интеграции MCP

Как Claude Code подключается к серверам MCP

MCP (Model Context Protocol) — открытый стандарт для подключения инструментов ИИ к внешним сервисам. Claude Code поддерживает три транспортных режима: HTTP (рекомендован для удалённых серверов), stdio (для локальных процессов) и SSE.

Добавить сервер — одна команда: claude mcp add server-name --transport http "URL". После этого инструменты сервера появляются как вызываемые инструменты в сессии, подчиняясь той же цепочке разрешений, что и встроенные.

Обнаружение инструментов и потоки аутентификации

Одна деталь, которая меня впечатлила: поиск инструментов. При подключении MCP-серверов Claude Code не загружает все схемы их инструментов в контекст сразу. В начале сессии загружаются только имена инструментов, а затем используется механизм поиска для обнаружения нужных инструментов, когда задача действительно в них нуждается. В контекст попадают только те инструменты, которые использует Claude.

Это сохраняет низкие накладные расходы MCP. Потоки аутентификации зависят от сервера — OAuth, API-ключи, заголовки. Claude Code требует явного одобрения пользователя для новых MCP-серверов.

Что готово к production, а что ещё развивается

Интеграция MCP функциональна и активно используется. Но стоит знать о нескольких практических ограничениях:

Рекомендуемый максимум — около 5–6 активных MCP-серверов, поскольку каждый запускает подпроцесс. Поиск инструментов помогает с накладными расходами контекста, но задержка всё равно нарастает за этой отметкой. Большие ответы MCP требуют тщательной обработки. Ограничение по умолчанию в 25 тысяч токенов подходит для большинства случаев, но становится тесным для схем баз данных. Резервное сохранение на диск помогает, хотя модель получает только ссылку, а не полный результат в контексте.

Качество MCP-серверов, созданных сообществом, неодинаково. В документации Anthropic прямо отмечается, что сторонние серверы могут быть векторами инъекции промптов. Система разрешений помогает, но ответственность за доверие по-прежнему на вас.

Уроки для разработчиков

Что эта архитектура раскрывает о production-агентных системах

Несколько паттернов из проектирования Claude Code, которые, на мой взгляд, применимы в общем случае:

Разделите рассуждение и применение разрешений. Модель решает, что она хочет сделать. Другая система решает, разрешено ли это. Взломанная модель не сможет обойти проверки безопасности, потому что это буквально другой путь выполнения кода.

Сделайте управление контекстом явным. Компактификация, ограничения на обрезку, поиск инструментов, сохранение на диск — всё это механизмы активного управления тем, что видит модель. Большинство любительских реализаций агентов воспринимают контекст как бездонный мешок. Это не так.

Проектируйте с учётом непрерывности сессий. Снимки состояния, обратимые изменения файлов, CLAUDE.md как постоянный якорь. Долгоработающим агентам нужна память, которая переживает сжатие контекста.

Детализированность разрешений окупается. Правила для каждого инструмента, каждого паттерна, каждой директории с оценкой «запрет прежде всего». Больше работы, чем флаг «разрешить всё», но это разница между демо и deployable-системой.

Когда строить собственный харнес, а когда использовать управляемый слой

Узкая, чётко определённая задача — CI-бот, запускающий тесты и публикующий результаты — вы можете сами подключить минимальный харнес. Несколько инструментов, простая проверка разрешений, фиксированное контекстное окно.

Расширенные сессии, состояние после сбросов контекста, ненадёжный вывод инструментов, десятки инструментов — используйте существующий харнес или тщательно изучите один из них. Claude Agent SDK, архитектура Codex от OpenAI, LangGraph — все они решали проблемы, с которыми вы рано или поздно столкнётесь.

Большинство команд недооценивают сложность харнеса. Я тоже это сделал. Модель — это простая часть.

Часто задаваемые вопросы

Что такое харнес агента Claude Code?

Инфраструктурный слой между моделью Claude и реальным миром — диспетчеризация инструментов, разрешения, управление контекстом, состояние сессии, подключения MCP. Anthropic описывает его как то, что «превращает языковую модель в способного агента для написания кода».

Как Claude Code обрабатывает разрешения для инструментов?

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

Готова ли интеграция MCP в Claude Code к production?

Функциональна и активно используется, но с практическими ограничениями по количеству серверов, размеру ответов и доверию к сторонним разработчикам. Развивается быстро.

Могу ли я построить собственный харнес по тем же паттернам?

Да. Claude Agent SDK предоставляет те же режимы разрешений, хуки и управление контекстом. Проекты сообщества, такие как Everything Claude Code, также задокументировали повторно используемые паттерны.

В чём разница между паритетом спецификации и паритетом поведения?

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

Кое-что не выходит у меня из головы: харнес — это сложная часть. Все считают, что модель и есть конкурентное преимущество. И это так — до тех пор, пока вы не попытаетесь заставить её действовать надёжно дольше пяти минут. Именно здесь живёт инженерия.

Предыдущие публикации: