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

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.

한 줄 요약

현대 AI 에이전트의 허네스 진화를 효율화하기 위해 행동 중심의 자동 생성 가이드인 Harness Handbook과 BGPD 프로세스를 제안한다.

핵심 기여도

**Behavior Localization**을 허네스 수정 전 필수 단계로 정의 (예: 수정 요청에 해당하는 코드 위치 식별).
**Harness Handbook**를 도입: 정적 분석과 LLM을 활용해 행동 중심으로 코드 링크를 자동 생성.
**Behavior-Guided Progressive Disclosure (BGPD)** 프로세스를 제안: 행동 기반으로 코드 탐색을 단계적으로 유도.
두 개 오픈소스 허네스에서 실험: 수정 계획 품질 +10.0~18.9%, 토큰 사용량 -8.6~12.7%.

핵심 아이디어

AI 에이전트의 허네스는 단순히 모델 성능에만 의존하지 않고, 프롬프트 생성, 상태 관리, 도구 호출, 실행 조정 등 다양한 역할을 수행한다. 그러나 허네스는 복잡한 구조로 인해 수정 요청을 코드 위치에 매핑하는 것이 어렵다. 이 문제를 해결하기 위해, **Harness Handbook**는 정적 프로그램 분석과 LLM을 활용해 행동 중심의 코드 링크를 자동 생성한다. 이는 기존의 파일/함수 중심 접근과 달리, **행위 → 코드**의 직접 맵핑을 가능하게 한다. 또한, **BGPD**는 수정 요청을 고수준 행동에서 세부 코드로 단계적으로 이동하며, 수정 대상 위치를 검증한다. 이는 특히 **분산된 구현, 드문 경로, 모듈 간 상호작용**에서 효과적이다.

기술적 접근법

**Harness Handbook**는 정적 분석(static program analysis)과 LLM-assisted behavioral structuring을 통해 생성.
**BGPD**는 행동 기반으로 코드 탐색을 단계적으로 유도하며, 수정 대상 위치를 검증.
실험에 사용된 모델: **DeepSeek-V4-Pro**, 평가 모델: **GPT-5.5**, **Opus 4.8**, **DeepSeek-V4-Pro**.
평가 지표: **plan quality**, **localization accuracy**, **planning cost**.
실험 환경: **Codex**, **Terminus-2** 두 개의 오픈소스 허네스.

주요 결과

**Codex**와 **Terminus-2**에서 **Handbook-Assisted planning**이 **Baseline** 대비 **+10.0~18.9%**의 수정 계획 성공률 향상.
**토큰 사용량**은 **-12.7% (Codex)**, **-8.6% (Terminus-2)** 감소.
**24개의 파일/기호 수준 Recall, Precision, F1** 지표에서 **더 약한 planner**가 **강력한 모델**과 동일 수준의 성능 달성.
**분산된 구현, 드문 경로, 모듈 간 상호작용**에서 가장 큰 성능 향상.

의의 및 한계

**Behavior Localization** 문제를 명확히 정의하고, 행동 중심의 허네스 진화를 가능하게 하는 **Harness Handbook**를 제시함으로써, 복잡한 허네스 시스템의 수정 효율성을 높임.
**BGPD**는 수정 요청을 행동 단계에서 코드 단계로 이동하는 데 효과적인 프로세스를 제공.
한계로는 **Handbook 생성 시 정적 분석과 LLM의 오류 가능성**, **동적 환경에서의 실시간 업데이트 필요성**이 언급됨. 또한, **복잡한 행동 구조를 정확히 추출하는 한계**도 존재.

실용적 활용

**AI 에이전트 개발자**가 허네스를 효율적으로 수정할 수 있도록 지원.
**코드 검토, 회귀 영향 분석, 행동 감사** 등 다양한 개발 및 유지보수 작업에 활용 가능.
향후 **자체 진화하는 허네스 시스템** 구축에 기반 자료로 활용될 수 있음.