ハーネスエンジニアリングとは？AIエージェントを実用的なツールにする考え方

ハーネスエンジニアリングを簡単に言うと

ハーネスエンジニアリングは、言語モデルの周りに、実際の作業を安定してこなせる環境を構築するための工学分野です。harness（ハーネス）は「馬具」や「安全帯」を意味する言葉です。モデルは非常に強力ですが、どこへ進むべきか、どのツールを使うべきか、いつ止まるべきかを自分では知りません。ハーネスはその力を正しい方向へ導きます。

最も短い定義は次のとおりです。

エージェント = モデル + ハーネス

モデルとは重みと、推論しテキストやコードを生成する能力のことです。ハーネスはそれ以外のすべてを指します。CLAUDE.md や AGENTS.md などのシステム指示ファイル、ツールの組み合わせ（shell、ファイル編集、MCPサーバー）、コマンドを実行するサンドボックス、セッションをまたいで保存される状態ファイル、そしてエラーをエージェントに知らせるテストやリンター、フックです。ハーネスを取り除くと、テキストで答えることしかできないチャット画面が残るだけです。

同じエージェントが「ベテラン」にも「新人」にもなる理由

こんな経験はないでしょうか。あるリポジトリではエージェントがベテランの開発者のように働くのに、別のリポジトリでは迷ってしまい、昨日の決定を忘れ、動かない機能を「完了しました」と報告する。このとき最初に思いつくのは、より新しいモデルに替えることです。しかし多くの場合それは効果がありません。どちらのケースでもモデルは同じだからです。違うのは環境です。

ハーネスエンジニアリングの出発点は、ここにあります。エージェントが壊れているのではなく、その周囲が壊れているのです。テストを実行する手段がなければ、エージェントはテストできません。試したことがどこにも記録されていなければ、エージェントは自分が何を試したかを覚えていません。どの検査も機能が壊れていると教えてくれなければ、エージェントはそれに気づけません。これらはモデルの「性格」ではなく、設計上の欠陥です。体系的に直すことができます。

ハーネスが貧弱なときの典型的な症状

• 新しいセッションのたびに、環境の修復から始まる。依存関係が合わない、データベースが起動しない、変数がない。
• 前回のセッションを覚えていないため、すでに却下された方法を繰り返す。
• ルールが指示ファイルに明記されているのに、エージェントが無視する。
• 「テストはすべて成功」なのに機能は壊れている。テストが別のものを確認していたため。
• 三つのタスクを同時に始めて、どれも終わらせられない。

ハーネスの構成要素：5つのサブシステム

よくある誤解は、ハーネスを「プロンプトが書かれたファイル一つ」とみなすことです。実際には五つの仕組みからなり、それぞれ壊れ方が異なります。

指示

指示が解決するのは「エージェントは必要なルールを見つけられるか」という問題です。良い入口ファイルは教科書ではなく地図です。検証コマンドと厳格な制約を載せた短い目次があり、詳細は必要になったときにエージェントが開く別ドキュメントに置きます。良い指示は不変条件（「すべてのSQLクエリはパラメータ化する」）を定めるもので、実装を一行ずつ指定するものではありません。

ツール

エージェントが検証できるのは、アクセスできるものだけです。リンターを実行できなければ、「コミット前にリンターを実行せよ」というルールは機能しません。ツールは、エージェントの組み込み機能（ファイルの読み書き、コマンド実行）や、MCP（データベース、ブラウザ、タスク管理ツールへのアクセスを提供するプロトコル）を通じて与えられます。

環境

環境は、エージェントがコマンドを実行する場所です。ワンコマンドで起動でき、セッションごとに同じ状態であり、ミスによる被害を抑えられる必要があります。本番環境にアクセスできないサンドボックス、専用のブランチや作業コピー、そして一分以内に元の状態へ戻せることがその条件です。

状態

モデルはセッションをまたいだ記憶を持ちません。リポジトリに書かれていないものは、コンテキストウィンドウとともに消えます。そのため、目標、完了した作業、下した決定、行き詰まった方法、次のステップはファイルに残す必要があります。確認方法は簡単です。新しいセッションを開き、エージェントに「続けて」とだけ伝えてみてください。すぐに作業を始めるか、それとも何をすればよいか尋ね返すかで分かります。

フィードバック

フィードバックループは最も重要なサブシステムです。これがなければ、エージェントは自分だけが判定者となり、タスクが終わったと正直に思い込みます。テスト、型チェック、リンター、編集のたびに走るフック、ブラウザ上のE2Eシナリオなど、どれもエラーがまだ安く直せるうちに、エージェントへ赤い信号を返します。

ハーネスは一覧ではなくループである

五つのサブシステムは一つの閉じたループとして機能します。モデルは指示を読み、ツールを通じて環境で行動し、リポジトリを変更します。検証がその結果をチェックします。赤ならモデルに戻して修正させ、緑なら状態に記録します。状態は次のセッションのために指示を更新します。

指示 → モデル → ツール → 環境 → 変更
          ↑                    ↓
          └── 赤 ── 検証 ───────┘
                         ↓ 緑
                     状態 →（次のセッション）

どれか一つの矢印を取り除くと、ループはその場所で切れます。検証がなければエージェントはエラーに気づけません。状態がなければ、次のセッションは作業ではなく考古学から始まります。だからこそ、一つのサブシステムに投資しても別のサブシステムの欠落は補えません。五ページの AGENTS.md も、テストがなければ役に立たないのです。

ハーネスエンジニアリングとプロンプト／コンテキストエンジニアリングの違い

これらの概念は競合するものではなく、入れ子の関係にあります。

プロンプトエンジニアリングは指示サブシステムの一部です。コンテキストエンジニアリングは指示と状態にまたがり、エージェントが各瞬間に何を見ているかを扱います。ハーネスエンジニアリングは、コンテキストウィンドウには収まらないものを加えます。アクセス権、サンドボックス、テスト、フック、作業プロセスです。どれほど優れたプロンプトでも、物理的にテストを実行できないエージェントは助けられません。

なぜハーネスが必要なのか：長いタスクの数学

直感的には、各ステップの正答率が95%のモデルはほぼ完璧に思えます。しかしエージェントのタスクは多数のステップからなり、エラーは積み重なります。ステップが互いに独立しているとすれば、すべてのステップをエラーなしで通過する確率は、各確率の積になります。

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

10ステップを一度もエラーなしで完了するのは約60%の実行にとどまり、50ステップではおよそ十回に一回もありません。モデルの正答率を97%まで上げるのは、コストが高く、自分の手に負えるものでもありません。しかしエラーが起きたその場のステップで捕まえ、エージェントに直させることはハーネスの仕事です。フィードバックループは、「一つのエラーが次のエラーを引き起こす」連鎖を、短くて修正しやすいステップの連続に変えます。

例：同じエージェント、二つのリポジトリ

タスク：FastAPIで書かれた決済バックエンドに、クーポンによる割引を追加する。

ハーネスなし

エージェントは数ファイルを読み、割引計算関数と、その関数だけを単独で検証する単体テストを書きます。テストは成功し、エージェントは「完了」と報告します。しかし注文合計の計算が別モジュールにあることは知らず、データベースを起動して注文フロー全体を実行することもできませんでした。一日後、カートに割引が適用されていないことが判明します。

ハーネスあり

リポジトリのルートには数十行の AGENTS.md があり、環境の起動方法、必須の検証コマンド、決済アーキテクチャの説明先が書かれています。環境は docker compose up -d で起動します。計画ファイルには完了条件があります。「クーポン付き注文のE2Eシナリオが通る」。変更のたびにフックがリンターと型チェックを実行し、エージェントは完了を報告する前にE2Eテストを必ず実行します。

# AGENTS.md（抜粋）
## 検証——「完了」と言う前に必須
make lint        # ruff + mypy
make test        # pytest、単体テストと結合テスト
make e2e         # 注文シナリオ

## MUST
- 金額は円単位の整数（int）で計算し、float は使わない
- SQLクエリはすべてパラメータ化する
- 本番に適用済みのマイグレーションは変更しない

モデルは同じです。しかし今回は、エージェントがプロジェクトマップから金額計算モジュールを見つけ、E2Eテストが一回目で失敗し、割引がカートに届いていないと気づいて修正し、E2Eが通ってから報告します。結果の違いは、すべてハーネスの功績です。

どこから始めるか

1. エージェントが自分の作業をどう検証するかを書き出す。必ず実行すべきコマンドを一〜三個。フィードバックが最も効果が大きいので、ここから始めます。
2. 環境を再現可能にする。ワンコマンドで起動でき、すぐに元へ戻せる状態にします。
3. 状態ファイルを作る。目標、完了した作業、決定と行き詰まり、次のステップを記録します。
4. 指示を地図に縮める。検証コマンド、厳格な制約、詳細ドキュメントへのリンクだけにします。
5. エージェントの失敗ログを付ける。失敗のたびに、どのサブシステムが原因だったかを記録します。ログは次に直すべき場所を教えてくれます。

実用的な方法は、五つのサブシステムをそれぞれ1〜5点で採点し、最も低いものに30分かけて手を入れ、同じ典型的なタスク群を改善の前後で実行することです。こうすればハーネスの改善は感覚ではなく測定できるものになります。

まとめ

ハーネスエンジニアリングが対象とするのは、モデルそのものではなく、それを取り巻くすべて、つまり指示、ツール、環境、状態、フィードバックのループです。エージェントの信頼性は、このループの中で最も弱い部分で決まります。そのため、モデルを変えても不安定さが治ることはまれですが、テストや計画ファイルを一つ加えるだけで改善することはよくあります。サブシステムの一つひとつと、ハーネス全体の組み立ては、ハーネスエンジニアリングの講座で実践を通して解説しています。