エージェント・ハーネス・エンジニアリング

コーディングエージェントとは、モデルとその周りに構築されたすべてのものを合わせたものです。ハーネスエンジニアリングは、その足場を生きた成果物として扱い、エージェントがミスをするたびにそれを強化します。

簡単に言えば、エージェントが失敗するたびに、その同じミスを二度と起こさないように恒久的な解決策をエンジニアリングするのです。

過去 2 年間、業界はモデルについて議論してきました。どれが最も賢いか、どれが最もクリーンな React を書くか、どれが最も幻覚を起こさないか。その議論は重要ですが、システムのもう半分を見逃しています。

モデルは、実行中のエージェントへの単なる入力の 1 つです。残りはハーネスです。モデルの周りにラップされたプロンプト、ツール、コンテキストポリシー、フック、サンドボックス、サブエージェント、フィードバックループ、リカバリパスであり、エージェントが実際にタスクを完了できるようにするものです。

優れたハーネスを備えたそこそこのモデルは、悪いハーネスを備えた優れたモデルに一貫して勝ります。ますます、最も興味深いエンジニアリング作業はモデルの選択ではなく、その周りの足場を設計することにあります。

その分野には今や名前があります。@Vtrivedy10 が「ハーネスエンジニアリング」という用語を作り出し、ハーネスが実際に何であるか、そして各ピースがなぜ存在するのかについて明確な内訳を提供しました。@dexhorthy のような他の業界の声は、出現するパターンを追跡し、HumanLayer はエージェントの失敗を設定の「スキル問題」と位置付け、Anthropic のエンジニアリングチームは長時間実行アプリの設計に関するガイドを公開し、Birgitta Böckeler はユーザー側のエクスペリエンスを探求しています。これらはすべて、ほぼ同じアイデアに収束しています。

この投稿は、それらの糸をまとめたものです。

ハーネスとは、実際には何か？

Trivedy の核となる定義が、ほとんどの重労働を担っています。

エージェント = モデル + ハーネス。もしあなたがモデルでなければ、あなたはハーネスです。

ハーネスは、モデル自体ではないすべてのコード、設定、実行ロジックを包含します。生のモデルはエージェントではありません。ハーネスが状態、ツール実行、フィードバックループ、強制可能な制約を提供して初めてエージェントになります。

具体的には、ハーネスには以下が含まれます。

• システムプロンプト、CLAUDE.md、AGENTS.md、スキルファイル、サブエージェントの指示。
• ツール、スキル、MCP サーバー、およびそれらの技術的な説明。
• バンドルされたインフラストラクチャ（ファイルシステム、サンドボックス、ヘッドレスブラウザなど）。
• サブエージェントの生成、ハンドオフの処理、モデルのルーティングのためのオーケストレーションロジック。
• 決定論的な実行のためのフックとミドルウェア（lint チェックやコンテキストの圧縮など）。
• ログ、トレース、コスト、レイテンシ測定のための可観測性ツール。

その核となるのは、エージェントは目標を達成するためにツールをループで実行するシステムです。本当のスキルは、ツールとそのループの両方を設計することにあります。

これは広大な表面積を表していますが、それはモデルプロバイダーのものではなく、あなたの表面積です。Claude Code、Cursor、Codex、Aider、Cline はすべてハーネスです。基盤となるモデルはプラットフォーム間で同一かもしれませんが、あなたが体験する動作はハーネスによって支配されます。

「スキル問題」を再定義しよう

エージェントが無意味なことをしたときに、エンジニアがモデルのせいにし、「次のバージョンまで待つ」問題として片付けてしまうのはよくあることです。

ハーネスエンジニアリングの考え方は、このデフォルトを拒否します。失敗は通常、ある程度理解可能です。エージェントが規約を無視した場合は、AGENTS.md に追加します。破壊的なコマンドを実行した場合は、それをブロックするフックを書きます。40 ステップのタスクで迷子になった場合は、アーキテクチャをプランナーと実行者に分割します。壊れたコードで一貫して終了する場合は、型チェックのバックプレッシャー信号をループに配線します。

HumanLayer が言うように：「それはモデルの問題ではありません。設定の問題です。」パフォーマンスベンチマークを考えてみてください。既製のフレームワーク内で実行されているトップモデルは、カスタムで高度に調整されたハーネス内で実行されているまったく同じモデルよりも、スコアが劇的に低くなることがよくあります。モデルを、より優れたコードベースツール、よりタイトなプロンプト、よりシャープなバックプレッシャーを備えた環境に移すことで、元のセットアップが残した能力を解放できます。

今日のモデルが理論的にできることと、実際に目にする動作との間のギャップは、主にハーネスのギャップです。

ラチェット：すべてのミスがルールになる

ハーネスエンジニアリングにおける最も重要な習慣は、エージェントのミスを永続的なシグナルとして扱うことです。つまり、再試行して忘れるだけの一回限りの偶然ではないということです。

エージェントがコメントアウトされたテストを含む PR を誤ってマージして出荷した場合、それは入力です。AGENTS.md の次のイテレーションでは、「テストをコメントアウトしないでください。削除するか修正してください。」と明記しなければなりません。次の pre-commit フックは、差分内の .skip( を自動的にフラグする必要があります。レビューアーサブエージェントは、コメントアウトされたテストをブロックするように更新されなければなりません。

制約は、実際の失敗を観察した場合にのみ追加し、有能なモデルがそれらを冗長にした場合にのみ削除する必要があります。優れたシステムプロンプトのすべての行は、特定の歴史的な失敗に遡る必要があります。

このため、ハーネスエンジニアリングは、万能のフレームワークではなく、1 つの分野です。特定のコードベースに適したハーネスは、その独自の失敗の歴史によって完全に形成されます。

動作から逆算する

ハーネスを設計する最も効果的な方法は、望ましい動作から始めて、それを提供するコンポーネントを構築することです。望む動作 → それを達成するためのハーネス設計。

ハーネスのすべてのピースには、明確な役割がなければなりません。コンポーネントが存在する目的の特定の動作を名付けることができない場合は、削除する必要があります。

ファイルシステムと Git - 永続的な状態

ファイルシステムは基本です。モデルは、コンテキストウィンドウに収まるものにしか操作できません。ファイルシステムは、データを読み取るためのワークスペース、中間作業をオフロードする場所、複数のエージェントが調整するための表面を提供します。

Git を追加すると、無料のバージョン管理が提供され、エージェントが進捗を追跡し、実験をブランチし、エラーをロールバックできるようになります。

Bash とコード実行：汎用ツール

ほとんどのエージェントは ReAct ループで動作します。推論し、ツール呼び出しで行動し、観察し、繰り返します。考えられるすべてのアクションのためにツールを事前に構築する代わりに、エージェントに bash アクセスを与えることで、エージェントは必要に応じてその場でツールを構築できます。

エージェントは一般的にシェルコマンドに優れており、bash とコード実行は自律的な問題解決のデフォルト戦略となっています。

サンドボックスとデフォルトツール

Bash は、安全に実行される場合にのみ有用です。サンドボックスは、エージェントにコードを実行し、ファイルを検査し、ホストマシンを危険にさらさずに作業を検証するための分離された環境を提供します。

優れたサンドボックスには、強力なデフォルトが付属しています。プリインストールされた言語ランタイム、テスト CLI、ヘッドレスブラウザなどにより、エージェントは自身の作業を観察し、自己検証ループを閉じることができます。

メモリと検索：継続的学習

モデルは、トレーニングの重みと現在のコンテキストを超えた知識を持っていません。ハーネスは、メモリファイル（AGENTS.md など）を使用してこのギャップを埋め、すべてのセッションに知識を注入します。

新しいライブラリバージョンやライブデータなどのリアルタイム情報については、Web 検索と MCP ツールがハーネスに直接組み込まれています。

コンテキストの腐敗との戦い

モデルは、コンテキストウィンドウがいっぱいになると推論が低下します。ハーネスは、3 つの主要な手法を使用してこの希少性を管理します。

• 圧縮：古いコンテキストをインテリジェントに要約してオフロードし、API エラーを防ぎます。
• ツール呼び出しのオフロード：巨大なツール出力（2,000 行のログなど）をファイルシステムに保存し、コンテキストには必須のヘッダーとフッターのみを保持します。
• 段階的開示：タスクが明示的に必要とする場合にのみ、指示とツールを明らかにし、起動時にすべてをロードするのではありません。

長時間の実行

自律的で長時間実行される作業は、早期停止と不十分な問題分解に悩まされます。ハーネスは、構造設計を通じてこれに対抗します。

• ループ：モデルの終了試行をインターセプトし、新しいコンテキストウィンドウで完了目標に向けて継続するように強制します。
• 計画：モデルに目標をステップバイステップの計画ファイルに分解させ、各ステップ後に自己検証フックを介して作業をチェックするように強制します。
• 分割：生成と評価を別々のエージェントに分離し、モデルが自身の作業を評価する際に固有のポジティブバイアスを防ぎます。

フックは執行レイヤー

フックは、アクションを要求することとそれを執行することの間のギャップを埋めます。これらは特定のライフサイクルで実行されます。ツール呼び出しの前、ファイル編集の後、コミットの前などです。フックは破壊的なコマンドをブロックし、トークンを節約するために自動フォーマットを強制し、テストスイートを実行します。

理想的には、成功は静かで、失敗は詳細です。型チェックが合格すれば、エージェントは何も聞きません。失敗すれば、エラーは自己修正のためにループに直接注入されます。

これがルールブックとツールの選択です

リポジトリのルートにあるフラットなマークダウンファイルは、依然として最もレバレッジの効いた設定ポイントです。ただし、スタイルガイドではなく、パイロットのチェックリストのように扱わなければなりません。短く保ち、すべてのルールが過去の失敗を通じて獲得されたものであることを確認してください。

同じ規律がツールにも適用されます。10 の高度に焦点を絞ったツールは、常に 50 の重複するツールよりも優れています。

さらに、ツールの説明はプロンプトを構成するため、悪意のあるまたはずさんな外部統合（未検証の MCP サーバーなど）は、エージェントが作業を開始する前に悪意のあるプロンプトを注入する可能性があります。

これが本番環境でどのように見えるか

私が見た成熟したハーネスの最も明確な公開イメージは、Fareed Khan による（推定の）Claude Code のアーキテクチャの内訳です。

前のセクションのほとんどすべての概念が、この図に名前付きコンポーネントとして現れています。コンテキスト注入は知識レイヤーです。ループ状態はメモリストアとワークツリーアイソレーターに存在します。破壊的アクションフックは許可ゲートの背後にあります。サブエージェントコンテキストファイアウォールは、マルチエージェントレイヤー全体です。ツールディスパッチレジストリは、MCP サーバーと bash の両方が接続する場所です。Claude Code の軌跡は、その下にあるモデルと少なくとも同じくらいハーネスに関するものです。

ハーネスは縮小せず、移動する

モデルが改善されるにつれて、ハーネスの必要性は消えず、変化します。

より良いモデルが足場を時代遅れにすると考えるのは魅力的です。例えば、最近のモデルアップグレードにより、「コンテキスト不安」の緩和の必要性が大幅に減少しました。しかし、床が上がると、天井も上がります。以前は到達できなかったタスクが現在は可能になり、まったく新しい障害モードをもたらします。

ハーネスのすべてのコンポーネントは、モデルが単独ではできないことについての仮定をエンコードしています。モデルが改善された場合、時代遅れの足場は削除され、次の地平に到達するために新しい足場を構築する必要があります。

トレーニングループはどうですか？

ハーネス設計とモデルトレーニングの間には、活発なフィードバックループがあります。

今日のモデルは、特定のハーネスをループに含めてポストトレーニングされることが多く、ある程度の過学習を生み出しています。モデルは、ハーネス設計者が優先した特定のアクション（ファイルシステム操作、bash、サブエージェントディスパッチなど）に非常に優れたものになります。

これにより、ハーネスは静的な設定ファイルではなく、生きたシステムとなり、「最良の」ハーネスは、特定のタスクとワークフローに最適化されたものであることが証明されます。

ハーネス・アズ・ア・サービス（HaaS）

業界は、LLM API（補完を提供する）上に構築することから、ハーネス API（ランタイムを提供する）上に構築することへとシフトしています。SDK は現在、ループ、ツール、コンテキスト管理、フック、サンドボックスをすぐに提供します。

スクラッチからオーケストレーションを構築する代わりに、現代のデフォルトは、ハーネスフレームワークを選択し、そのコアピラーを設定し、純粋にドメイン固有のプロンプトとツールの設計に集中することです。

これがトラブルシューティングをスケーラブルにするものです。エージェントアーキテクチャ全体を再発明するのではなく、適切に設計された設定サーフェスを調整しているのです。

この先の行き先

今日のトップコーディングエージェントを見ると、それらはその下にあるモデルよりも互いに似ています。モデルは異なりますが、ハーネスのパターンは収束しています。業界は、生成テキストを出荷可能なソフトウェアに変えるために必要な、耐荷重性のある足場を急速に特定しています。

最もエキサイティングな未解決の問題は、単一エージェントを超えて進んでいます。複数のエージェントを並行して調整すること、エージェントが自身のトレースを分析してハーネスレベルの障害を修正できるようにすること、ツールをジャストインタイムで動的にアセンブルする環境を構築することです。

最終的に、これはハーネスが静的な設定ファイルではなくなり、コンパイラのように動作し始めるフェーズです。

優れたエージェントハーネスフレームワークを探しているなら、@FredKSchott が Flue を書きました。それは堅牢で、この投稿の以前のバージョンに触発されたようです！