現代のAIエージェントの能力は、基盤モデル単体の性能だけで決まるわけではありません。プロンプトの構築、状態の管理、そしてツールの呼び出しなどを統制する「ハーネス（Harness）」と呼ばれる実行基盤が重要な役割を担っています。

エージェントを継続的に進化させるためには、このハーネスの改修が欠かせません。しかしながら、ここで最大のボトルネックとなるのが「振る舞いのローカリゼーション（変更すべきコード箇所の特定）」です。

既存のコード検索やリポジトリマップはファイルや関数単位で構成されているため、「このような振る舞いに変更してほしい」という指示を受けたAIエージェント自身が、様々なファイルに分散したコードの繋がりを自力で推論しなければならないという限界がありました。

この記事では、コードベースをシステム本来の「振る舞い」を中心に整理し直し、これらの課題を解決に導く新しい表現手法「Harness Handbook」のアーキテクチャと、開発現場にもたらす影響について解説します。

1. Harness Handbookの中心概念と2つの原則

AIエージェントのコードが複雑に絡み合う中、開発者やAI自身が「どこに手を入れるべきか」を迷わず見つけ出せるように構築されたのが、Harness Handbook です。このハンドブックは、従来のファイル構造ではなく、システムの「振る舞い」をベースにコードベースを再構成します。

その中心となる概念は、大きく2つの要素で表現されます。

• 3階層のドキュメントツリー \(\mathcal{D}\): システム全体を、解像度の異なる3つの階層で整理します。
  • L1（システム概要）: アーキテクチャ全体や主要なステージ、大きなデータの流れを俯瞰する層です。
  • L2（コンポーネント概要）: 選択した実行ステージの役割、入出力、依存関係などをまとめた層です。
  • L3（ユニットの深掘り）: 実際のソースコードと直接紐づく層であり、具体的な実装の詳細を指し示します。
• 状態レジスタビュー \(\mathcal{Z}\): AIエージェントの振る舞いは、単一の関数で完結せず、様々なステージをまたいでデータが受け渡されることがよくあります。このビューは、そうしたステージ間の状態変化や共有データの関係性を記録し、分散したコードの繋がりを追跡しやすくします。

さらに、このハンドブックが常に開発の現場で役立ち続けるよう、以下の2つの原則が徹底されています。

1. 段階的開示（Progressive disclosure）
   最初からすべてのソースコードを読み込ませるのではなく、タスクが詳細を必要とするまではL1やL2の概要にとどめ、必要に応じてL3を開示します。これにより、AIエージェントが処理すべき情報量を最適化し、効率的なコード探索を支援します。
2. 振る舞いと実装の整合性（Behavior-implementation alignment）
   ハンドブックの情報は、常に実際のソースコード（リポジトリ）を「正」として扱います。ハンドブックが示すコードの場所（L3ロケーター）は、現在のリポジトリの内容と一致していなければならず、もし検証できない場合はその情報を一旦凍結します。これにより、ハンドブックが嘘をつくことを防ぎ、常に信頼できる状態を保ちます。

以上のように、Harness Handbookはシステムの全体像と詳細なコードの架け橋となり、開発をスムーズに進めるための強力な羅針盤として機能します。

2. ハンドブックの自動構築プロセス

Harness Handbookは、既存のコードベースから自動的に構築されます。この構築プロセスは、AI（LLM）の推論と確実なプログラム解析を組み合わせた3つのフェーズで構成されています。

• フェーズI: 静的解析による事実の抽出
  最初のステップでは、LLMを一切使わず、決定論的な静的解析（Static analysis）を実施します。このステップにより、関数、関数のシグネチャ、呼び出しグラフ \(\mathcal{G}\)（Program graph）といった、ソースコードに根ざした揺るぎない事実情報だけを抽出します。これにより、以降の工程はすべて事実に基づいた土台の上で進められます。
  • リーフモードの決定
    抽出した情報をもとに、ハンドブックの最下層であるL3の粒度を決定します。システムの実行ステージを定義した信頼できるシード骨格（Seed skeleton）が存在し、計算リソースの予算に見合う場合は「関数ベース（function-as-leaf）」を採用します。一方で、そうした骨格がない場合や、リポジトリが巨大な場合は、ファイル単位で整理する「ファイルベース（file-as-leaf）」を選択し、システム自身に構造を推論させます。
• フェーズII: 振る舞いに基づくコードの割り当てと分割
  関数ベースのモードを選択した場合、抽出した関数を適切な実行ステージへと割り当てます。もし1つの関数が複数の異なる機能（役割）を担っている場合は、コードを連続した「領域」に細かく分割します。そして、それぞれの領域を別々のステージにマッピングすることで、コードと振る舞いを正確に結びつけます。
• フェーズIII: 検証とハルシネーション対策
  構築の最終段階では、各情報を統合してL1からL3までのドキュメントツリーを合成します。ここで重要になるのが、LLMによる情報の捏造を防ぐ仕組みです。生成されたL3のロケータ（コードの場所情報）は、必ずパッケージ化される前に実際のソースコードと照合されます。もしコードの変更などによって検証を通過できないエントリがあれば、その情報は「凍結」され、コードの場所が確認できるまで探索の対象から外されます。

このように、確固たる事実に基づく解析とLLMの柔軟な解釈を組み合わせ、さらに厳格な検証プロセスを挟むことで、Harness Handbookは嘘をつかない信頼できるシステムの羅針盤として完成します。

3. BGPDによるコード特定と変更計画

Harness Handbookを活用して実際にシステムを改修するプロセスは、大きく「特定」「計画」「実行」「再同期」という4つのステップで進められます。ここでは、AIエージェントがどのように変更すべきコードを見つけ出し、編集を計画するのかを解説します。

このプロセスの中核を担うのが、BGPD（Behavior-Guided Progressive Disclosure：振る舞い主導の段階的開示）と呼ばれる探索ワークフローです。エージェントは、いきなり膨大なソースコードを読み込むのではなく、以下の手順で効率的に変更箇所を絞り込みます。

1. 段階的な探索による特定
   エージェントはまず、L1（システム概要）やL2（コンポーネント概要）といった上位の階層から探索を始めます。関連する実行ステージや状態レジスタを特定したうえで、詳細な情報が必要になるまでL3（ソースコード本文）を隠蔽します。これにより、エージェントが消費するトークンの無駄を防ぎ、様々な情報によるコンテキスト過多を効果的に回避できます。
2. 現在のリポジトリとの照合検証
   ハンドブック上で変更候補となるコード箇所を特定した後、エージェントは現在の実際のソースコード（リポジトリ）を開いて内容を検証します。ここで現在のコードとの関連性が正しく確認されたものだけが、検証済みのエビデンス \(\widehat{\mathcal{E}}_q\) として抽出されます。
3. 変更計画とアクション宣言の生成
   抽出したエビデンス \(\widehat{\mathcal{E}}_q\) をもとに、エージェントは具体的な編集計画を作成します。このとき、具体的なコードの差分を作成するだけでなく、「Modify（修正）」「Add（追加）」「Remove（削除）」といったアクション宣言 \(\Gamma\) をあわせて生成します。この \(\Gamma\) は、ソースコードを直接書き換えるため（差分生成用）ではなく、後の実行フェーズで「計画通りに正しく編集が適用されたか」を検証する用途として利用されます。
4. 実行と再同期
   作成された計画に基づき、別のエージェント（実行役）がリポジトリを実際に更新します。その後、変更内容に合わせてハンドブック自身が最新状態へと更新されます（再同期の詳細については次章で解説します）。

このように、BGPDはエージェントを「システムの全体的な振る舞い」から「具体的な実装箇所」へと迷わず誘導し、事実に基づいた安全で確実な変更計画の立案をサポートします。

4. リポジトリ変更に伴う自動再同期と保守

開発者やAIエージェントがコードを書き換え、システムが進化していく過程において、Harness Handbook自身も常に最新のコードベースと同期し続ける必要があります。しかし、変更のたびに巨大なハンドブック全体をゼロから作り直すのは非常に非効率です。

そこで、ハンドブックは以下の仕組みを用いて、無駄なく安全に最新状態を維持します。

• 影響範囲に絞った効率的な更新（Scoped update）
  リポジトリに実際の変更（差分 \(\Delta \neq \emptyset\)）が加わった際、既存のステージ定義（システムの骨組み）が有効な範囲内であれば、影響を受けた部分だけにスコープを絞って更新を実施します。これにより、計算コストを抑えつつ素早く再同期を完了させます。
• 行番号に依存しない正確な追跡
  ソースコードが少しでも編集されると行番号はずれてしまいますが、ハンドブックは行番号に依存しない関数の「フィンガープリント」を用いたマッチングを採用しています。そのため、単なる関数の場所移動やリネームであっても、AIは「別の新しい関数が作られた」と誤認することなく、正確に変更を検知してバージョン間の同期をとります。
• 推測を排除する保守的対応（Conservative handling）
  新しく追加されたコードの解析に失敗したり、適切なステージへの分類ができなかったりするケースも想定されます。このような場合、LLMに無理にコードの役割を推測させることは決してしません。代わりに、分類不能なコードとしてカバレッジ記録 \(\mathcal{Y}\) に残すか、関連するエントリの情報を一旦「凍結」するという保守的な対応を取り、ハンドブックに嘘（ハルシネーション）が混入することを防ぎます。

こうした仕組みにより、様々な改修が連続する開発現場においても、Harness Handbookは常に実態と乖離しない「生きた設計図」として機能し続けます。

5. 評価実験

Harness Handbookの実用性を検証するため、規模や言語が全く異なる2つのオープンソースプロジェクトを用いて評価実験が実施されました。

プロジェクト名	特徴と規模	採用モード
Terminus-2	Python製。6ファイル、内部関数103個の小規模な構成。	関数ベース
Codex	Rust製。2,267ファイル、内部関数34,363個の大規模リポジトリ。	ファイルベース

実験では、変更箇所の特定（Localization）を最重要視し、以下の計算式で計画の品質スコアを算出しています。

$$S = 0.5 S_{\text{Loc}} + 0.25 S_{\text{Scope}} + 0.25 S_{\text{Reason}}$$

結果として、Handbookを利用したエージェントは、「特定の正確さ（Loc）」「影響範囲の制御（Scope）」「推論の妥当性（Reason）」というすべての評価軸において、Handbookなしのベースライン手法を上回る勝率を記録しています。

具体的には、以下の3つの顕著な成果が確認されています。

• トークン消費を抑えつつ品質を向上
  BGPDによる段階的なナビゲーションが適切に機能した結果、無駄なコード探索が減少し、より高い計画品質を達成しながらエージェントの消費トークン数を8.6%（Terminus-2）〜12.7%（Codex）削減することに成功しました。
• 「検索困難」なタスクでの強さ
  単純なキーワード検索では見つけにくい、フォールバックやコールドパス、あるいはミラーリング実装などにコードが隠れている「Search-Hostile（検索困難）」なタスクにおいても、大きな成績向上が見られました。この改善傾向は、様々な難易度（Easy / Medium / Hard）のタスクを通じて一貫して確認されています。
• より小さなモデルの能力底上げ
  Handbookの誘導により、相対的に小規模なモデルであっても、Opus 4.8やGPT-5.5といった強力なモデルが作成した正解データに匹敵する精度（Recall、Precision、F1スコアの向上）を達成しました。さらに、全く無関係な箇所を修正しようとする「完全な見当違い（Wrong）」を示す割合が最大25.9ポイントも低下しており、的確で安全なコード改修をサポートできることが示されています。

おわりに

生産環境で稼働する大規模なエージェントハーネスを進化させる上で、システムの「振る舞い」をベースに変更すべきコードを特定できるインフラはもはや必要不可欠です。

Harness Handbookは、これまで見えにくかった「振る舞い」と「実装」のギャップを構造的なデータとして繋ぎ合わせます。これにより、一度に処理できる情報量（コンテキスト）に制限があるコーディングエージェントでも無駄なコード探索を回避でき、改修計画の精度と効率を同時に引き上げることが可能になります。

さらに、コードの変更に追従して自律的に再同期されるこの仕組みは、単なる開発補助ツールにとどまりません。長期的には、AIエージェント自身が自らのハーネスを継続的に自己進化（Self-evolving）させていくための、重要な自律型ループの基盤として期待されます。

More Information

• arXiv:2607.13285, Ruhan Wang et al., 「Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable」, https://arxiv.org/abs/2607.13285