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

問題: モデルをアップグレードしました。しかしパフォーマンスはほとんど変わりません。どのモデルバージョンを使っても、セッションのたびに同じ失敗パターンが繰り返されます。

すぐできる改善: モデルのチューニングをやめて、ハーネスをチューニングしましょう。あるチームはツールを15個から1つのbashコールに絞り込み、精度が80%から100%に向上し、トークン使用量が37%削減されました。

理解: エージェント = モデル + ハーネス。モデルは推論を担当します。ハーネスはそれ以外のすべてを担当します。エージェントが使えるツール、受け取るコンテキスト、エラーの表示方法、結果の検証方法などです。実際のところ、実世界のパフォーマンスにおける制約となるのはモデルではなくハーネスです。

ハーネスとは何か

ハーネスとは、AIモデルを囲むソフトウェア層であり、モデルの推論以外のすべてを管理します。ツールを呼び出し、メモリを管理し、タスクをルーティングし、検証チェックを実行します。どのコンテキストがどの形でプロンプトウィンドウに届くかを決定します。

Martin Fowlerの定義は明確です。ハーネスとは、エージェントの中からモデル自体を除いたすべてのものです。2つの制御の方向性があります。

• フィードフォワード（ガイド）: エージェントが行動する前に誘導します。システムプロンプト、コンテキストインジェクション、ツールの制限などです。最初の出力が正しい確率を高めます。
• フィードバック（センサー）: エージェントが行動した後に観察し、自己修正を可能にします。リンター、型チェッカー、テストランナー、ビルドフックなどです。エラーを人間の目に触れる前に検出します。

どちらの方向性だけでも不十分です。フィードバックなしのフィードフォワードは、同じミスを繰り返し修正するエージェントを生みます。フィードバックなしのフィードフォワードは、ルールを持ちながらもそれが失敗したときに学習しないエージェントを生みます。

なぜハーネス設計がモデルのアップグレードより効果的なのか

SWE-benchのリーダーボードがこの主張を明快に示しています。コーディングベンチマークでは、同じモデルでもスキャフォールドが異なると42%と78%という異なるスコアが出ます。モデルは変わっていません。ハーネスが変わったのです。

Vercelのケースは最も明確な例です。そのチームはエージェントのツールを15個以上から1つのbashツールに削減しました。ベンチマーク上で、精度は80%から100%に向上し、トークンは37%削減され、速度は3.5倍改善されました。モデルには手を加えていません。ハーネスの複雑さを取り除いただけです。

このパターンは多くのチームで繰り返されています。Harveyの法律AIチームはモデル周辺のシステムを改善することでタスク完了率を40.8%から87.7%に向上させました。OpenAIの社内ツールチームは「私たちの最も困難な課題は、環境・フィードバックループ・制御システムの設計に集中している」と結論付けています。

モデルはエンジンです。ハーネスは車です。エンジンをアップグレードすることは有効です。しかし、より良い車を作ることの方が通常は高いレバレッジを発揮します。

5つのレバー

すべてのハーネスは同じ制御ポイントの集合から構築されています。適切なレバーを正しい順序で引くことが、この技術の本質です。

1. ツール設計

エージェントが使えるツールは、その能力の範囲を定義します。ツールが多すぎると、エージェントはどれを使うかの判断にコンテキストを浪費します。少なすぎると、エージェントは回避策に頼ります。Vercelの結果が正準的な参照点です。少数の鋭いツールは、広い汎用ツールキットを上回ります。

ツールは能力ではなく成果に基づいて設計してください。execute_commandではなくrun_testsというツールの方が優れています。エージェントが何を実行するかを決める必要がなくなるからです。

2. コンテキストインジェクション

エージェントが行動前に持つ知識が、何を生み出すかを決定します。コンテキストインジェクションとは、適切な情報を適切なタイミングでプロンプトウィンドウに入れることです。アーキテクチャドキュメント、コーディング規約、最近のエラー、現在のファイルツリーなどです。

失敗パターンはオーバーインジェクションです。利用可能なすべてのものでウィンドウを溢れさせることです。適切なタイミングでの関連性の高いコンテキストは、大量の無差別なダンプを上回ります。

3. メモリアーキテクチャ

単一セッションのエージェントは、ウィンドウが閉じるとすべてを忘れます。適切にハーネスされたエージェントは、過去の決定、観察されたパターン、以前見たエラーを引き継ぎます。メモリは短期的（会話状態）、中期的（セッションログ）、または長期的（起動時に読む永続ファイル）である可能性があります。

Claude CodeのCLAUDE.mdファイルは長期メモリのレバーです。エージェントはセッション開始時にそれを読みます。そこに書いたものが以降のすべてのセッションを形成します。

4. 検証ループ

ハーネスはエージェントがスキップできないチェックを実行します。型チェッカー、リンター、ビルドコマンド、テストスイートなどです。これらがすべてのエージェントアクション後に自動センサーとして実行されると、エラーはそれを生み出したセッションと同じセッション内で表面化します。修正コストが下がります。

原則：品質チェックはできるだけ左側に保ちましょう。コミット前に検出された型エラーは数秒のコストです。レビューで検出された同じエラーは1時間のコストです。

5. 制約設計

エージェントができないことは、できることと同じくらい重要です。プロダクション設定への書き込みアクセスの制限、特定のツール呼び出しのブロック、エージェントが触れられるファイルの制限は、すべて制約のレバーです。目的はエージェントを妨げることではなく、制約によって不可能になるミスのクラスを排除することです。

制約のパラドックス

エージェントにルールを追加することが、必ずしもより良い動作を生むとは限りません。これが制約のパラドックスです。指示で過負荷になったハーネスは、最小限のガイダンスでエージェントが達成するレベル以下にパフォーマンスを低下させることがあります。

そのメカニズムは単純です。すべての制約がコンテキストを消費します。矛盾するルールはエージェントが乗り越えなければならないノイズを生みます。あらゆるエッジケースをカバーする長い指示セットは、最も重要な5つだけをカバーする短く明確なものより頻繁にパフォーマンスが悪くなります。

実用的な解決策は優先順位付けです。実際に繰り返す失敗パターンを特定してください。それらに対して制約を書きましょう。それ以外はモデルの判断に委ねましょう。ハーネスは頻繁に発生する失敗を排除すべきです。考えられるすべての悪い結果を列挙しようとすべきではありません。

計算的制御と推論的制御

ハーネス制御は2つのタイプに分かれます。

計算的制御は決定論的で高速です。型チェッカー、リンター、テストランナー、ビルドシステムなどです。ミリ秒から秒単位で実行されます。結果は信頼性が高く、すべてのエージェントアクションに対して実行するほど安価です。

推論的制御はモデルを判断者として使用します。コードレビューエージェント、意味的品質チェック、「LLM-as-evaluator」パターンなどです。より遅く、高価で、非決定論的です。計算的制御では見逃すものを検出します。セマンティックな重複、誤って適用されたパターン、誤解された指示などです。

実用的な分割：すべての変更に計算的制御を自動的に実行し、高いリスクを持つ変更や統合後に推論的制御を選択的に実行します。2つの層は競合するのではなく、補完的です。

3つのハーネスカテゴリー

ハーネスはエージェント出力の異なる次元を規制します。それらを区別することが有効なのは、カテゴリーによって適切な制御が異なるからです。

保守性ハーネス: コード品質、スタイル、構造に関するガイドとセンサーです。これは最も構築しやすいカテゴリーです。既存のツール（リンター、型チェッカー、カバレッジツール）が直接接続できます。ほとんどのチームはここから始めます。

アーキテクチャ適合性ハーネス: 構造的制約を強制するガイドとセンサーです。モジュール境界、依存関係ルール、パフォーマンス予算などです。フィットネス関数は自動チェックとして実行されます。アーキテクチャのドリフトは、何ヶ月も後のレビューで発見されるのではなく、検出されます。

動作ハーネス: 機能的正確さに関するガイドとセンサーです。これは最も難しいカテゴリーです。AIが生成したテストスイートはまだ指定された動作を完全に代替するほど信頼できません。ほとんどのチームは現在、仕様書（フィードフォワード）とAI生成テストに選択的な手動検証を加えた組み合わせを使っています。未解決の問題は、手動監視を減らせるほどエージェント生成テストへの十分な信頼を構築することです。

Claude Codeの出発点

Claude Codeはいくつかのハーネスレバーを直接公開しています。

CLAUDE.mdは主要なフィードフォワード制御です。アーキテクチャの決定、命名規則、従うべきまたは避けるべきパターン、エージェントがすべきでないことについての明示的なルールなどです。このファイルはすべてのセッション開始時にロードされます。ここに書いたものは、プロンプトなしでエージェントのデフォルト動作を形成します。

**.claude/agents/**のスペシャリスト定義により、エージェントごとにスコープを制限できます。マイグレーションファイルのみを触れるデータベースエージェントは、誤ってフロントエンドコンポーネントを変更することができません。スコープ制限は最もコストの低い制約の1つです。

フックにより、計算センサーをエージェントループに接続できます。型チェッカーを実行するpost-editフックは、すべてのファイル変更がエージェントが次のタスクに進む前に検証されることを意味します。

settings.jsonのパーミッションルールは、エージェントがアクセスできるツールを定義します。すべてから始めて後で制限しようとするよりも、少ないツールから始めて拡張する方が優れています。

良いハーネスは人間の入力を完全に排除しようとしません。センサーが検出できない決定、ルールではなく判断が解決しなければならない決定に人間の注意を向けます。

よくある質問

エージェント・ハーネス・エンジニアリングとは何ですか？

エージェント・ハーネス・エンジニアリングとは、AIモデルを除いたエージェントのすべてを設計する実践です。これにはツールの選択、コンテキストインジェクション、メモリアーキテクチャ、検証ループ、制約設計が含まれます。ハーネスは、エージェントが受け取る情報、取れるアクション、エラーが人間のレビューに達する前にどのように検出・修正されるかを決定します。

なぜハーネスはモデルより重要なのですか？

SWE-benchのコーディングベンチマークでは、同じモデルがあるスキャフォールドで42%、より優れたスキャフォールドで78%のスコアを出します。Vercelはエージェントのツールの80%を削除し、精度が80%から100%に向上し、トークンが37%削減されました。モデルの推論は固定されています。ハーネスが、その推論能力がどれだけタスクに届くかを決定します。

AIエージェントスキャフォールドとは何ですか？

スキャフォールドとは、複雑な多段階タスクを可能にするためにAIモデルを取り囲む構造的な層です。エージェントに呼び出すツール、読み書きするメモリ、エラー後に再実行するループ、自己修正のためのフィードバック信号を提供します。スキャフォールドとハーネスはほとんどの文脈で互換的に使われます。区別するとすれば、ハーネスは制御とガバナンスを強調し、スキャフォールドは構造と実現を強調します。

良いエージェントハーネスはどのように構築しますか？

5つのレバーを順番に始めましょう。まずツール設計、次にコンテキストインジェクション、次にメモリ、次に検証ループ、次に制約です。各レバーについて、理論的なものではなく実際に観察する失敗パターンを特定してください。各失敗を防ぐ最もシンプルな制御を構築しましょう。計算チェック（型チェッカー、リンター、テスト）をすべてのエージェントアクション後に自動的に実行してください。計算的なものが届かない場合にのみ推論的制御を追加してください。

AIエージェントにおける制約のパラドックスとは何ですか？

制約を追加しても、エージェントの動作が必ずしも改善するとは限りません。長い網羅的なルールセットは、すべての制約がコンテキストを消費し、矛盾するルールがノイズを生むため、短く明確なものよりパフォーマンスが悪くなることが多いです。解決策は優先順位付けです。最も頻繁に繰り返される失敗パターンを特定し、それらに対してのみ制約を書きます。それ以外はモデルの判断に委ねましょう。

なぜVercelは15個以上のツールを1つに削減したのですか？

Vercelのチームは、広いツールセットがエージェントに問題の解決方法ではなく、どのツールを呼び出すかの判断にコンテキストを費やさせることを発見しました。1つのbashツールに削減することでそのオーバーヘッドを取り除きました。精度は80%から100%に向上し、トークンは37%削減され、ベンチマークで速度が3.5倍改善されました。原則：少数の鋭いツールは大きな汎用ツールキットを上回ります。

さらなるエージェントの概念を探る:

• エージェントパターン - マルチエージェント作業のオーケストレーション形状
• エージェントの基礎 - サブエージェント、スラッシュコマンド、CLAUDE.mdペルソナ
• サブエージェント設計 - 複数エージェントを調整するためのアーキテクチャパターン
• チームオーケストレーション - 実践におけるビルダーとバリデーターのループ
• カスタムエージェント - スペシャリストエージェント定義の作成