Harness Handbook: способ быстрее находить нужный код при правке ИИ-агентов
Возможности современного ИИ-агента зависят не только от базовой модели, но и от harness, обвязки, которая формирует промпты, управляет состоянием, вызывает инструменты и координирует выполнение. По мере развития моделей, API, окружений и требований harness приходится постоянно дорабатывать. Но прежде чем внести изменение, разработчик или сам кодирующий агент должен найти все места в коде, реализующие нужное поведение. Это сложно: продакшен-harness'ы большие, части кода тесно связаны между собой и поведение распределено по многим модулям, а запрос на изменение описывает желаемое поведение системы, тогда как репозиторий организован по файлам и модулям, соответствия между ними нет. Поиск по коду, индексация репозитория и обработка длинного контекста облегчают изучение кода, но задачу сопоставления «поведение → код» разработчику всё равно приходится решать вручную. Авторы называют такую локализацию поведения главным узким местом при развитии harness-систем.
В работе представлены два элемента решения. Первый, сам Harness Handbook: представление кодовой базы, ориентированное на поведение, а не на файлы. Оно строится автоматически из исходников harness с помощью статического анализа и структурирования при участии LLM, и каждое описанное поведение в нём связано с конкретным местом в исходном коде. Второй, метод Behavior-Guided Progressive Disclosure (BGPD, «пошаговое раскрытие деталей, направляемое поведением»): он ведёт агента от общего описания нужного поведения к релевантным деталям реализации и проверяет предложенные места правки на соответствие актуальному коду.
Подход проверили на разнообразных запросах модификации для двух реальных open-source harness-систем. Планирование правок с помощью Handbook показало более точную локализацию поведения и более качественные планы правок, при этом планировщику потребовалось меньше токенов. Наибольший выигрыш получили как раз в сложных случаях: когда нужный код разбросан по разным местам, когда затронутые пути выполняются редко и когда правка затрагивает взаимодействие между несколькими модулями. Вывод авторов: развитие сложных агентных систем упирается не только в умение генерировать сами правки, но и в умение определить, куда именно их вносить.
Ключевые факты
- Harness, это обвязка вокруг модели (промпты, состояние, инструменты, выполнение), и её тоже приходится постоянно дорабатывать по мере роста системы
- Главная сложность, «локализация поведения»: найти в большом связанном коде все места, где реализовано нужное поведение, прежде чем вносить правку
- Harness Handbook, представление кодовой базы, ориентированное на поведение; строится автоматически статическим анализом и LLM поверх существующего кода harness
- BGPD (Behavior-Guided Progressive Disclosure) ведёт агента от общего описания поведения к деталям реализации и сверяет кандидатов с актуальным кодом
- На запросах модификации для двух open-source harness подход дал точнее локализацию и планы правок при меньшем расходе токенов планировщика, особенно на разбросанном по коду и редко исполняемом функционале
Почему это важно
С ростом моделей, инструментов и интеграций harness-код агентных систем усложняется и становится тесно связанным, а поведение, распределённым по множеству модулей. При этом запрос на изменение всегда формулируется в терминах поведения («сделай так, чтобы агент делал X»), а код организован по файлам, прямого соответствия между ними нет. Найти все места, которые нужно поправить, вручную, трудоёмко и легко упустить часть логики. Авторы называют это узким местом, которое тормозит развитие сложных агентных систем, причём как для людей-разработчиков, так и для самих coding-агентов, которые пытаются править собственный или чужой harness.
Кому это важно
В первую очередь, разработчикам и командам, которые поддерживают open-source или внутренние harness-фреймворки для ИИ-агентов и вынуждены часто вносить в них точечные изменения. Также это релевантно тем, кто использует coding-агентов для автоматизации доработки таких систем: качество локализации кода напрямую влияет на то, насколько агент правильно и полно вносит правку.
Как это применить
Harness Handbook строится автоматически поверх существующей кодовой базы harness, с помощью статического анализа и структурирования при участии LLM, без ручной разметки. Дальше правки планируются не «в лоб» по файлам, а через BGPD: сначала агент получает общее описание релевантного поведения, затем постепенно раскрываются детали реализации, а предложенные места правки сверяются с актуальным состоянием кода перед тем, как приступать к изменению.
Можно ли доверять
Это исследовательская работа (препринт на arXiv), а не готовый коммерческий продукт. Метод проверяли на разнообразных реальных запросах модификации для двух open-source harness-систем и сравнивали с обычным планированием без Handbook, по точности локализации поведения, качеству планов правок и расходу токенов планировщика. Задача узкая и инженерная, но методологически описана предметно: авторы явно указывают, на каких типах случаев (разбросанный код, редкие пути, межмодульные взаимодействия) выигрыш оказался наибольшим, а не просто заявляют общее улучшение.
Риски и подводные камни
Оценка проведена всего на двух harness-системах, обобщаемость подхода на другие архитектуры и языки кода пока не доказана. Handbook нужно поддерживать в актуальном состоянии по мере изменения кода harness, иначе связки «поведение → код» устареют и начнут вводить агента в заблуждение. Наконец, это исследовательский прототип: готовой интеграции в популярные agent-фреймворки или инструментов для практического использования в статье не описано.