하네스 핸드북: 진화하는 에이전트 하네스의 가독성, 탐색성, 편집성 확보

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

July 14, 2026

저자: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

cs.AI

초록

현대 AI 에이전트의 능력은 기반 모델뿐만 아니라 프롬프트를 구성하고, 상태를 관리하며, 도구를 호출하고, 실행을 조정하는 하네스(harness)에도 의존합니다. 모델, API, 환경 및 요구사항이 진화함에 따라 하네스는 지속적으로 수정되어야 합니다. 이러한 변경을 수행하기 전에 개발자나 코딩 에이전트는 대상 동작을 구현하는 모든 코드 위치를 식별해야 합니다. 이는 프로덕션 하네스가 크고, 강하게 결합되어 있으며, 동작이 분산되어 있는 반면, 수정 요청은 시스템이 수행해야 할 작업을 설명하고 저장소는 파일과 모듈별로 구성되어 있기 때문에 어렵습니다. 코드 검색, 저장소 인덱싱 및 장문맥 처리는 검사를 용이하게 하지만, 여전히 이러한 동작-코드 매핑을 수동으로 복구해야 합니다. 따라서 동작 위치 파악(behavior localization)은 하네스 진화의 핵심 병목 현상입니다. 우리는 하네스 핸드북(Harness Handbook)을 소개합니다. 이는 정적 분석과 LLM 지원 구조화를 통해 하네스 코드베이스로부터 자동으로 합성된 동작 중심 표현으로, 각 동작을 해당 소스에 연결합니다. 또한 행동 유도 점진적 공개(Behavior-Guided Progressive Disclosure, BGPD)를 소개합니다. 이는 에이전트를 높은 수준의 동작에서 관련 구현 세부 사항으로 안내하고 후보 위치를 현재 소스와 대조하여 검증합니다. 두 개의 오픈소스 하네스에서 얻은 다양한 수정 요청에 대해, 핸드북 지원 계획(Handbook-Assisted planning)은 더 적은 플래너 토큰을 사용하면서 동작 위치 파악 및 편집 계획 품질을 향상시키며, 분산된 사이트, 거의 실행되지 않는 경로 및 모듈 간 상호작용에서 가장 큰 이점을 보입니다. 따라서 복잡한 에이전트 시스템을 진화시키는 것은 편집을 생성하는 것뿐만 아니라 해당 편집이 어디에서 이루어져야 하는지를 결정하는 데 달려 있습니다.

English

The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution. As models, APIs, environments, and requirements evolve, the harness must be continually modified. Before such a change can be made, a developer or coding agent must identify all code locations that implement the target behavior. This is difficult because production harnesses are large, tightly coupled, and behaviorally distributed, while modification requests describe what the system should do and repositories are organized by files and modules. Code search, repository indexing, and long-context processing ease inspection, but still leave this behavior-to-code mapping to be recovered by hand. Behavior localization is therefore a central bottleneck in harness evolution. We introduce the Harness Handbook, a behavior-centric representation synthesized automatically from a harness codebase via static analysis and LLM-assisted structuring, linking each behavior to its corresponding source. We also introduce Behavior-Guided Progressive Disclosure (BGPD), which guides agents from high-level behaviors to relevant implementation details and verifies candidate locations against the current source. On diverse modification requests from two open-source harnesses, Handbook-Assisted planning improves behavior localization and edit-plan quality while using fewer planner tokens, with the largest gains on scattered sites, rarely executed paths, and cross-module interactions. Evolving complex agentic systems thus depends not only on generating edits, but also on determining where those edits should be made.