Карта поведения помогает быстрее менять ИИ-агентов

Когда проблема не в модели, а в «обвязке»

В разговорах об ИИ-агентах почти все внимание уходит моделям. Какая LLM сильнее, у кого лучше рассуждение, кто точнее пишет код. Но в реальной инженерной жизни успех агента часто упирается не только в саму модель. Есть еще слой, который собирает подсказки, хранит состояние, вызывает инструменты, следит за порядком шагов. Авторы статьи называют его обвязкой агента.

И вот именно этот слой становится больным местом, когда систему нужно менять.

Добавить новую возможность. Подправить поведение. Перенести логику на другой API. Исправить редкую ветку выполнения. Все это звучит как обычная доработка. Но на деле разработчику или агенту для программирования сначала нужно понять, где вообще в коде живет нужное поведение. А это часто не один файл и не одна функция. Логика размазана по этапам выполнения, общему состоянию, служебным модулям и обходным путям.

Новая работа Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable предлагает смотреть на код не как на набор файлов, а как на набор поведений. И показывает, что это не просто красивый способ документирования, а вполне практичный инструмент, который помогает агентам лучше планировать правки, реже промахиваться по местам изменений и тратить меньше токенов.

В чем здесь настоящая проблема

Если коротко, статья формулирует очень земную мысль: самая трудная часть изменения сложной системы — не написать новый код, а найти все места, которые надо поменять.

Авторы дают этому отдельное имя: локализация поведения. Это поиск всех участков кода, которые вместе реализуют поведение, описанное в запросе на изменение.

Почему это сложно:

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

Именно этот разрыв статья пытается закрыть.

Что такое Harness Handbook

Идея Harness Handbook проста и сильна: сделать для обвязки агента поведенческое представление, которое связывает описание поведения с конкретным кодом.

Вместо структуры «папка → файл → функция» получается структура «этап работы системы → компоненты этого этапа → конкретные участки кода». То есть навигация идет не от файловой системы, а от того, что делает система во время работы.

Трехуровневое представление Harness Handbook: от общей картины системы к этапам и затем к конкретным участкам кода.

У Handbook три уровня:

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

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

Как этот справочник строится

Самое интересное, что Handbook не пишется вручную. Его строят автоматически из репозитория в три шага.

Конвейер построения Harness Handbook: статический анализ, организация по поведению и сборка трехуровневого справочника.

Сначала идет статический анализ. Из кода извлекают функции, сигнатуры, вызовы, границы с внешними зависимостями, связи между частями программы. Это делается детерминированно, без помощи модели.

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

Наконец, поверх этого собирается сам Handbook: уровни L1–L3, ссылки на код и карта состояния.

Есть важная страховка: Handbook не должен «галлюцинировать» структуру. Если ссылка на участок кода больше не подтверждается текущим репозиторием, такой элемент замораживается и не участвует в дальнейшей локализации. Иными словами, источник истины — всегда сам код, а не текстовое описание.

Это очень разумный инженерный компромисс. Авторы не пытаются заменить репозиторий умной сводкой. Они делают навигатор, который помогает быстрее добраться до нужных мест.

Как это помогает агенту для программирования

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

Сценарий выглядит так:

Это важно. Handbook не редактирует код и не подменяет его. Он сужает пространство поиска и помогает не пропустить разбросанные точки изменения.

А после правок справочник можно автоматически синхронизировать с новым состоянием репозитория. То есть система не просто помогает один раз, а остается живой картой проекта.

Как проверяли идею

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

Одна — компактная Python-система с шестью исходными файлами. Другая — большой Rust-монорепозиторий Codex с тысячами файлов и глубокими графами вызовов.

Для каждой системы собрали по 30 запросов на изменение поведения. Запросы делились на три типа:

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

Что получилось на практике

Главный результат: доступ к Handbook улучшал качество планов и одновременно снижал расход токенов.

С Handbook планы побеждают чаще и требуют меньше токенов у планировщика на обеих системах.

На Codex доля побед по качеству плана выросла с 28,3% до 38,3%. На Terminus-2 — с 26,7% до 45,6%. Причем это не оценка одного-единственного судьи: вывод устойчиво повторился у трех разных моделей-оценщиков.

По токенам картина тоже приятная. Средний расход на один запрос снизился:

Это важный момент. Часто улучшение качества покупают просто более длинным контекстом. Здесь наоборот: лучше нашли нужные места и при этом меньше читали лишнего.

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

Особенно впечатляет снижение полных промахов. Метрика Wrong — это доля случаев, где план вообще не пересекся с эталоном. С Handbook она падала местами больше чем на 20 процентных пунктов. То есть справочник помогал не только чуть-чуть улучшить хорошие планы, но и спасал от грубых провалов.

Где выигрыш особенно заметен

Наибольший выигрыш наблюдается в сложных типах запросов: межфайловых и «поисково-враждебных» задачах.

Самые заметные улучшения пришлись не на простые случаи, а на те, где обычный поиск по коду особенно слаб:

Это хорошо согласуется с основной идеей статьи. Если изменение можно найти простым поиском по имени функции, Handbook не дает магии. Но если поведение живет «между» файлами, этапами и состояниями, тогда поведенческая карта оказывается очень полезной.

Почему это важно шире, чем кажется

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

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

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

Отсюда вытекает несколько последствий:

Особенно интересна идея автоматической пересборки Handbook после каждого диффа. Это уже похоже на зачаток системы, где агент не просто пишет патчи, а поддерживает актуальную модель мира о собственном коде.

Что в итоге

Работа Harness Handbook предлагает очень практичный сдвиг оптики: смотреть на репозиторий не как на набор файлов, а как на карту поведения системы.

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

Главный вывод здесь простой: эволюция сложных ИИ-систем упирается не только в умение сгенерировать изменение, но и в умение понять, где именно это изменение должно произойти. И в этой задаче поведенческий справочник может оказаться не менее важным, чем очередной скачок качества самой LLM.