LLM（大規模言語モデル）がチャットウィンドウでコードを書くとき、そのインタラクティブな流れは非常にシンプルで直線的です。ユーザーが Prompt を送信し、モデルがそれを処理して、テキストをストリーミング返答します。
しかし、Claude Code、Codex、Cursor などの AI coding agent が実際のコードリポジトリ上で動作する場合、その仕組みは根本的に異なります。Agent はファイルを検索し、コードを修正し、シェルコマンドを実行し、エラーを検査し、unit test を実行した上で、環境からのリアルタイムなフィードバックに基づいて次のアクションを決定します。
推論（Reasoning）自体は引き続きモデルが担当しますが、その推論がコードベースとどのように相互作用するかを制御する下位システムが存在します。そのシステムこそが Agent Harness です。
混乱しやすいのは、「agent harness」という言葉が単一のソフトウェアツールを指しているわけではない点です。現在の AI エンジニアリングにおいて、この用語は複数の関連するレイヤーを指して使われています：agent を動かす runtime、既存のコーディング助手の周囲に配置されるプロジェクト固有の制御機構、さらには agent の能力を評価するためのインフラなどです。この違いを整理して理解することで、現代の coding agent が実際にどのように機能しているのかが明確になります。
1. LLMは Agent ではない
根本的に、LLMは受け取った Context を出力レスポンスへとマッピングするだけです。標準的なモデルに対して「このリポジトリの認証バグを修正してください」と依頼すれば、考えられる修正案を説明し、コードスニペットを作成することはできます。しかし、リポジトリへのアクセス権、ファイル編集権限、ターミナル、test runner、そして修正が実際に機能したかを検証するフィードバック機構を自動的に備えているわけではありません。
それらの機能は、周囲のシステムによって提供される必要があります。Coding agent とは、推論モデルとそれを包み込む実行システムの組み合わせなのです。
$$\text{Agent} = \text{Model} + \text{Harness}$$
この数式は、モデルの認知的な推論能力と、その推論を信頼性の高いアクションへと変換するために必要な決定論的システム（Deterministic Machinery）を明確に区別しています。
2. ハーネスの本質的な役割とは？
Agent harness の最も決定的な特徴は、個別機能の多さではなく Feedback Loop（フィードバック・ループ） にあります。従来の LLM 対話が入力から出力への単一パスであるのに対し、agent harness は「実行」「観察」「自己修正」の反復サイクルを創出します。
実際のコーディング作業において、このループによって agent は予期せぬ test 失敗、文法エラー、依存関係の不足などに動的に対応できるようになります。モデルは最初のコード生成で完璧な回答を出す必要はありません。Harness が周囲のインフラを提供することで、agent はアクションを起こし、結果を観察し、実際に起きた事象に基づいて次のステップを柔軟に適応させることができます。
これにより、一発で正しい解を生成することをモデルに強制するのではなく、失敗を経由しながら作業を継続することが可能になります。
3. ハーネスが実際に制御している6つの領域
プロダクションレベルの coding harness は、実務における6つのコア機能を調整・制御しています：
- ツールの実行（Tool Execution）: ファイルの読み込み、コードの編集、リポジトリの検索、シェルコマンドの実行、Git操作などのシステム機能を、モデルが呼び出し可能な構造化アクションとして提供します
- コンテキスト管理（Context Management）: ファイルの選定、リポジトリ情報の付与、会話履歴の圧縮（Context Compaction）を行い、複数ターンのセッションを通じてトークン予算を最適に管理します
- 状態の保持（State Preservation）: 長時間にわたるセッション全体で、タスク計画、完了したステップ、アーキテクチャ上の決定、失敗した試行を追跡し、作業の連続性を維持します
- 権限とセキュリティ（Permissions & Security）: 安全な操作は自動的に許可しつつ、破壊的なコマンドや外部ネットワークへのアクセスには人間の明示的な承認を要求するアクセス制御を強制します
- 検証（Verification）: コンパイラ出力、リンターの警告、テストの実行結果をキャプチャし、環境からのエラーをモデルが利用可能なフィードバックへと変換します
- オーケストレーション（Orchestration）: コンテキスト構築、ツール実行、状態更新、検証を単一の実行パイプラインとして接続するメインイベントループを管理します
4. Harness Engineering vs. Prompt & Context Engineering
効果的な agentic workflow を構築するには、モデルを囲む3つの相補的な制御レイヤーを区別することが重要です：
- Prompt Engineering: モデルへの指示やペルソナを制御します（例：「クリーンな TypeScript を書いてください」）
- Context Engineering: モデルに与える情報量を制御します（コードスニペット、リポジトリ context、トークン予算）
- Harness Engineering: 生成された agent が実際に実行できるアクションを制御します（実行ループ、権限ゲート、検証フック）
プロンプトへの詰め込みから決定論的検証へ
Agent が同じ失敗を繰り返す際、prompt により多くの指示を詰め込むアプローチがよく取られます（例：「【重要】終了前に必ず unit test を実行すること」）。しかし、context が肥大化するにつれて、prompt による指示の遵守率は低下しがちです。
Harness engineering では、重要な責任をモデルへの指示文から**システム側の決定論的メカニズム（Deterministic Mechanisms）**へと移行させます：
前者のアプローチはモデルの確率的な遵守に依存しますが、後者のアプローチは決定論的なフィードバックループを構築します。
5. Harness Engineering の「80/20の法則」
Harness を複雑化させ、多数のツールや重厚な状態データベース、複雑なマルチエージェント構成を構築したくなる誘惑は強力です。しかし現実には、基本的な「行動—観察ループ」をカバーする最小限のプリミティブ（基本機能）を用意するだけで、驚くほど高い効果が得られます：
- 必須の基本機能: 検索（Search） $\rightarrow$ 閲覧（Read） $\rightarrow$ 編集（Edit） $\rightarrow$ ターミナル（Terminal） $\rightarrow$ テスト（Test）
- 運用制御: コンテキスト圧縮（Context Compaction） $\rightarrow$ 権限管理（Permissions） $\rightarrow$ 状態追跡（State Tracking） $\rightarrow$ 検証（Verification）
Git や データベースクライアントなどのツールはこれらの応用であり、根幹となるコア構造は非常にシンプルです。過剰に複雑なアーキテクチャは必要ありません。Harness engineering の真のゴールは、フィードバックループを確実かつシンプルに完結させる最小限の仕組み（Minimum Machinery）を構築することです。
6. おわりに
大規模言語モデル（LLM）と AI エージェントの決定的な違いは、システム設計にあります。
LLM はトークンの確率に基づいてテキストを生成します。一方で AI エージェントは、構造化されたツール、状態管理、そして環境からのリアルタイムなフィードバックを通じてコードベース上で自律的に動作します。
モデルは 「agent が何について推論できるか」 を決定し、harness は 「その推論が現実のシステムとどのように相互作用するか」 を決定します。