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

この記事は元々Addy Osmaniのブログに掲載され、許可を得て転載されています。

要点：エージェントがミスを犯すたびに、そのミスが二度と起こらないように解決策を設計する。

ここ2年、私たちはモデルについて議論してきました。どれが最も賢いか、最もきれいなReactコードを書くか、幻覚が少ないか。その議論はそれなりに意味がありますが、システムの半分を見落としています。モデルは実行中のエージェントへの1つの入力に過ぎません。残りはハーネス、つまりプロンプト、ツール、コンテキストポリシー、フック、サンドボックス、サブエージェント、フィードバックループ、リカバリパスなど、モデルが実際に何かを完了できるようにするためのラッパーです。

優れたモデルと貧弱なハーネスよりも、平凡なモデルと優れたハーネスの方が効果的です。私は自分の仕事でこれを何度も目の当たりにしてきました。そして、興味深いエンジニアリングはモデル選びではなく、その周りの足場を設計することにあります。

この分野には今や名前がついています。Viv Trivedyが「ハーネスエンジニアリング」という用語を作り、彼の「エージェントハーネスの解剖」という記事は、ハーネスとは何か、各要素がなぜ存在するのかを最も明確に説明しています。Dex Horthyはこのパターンを追跡しています。HumanLayerは、エージェントの失敗のほとんどを「スキル問題」、つまりモデルの重みではなく設定の問題と位置づけています。Anthropicのエンジニアリングチームは、長期実行タスク向けにハーネスを設計する方法について、私が考える最高の公開分析を発表しました。Birgitta Böckelerはユーザー側から見たこの様子の良い概要を提供しています。

この記事は、これらの糸をまとめようとする試みです。

ハーネスとは何か？

Vivの一言でほとんど説明できます：エージェント = モデル + ハーネス。モデルでなければ、あなたはハーネスです。

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

具体的には、ハーネスには以下が含まれます：システムプロンプト、CLAUDE.md、AGENTS.md、スキルファイル、サブエージェントプロンプト；ツール、スキル、MCPサーバー、およびその説明；バンドルされたインフラ（ファイルシステム、サンドボックス、ブラウザ）；オーケストレーションロジック（サブエージェント生成、ハンドオフ、モデルルーティング）；決定論的実行のためのフックとミドルウェア（圧縮、継続、リントチェック）；可観測性（ログ、トレース、コストとレイテンシの計測）。

Simon Willisonはループ部分を本質に還元しています：エージェントとは「目標を達成するためにツールをループで実行するシステム」です。技術はツールとループの両方の設計にあります。

これが多くの表面積に聞こえるなら、その通りです。そしてそれはあなたの表面積であり、モデルプロバイダーのものではありません。Claude Code、Cursor、Codex、Aider、Cline — これらはすべてハーネスです。下にあるモデルは時々同じですが、あなたが体験する動作はハーネスが何をするかによって支配されます。

コーディングエージェント = AIモデル + ハーネス。Vivによって明確にされ、HumanLayerによっても反響されたこの方程式こそ、実際の作業が存在する場所です。左辺に関する議論は賑やかですが、実際のレバレッジのほとんどは右辺にあります。

「スキル問題」の再構成

私が観察するエンジニアのパターンがあります。エージェントが愚かなことをすると、エンジニアはモデルを非難し、その非難は「次のバージョンを待つ」というファイルに分類されます。

ハーネスエンジニアリングの考え方はそのデフォルトを拒否します。失敗は通常、理解可能です。エージェントが規約を知らなかったので、AGENTS.mdに追加します。エージェントが破壊的なコマンドを実行したので、それをブロックするフックを追加します。エージェントが40ステップのタスクで迷子になったので、プランナーと実行者に分割します。エージェントが壊れたコードを「完成」し続けたので、型チェックのバックプレッシャー信号をループに配線します。

HumanLayerは言います：「それはモデルの問題ではなく、設定の問題です。」ハーネスエンジニアリングとは、そのことを真剣に受け止めたときに起こることです。

Vivの記事とHumanLayerの両方に現れる印象的なデータポイントがあります。Terminal Bench 2.0では、Claude Code内で動作するClaude Opus 4.6は、カスタムハーネスで動作する同じモデルよりもはるかに低いスコアを記録しました。Vivのチームはハーネスのみを変更することで、コーディングエージェントをトップ30からトップ5に押し上げました。モデルはトレーニングされたハーネスに結合された後訓練を受けます。より良いツール、よりタイトなプロンプト、より鋭いバックプレッシャーを備えた別のハーネスに移すことで、元のハーネスが未活用にしていた能力を解放できます。

これは「GPT-6を待て」というナラティブの反対です。今日のモデルができることと、あなたが見ている実際の能力とのギャップは、主にハーネスのギャップです。

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

ハーネスエンジニアリングで最も重要な習慣は、エージェントの失敗を永続的な信号として扱うことです。笑い話にするための一回限りの話ではなく、「悪い実行」として再試行するものでもありません。信号です。

エージェントがコメントアウトされたテストを含むPRを出し、私がうっかりマージした場合、それは入力です。次のバージョンのAGENTS.mdには「テストをコメントアウトしないでください。削除するか修正してください」と書かれています。次のバージョンのプリコミットフックは、差分内の「.skip(」と「xit(」をgrepします。次のバージョンのレビューサブエージェントは、コメントアウトされたテストをブロッカーとしてフラグ付けします。

実際の失敗を見たときにのみ制約を追加します。有能なモデルが制約を冗長にしたときにのみ削除します。優れたAGENTS.mdのすべての行は、具体的にうまくいかなかった何かに遡れるべきです。

これが、ハーネスエンジニアリングがフレームワークではなく、学問である理由でもあります。あなたのコードベースに適したハーネスは、あなたの失敗の歴史によって形作られます。ダウンロードすることはできません。

望ましい動作から逆算する

実際にハーネスを設計する際にVivの枠組みで最も役立つのは、望ましい動作から始めて、それを実現するハーネスの部分を導き出すことです。彼のパターン：望ましい（または修正したい）動作 → モデルがそれを達成するのに役立つハーネス設計。

このように導き出すことの有用な点は、すべてのハーネスコンポーネントに特定の役割があることです。あるコンポーネントが存在する目的となる動作を名付けることができなければ、おそらくそこにあるべきではありません。

このセクションの残りでは、Vivの順序にほぼ従い、私が盗む価値があると見つけた具体的なパターンを挙げながら各要素を説明します。

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

ファイルシステムは最も基本的なプリミティブであり、退屈だからといって過小評価されがちです。モデルはコンテキストに収まるものにしか直接操作できません。ファイルシステムがなければ、チャットウィンドウにコピーペーストするだけであり、ワークフローとは言えません。

ファイルシステムがあれば、エージェントはデータ、コード、ドキュメントを読み取るワークスペースを手に入れます；中間作業をコンテキストに保持する代わりにオフロードする場所；そして複数のエージェントと人間が共有ファイルを通じて調整できる表面。その上にGitを追加すれば、バージョン管理が無料で手に入り、エージェントは進捗を追跡し、エラーをロールバックし、実験をブランチできます。

他のハーネスプリミティブのほとんどは、何らかの形でファイルシステムを指しています。

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

現在の主要なエージェントループはReActループです：モデルが推論し、ツール呼び出しを介してアクションを起こし、結果を観察し、繰り返します。しかしハーネスは、ロジックを持つツールのみを実行できます。すべての可能なアクションに対してツールを事前に構築することもできますし、エージェントにBashを与えて、その場で必要なツールを自分で構築させることもできます。

Willisonの見解は、エージェントはすでにシェルコマンドに優れており、ほとんどのタスクは適切に選ばれたCLI呼び出しに集約されるというものです。ハーネスは依然として焦点を絞ったツールを提供しますが、Bashとコード実行は自律的な問題解決のデフォルトの汎用戦略となっています。これは、誰かに1つのキッチンガジェットの使い方を教えるのと、台所を与えるのとの違いです。

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

Bashは安全な場所で実行される場合にのみ有用です。エージェント生成コードをラップトップで実行するのは危険であり、単一のローカル環境は多数の並行エージェントに対応できません。

サンドボックスはエージェントに隔離された動作環境を提供します。ハーネスはローカルで実行する代わりにサンドボックスに接続してコードを実行し、ファイルを検査し、依存関係をインストールし、作業を検証します。コマンドを許可リストに追加したり、ネットワーク分離を強制したり、オンデマンドで新しい環境をスピンアップしたり、タスク完了時にそれらを破棄したりできます。

優れたサンドボックスには優れたデフォルトが付属しています：プリインストールされた言語ランタイムとパッケージ、GitとテストCLI、Webインタラクション用のヘッドレスブラウザ。ブラウザ、ログ、スクリーンショット、テストランナーは、エージェントが自身の作業を観察し、自己検証ループを閉じることを可能にします。

モデルは自分の実行環境を設定しません。エージェントがどこで実行されるか、何が利用可能か、そしてどのように出力を検証するかは、すべてハーネスレベルの決定です。

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

モデルは、重みと現在コンテキストにあるもの以外の追加知識を持ちません。重みを編集できない場合、知識を追加する唯一の方法はコンテキスト注入です。

ファイルシステムが再びプリミティブです。ハーネスはAGENTS.mdのようなメモリファイル標準をサポートし、毎回の開始時に注入されます。エージェントがそのファイルを編集すると、ハーネスはそれをリロードし、あるセッションの知識が次のセッションに引き継がれます。これは粗いながらも効果的な継続的学習の形態です。

トレーニング時に存在しなかった知識（新しいライブラリバージョン、最新のドキュメント、今日のデータ）については、ウェブ検索やContext7のようなMCPツールがカットオフを埋めます。これらはユーザーに任せるよりもハーネスに組み込むと便利なプリミティブです。

コンテキストの劣化との戦い

コンテキスト劣化とは、コンテキストウィンドウがいっぱいになるにつれてモデルの推論とタスク完了能力が低下する現象です。コンテキストは希少であり、ハーネスは大部分が優れたコンテキストエンジニアリングのための配信メカニズムです。

3つのテクニックが繰り返し現れます：

圧縮。ウィンドウがいっぱいに近づくと、何かを犠牲にしなければなりません。APIエラーを許容することはプロダクションハーネスには選択肢ではないため、ハーネスは古いコンテキストをインテリジェントに要約してオフロードし、エージェントが作業を続けられるようにします。

ツール呼び出しのオフロード。大きなツール出力（2000行のログファイルなど）は、シグナルをほとんど追加せずにコンテキストを乱雑にします。ハーネスはしきい値を超えた先頭と末尾のトークンを保持し、完全な出力をファイルシステムにオフロードし、エージェントがオンデマンドで読み取れるようにします。

スキルの段階的開示。起動時にすべてのツールとMCPをコンテキストにロードすると、エージェントがアクションを起こす前にパフォーマンスが低下します。スキルにより、ハーネスはタスクが実際に必要とする場合にのみ命令とツールを明らかにできます。

Anthropicのハーネス記事は、非常に長いタスクのためにさらに1つのテクニックを追加しています：完全なコンテキストリセット。ハーネスはセッションを破棄し、コンパクトな引き継ぎファイルから再構築します。彼らは、長いタスクには圧縮だけでは不十分であり、構造化されたブリーフィングから新たに始める必要がある場合があると明言しています。これは、通常「メモリ」について考える方法よりも、新しいエンジニアをオンボーディングする方法に近いです。

長期間実行：ラルフループ、計画、検証

自律的な長期間作業は聖杯であり、最も難しい部分です。今日のモデルは早期停止、複雑な問題の分解の貧弱さ、および複数のコンテキストウィンドウにまたがる作業の非一貫性に苦しんでいます。ハーネスはこれらすべてを考慮して設計する必要があります。

以前、自己改善エージェントや2026年のトレンド記事でラルフループのような自律コーディングループについて書きましたが、この枠組みで改めて述べる価値があります：フックがモデルの終了しようとする試みを傍受し、元のプロンプトを新しいコンテキストウィンドウに再注入し、エージェントに完了目標に対して継続するよう強制します。各イテレーションはクリーンな状態で始まりますが、ファイルシステムを介して前の状態を読み取ります。これは、単一セッションのエージェントをマルチセッションにする驚くほど単純なトリックであり、「より賢いモデルを使う」だけからは決して導き出せない種類のプリミティブです。

計画とは、モデルが目標を一連のステップに分解し、通常はディスク上の計画ファイルに書き込むことです。ハーネスはプロンプトと計画ファイルの使い方のリマインダーでこれをサポートします。