Обвязка решает: как устроены харнессы ИИ-агентов и почему именно они определяют результат
Вопрос "какая нейросеть лучше пишет код?" сегодня звучит почти в каждом разговоре о разработке. Однако сама модель - лишь часть системы. Не меньшее значение имеет программная и процессная обвязка, которая помогает ей работать с файлами, запускать команды, учитывать историю действий и проверять результат. Именно поэтому на практике качество работы определяют не только параметры LLM, но и то, как устроены ИИ-агенты вокруг неё.
В этой статье разберём устройство агентной системы на примере обычного интернет-магазина на Next.js и PostgreSQL. Представим команду из четырёх разработчиков, репозиторий на GitHub и CI на GitHub Actions. Один из разработчиков запускает Claude Code, Codex или Cursor и формулирует задачу: "Сделай кнопку корзины васильковой". Что происходит дальше - и где в этом процессе находятся модель, скаффолд, харнесс и сам агент?
Четыре уровня агентной системы
Удобно разделять систему на четыре составляющие: модель, скаффолд, харнесс и агент. Часто это описывают формулой:
Model + Harness = Agent
Модель - это функция "текст на входе → текст на выходе". Она получает запрос, генерирует ответ и завершает работу. У неё нет постоянной памяти между вызовами, доступа к репозиторию или возможности самостоятельно открыть файл и выполнить команду. В конкретном проекте моделью может быть Claude Opus, GPT-5.x, Gemini, DeepSeek или другая языковая система.
Скаффолд - это набор предварительных условий, с которыми модель начинает работу. Сюда входят системный промпт поставщика, описания доступных инструментов, правила проекта в `CLAUDE.md` или `AGENTS.md`, подключения к внешним сервисам через MCP, а также формат сообщений, который умеет разбирать исполнительный слой.
Именно скаффолд объясняет модели, кто она, какие действия разрешены, как принято оформлять код и каким образом следует запрашивать инструменты. На реальном проекте в контекст могут попадать от нескольких сотен до десятков тысяч токенов инструкций. Если агент постоянно нарушает внутренние соглашения команды, сначала стоит проверить именно этот уровень.
Харнесс - исполнительный механизм вокруг вызова модели. Он собирает промпт из системных правил, истории и текущей задачи, отправляет его в LLM, разбирает ответ, запускает запрошенные действия и возвращает результаты обратно в контекст. Если модель попросила прочитать `cart.ts`, изменить `styles.css` или выполнить `pnpm test`, именно харнесс превращает эти намерения в реальные операции.
К харнессу также относятся управление длинным контекстом, кэширование промптов, песочница, подтверждения опасных команд, откаты, хуки и логика остановки. В привычных инструментах вроде Claude Code, Codex или Cursor разработчик взаимодействует не с "чистой" моделью, а с уже готовым харнессом.
Агентом называют всю связку, которая действует ради цели: модель, исполнительный цикл, инструменты, память и правила принятия решений. Когда говорят, что "агент подготовил pull request", речь идёт не только о нейросети, а о полном конвейере.
Хорошая метафора - автомобиль. Модель в нём похожа на двигатель, харнесс - на трансмиссию и органы управления, а агент - на автомобиль, который действительно движется к заданной цели. Даже мощный двигатель бесполезен без управления, топлива и надёжной передачи усилия.
Подробный разбор того, как такая обвязка выглядит в живом проекте, можно найти в материале о [харнессе для ИИ-агентов и его практической роли](/ru/articles/1079012/?utm_campaign=1079012&utm_source=habrahabr&utm_medium=rss). Там особенно хорошо видно, что большая часть эффективности появляется не в момент генерации текста, а в последующих шагах: чтении файлов, проверках и корректировках.
Из чего складывается исполнительный цикл
Упрощённо цикл выглядит так:
1. Собрать инструкции, историю и задачу.
2. Отправить контекст модели.
3. Получить текстовый ответ или запрос инструмента.
4. Выполнить действие.
5. Добавить результат в историю.
6. Повторять процесс, пока цель не достигнута или выполнение не остановлено.
Сам цикл может занимать всего несколько строк кода. Но реальная разработка ИИ-агентов требует десятков дополнительных решений: сколько файлов разрешать читать за один шаг, когда сжимать историю, как обрабатывать ошибку команды, кто подтверждает опасные действия и каким образом доказывается корректность результата.
Главные слои харнесса
Контекст и его компактность
Контекст быстро разрастается: в него попадают исходная задача, инструкции проекта, содержимое файлов, вывод терминала и предыдущие ответы. Если передавать всё без ограничений, растут стоимость и задержка, а модель начинает хуже выделять главное.
Поэтому харнесс выбирает существенные фрагменты, удаляет устаревшие сообщения, объединяет повторяющуюся информацию и создаёт краткие резюме. Важно не просто "обрезать историю", а сохранить состояние задачи: что уже сделано, какие решения приняты и какие проверки ещё требуются.
Кэширование промптов
Большая часть системных инструкций повторяется в каждом вызове. Кэширование позволяет не оплачивать повторную обработку неизменяемого префикса и заметно снижает задержку. Для длинных правил проекта это становится одним из ключевых факторов экономики.
Поэтому при выборе инструментов для ИИ-агентов важно смотреть не только на заявленное качество модели, но и на работу с кэшем, размером контекста, повторными запросами и стоимостью многошаговых сценариев.
Дизайн инструментов
Инструменты - это интерфейс между языковой моделью и внешним миром. Чем яснее описаны их параметры, ограничения и ожидаемый результат, тем меньше вероятность ошибочного вызова.
Слишком крупный инструмент заставляет модель принимать много решений одновременно. Слишком мелкий создаёт длинную цепочку вызовов. Обычно лучше всего работают операции с понятными границами: чтение конкретного файла, поиск по проекту, применение патча, запуск тестов, просмотр статуса Git.
Права и безопасность
Агенту нельзя безусловно доверять доступ ко всей системе. Команды вроде `rm -rf`, публикация изменений, удаление базы или отправка данных во внешнюю систему должны выполняться в песочнице либо требовать подтверждения.
Практичный подход - разделять операции на безопасные и привилегированные, ограничивать рабочую директорию, использовать временные окружения и вести журнал действий. Безопасность должна быть встроена в харнесс, а не добавляться после первого инцидента.
Верификация
Генерация кода не равна доказательству его корректности. Харнесс может запускать линтеры, модульные и интеграционные тесты, проверять типы, анализировать diff и сравнивать результат с требованиями задачи.
Чем больше автоматических проверок выполняется без участия человека, тем надёжнее процесс. При этом финальное ревью всё равно необходимо: тесты способны подтвердить техническую работоспособность, но не всегда проверяют бизнес-логику и удобство интерфейса.
Процессная обвязка и SDD
У слова "харнесс" есть и более широкий смысл. Это не только программный цикл с инструментами, но и процессная среда, в которой агент получает задачу и сдаёт результат. Сюда входят шаблоны issue, правила ветвления, формат pull request, обязательные проверки CI и критерии готовности.
Отдельное направление - SDD, или разработка через спецификацию. В этом подходе спецификация становится главным описанием поведения системы, а код рассматривается как реализация требований. Агент получает не расплывчатое "сделай авторизацию", а структуру с условиями, ограничениями, примерами и критериями приёмки.
Такой подход снижает число неоднозначностей и облегчает проверку результата. Однако SDD не является универсальным решением: подробная спецификация требует времени, может устареть и иногда ограничивает исследовательскую работу. Наиболее эффективно сочетать её с короткими итерациями и автоматическими тестами.
Что измерять в живом проекте
Чтобы оценить вклад обвязки, полезно вести машинный журнал. В нём можно фиксировать число вызовов модели, объём входных и выходных токенов, количество инструментальных операций, время выполнения, частоту ошибок и долю задач, завершённых без ручной коррекции.
Такие измерения часто показывают неожиданный результат: значительная часть времени уходит не на генерацию кода, а на чтение репозитория, повторные попытки, запуск тестов и исправление неверных предположений. Улучшение описания инструментов или правил проекта способно дать больший эффект, чем переход на другую модель.
Для задач разработки полезно отдельно считать стоимость не одного ответа, а полного успешного сценария. Модель, которая дешевле на один вызов, может оказаться дороже в реальной работе, если ей требуется больше итераций и исправлений.
Практический чеклист
Перед внедрением агентного инструмента стоит проверить:
- есть ли в репозитории единый файл правил;
- понятно ли описаны доступные команды и инструменты;
- разделены ли безопасные и привилегированные действия;
- умеет ли система сжимать длинный контекст;
- используется ли кэширование повторяющихся инструкций;
- запускаются ли тесты и проверки автоматически;
- сохраняется ли журнал действий;
- предусмотрен ли откат изменений;
- определены ли критерии завершения задачи;
- понятно ли, в какой момент требуется человеческое ревью.
Разработка ИИ-агентов - это не соревнование моделей по качеству отдельных ответов. Надёжность формируется всей системой: контекстом, инструментами, правами, проверками и процессом. Именно поэтому автоматизация разработки с ИИ приносит устойчивый результат только тогда, когда вокруг модели создана продуманная обвязка.
В конечном счёте харнесс превращает генератор текста в рабочего исполнителя. Он даёт агенту глаза в виде чтения файлов, руки в виде команд и редакторов, память в виде состояния задачи, а также ограничения, которые не позволяют бездумно менять проект. Поэтому в зрелых системах решает не только модель, но и то, насколько грамотно устроено всё, что находится вокруг неё.
