ハーネスハンドブック：進化するエージェント・ハーネスを読みやすく、ナビゲートしやすく、編集しやすく

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エージェントの能力は、その基盤モデルだけでなく、プロンプトを構築し、状態を管理し、ツールを呼び出し、実行を調整するハーネスにも依存している。モデル、API、環境、要件が変化するにつれて、ハーネスは継続的に修正されなければならない。こうした変更を行う前に、開発者またはコードエージェントは、対象の振る舞いを実装しているすべてのコード箇所を特定する必要がある。しかし、プロダクションハーネスは大規模で密結合されており、振る舞いが分散している上、修正要求はシステムのあるべき動作を記述するのに対し、リポジトリはファイルやモジュールで整理されているため、この作業は困難である。コード検索、リポジトリインデックス作成、長文脈処理は検査を容易にするが、それでも振る舞いからコードへのマッピングは手動で復元する必要がある。したがって、振る舞いの特定はハーネス進化における中心的なボトルネックとなっている。本論文では、ハーネスコードベースから静的解析とLLM支援構造化を介して自動的に合成され、各振る舞いを対応するソースにリンクする、振る舞い中心の表現であるHarness Handbookを提案する。さらに、Behavior-Guided Progressive Disclosure（BGPD）を導入する。これは、エージェントを高レベルの振る舞いから関連する実装の詳細へと導き、候補箇所を現在のソースに対して検証する手法である。2つのオープンソースハーネスに対する多様な修正要求において、Handbook支援による計画は、より少ないプランナートークンで振る舞いの特定と編集計画の品質を向上させ、特に分散した箇所、ほとんど実行されない経路、モジュール間相互作用において最大の効果を示した。複雑なエージェントシステムの進化は、編集の生成だけでなく、その編集をどこに行うべきかを決定することにも依存しているのである。

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.