ハーネスエンジニアリングとは、AI エージェントが犯したミスの再発を防ぐ仕組みを、ドキュメント・ツール・アーキテクチャ制約の設計によって構造的に構築する実践手法である。Mitchell Hashimoto 氏の発信と OpenAI エンジニアリングチームの実践事例がほぼ同時期に登場し、Martin Fowler 氏も言及したことで急速に広まった。

この記事では、AI エージェントを業務に導入済み、または導入を検討しているエンジニアやマネージャーに向けて、ハーネスエンジニアリングの概念・構成要素・実践ステップを解説する。「エージェントは動くけど安定しない」という課題を抱えている方に、明日から適用できる具体的なアプローチを提示する。

プロンプトを書き直して祈るのではなく、同じミスを構造的に二度と起こさない仕組みを作る——それがハーネスエンジニアリングの核心だ。

OpenAI の表現を借りれば「try harder ではなく、欠けている能力を追加する」姿勢にあたる。エージェントの出力が期待と異なったとき、プロンプトに注意書きを追加するのは対症療法にすぎない。ハーネスエンジニアリングは、その失敗が物理的に再現できなくなるレベルまで環境側を変えることを目指す。

プロンプトエンジニアリングは「何を伝えるか」の最適化だ。入力テキストの構造・指示の明確さ・few-shot の例示を工夫することで、モデルの出力品質を上げる。一方、ハーネスエンジニアリングは「エージェントが動く環境そのもの」を設計する。ドキュメント、ツール、リンター、テスト、CI/CD パイプラインまで含めた包括的なアプローチであり、プロンプトはその構成要素の一部にすぎない。

両者は排他的ではなく補完関係にある。良いプロンプトは良いハーネスの一部だが、プロンプトだけでは防げない失敗が存在する。たとえば「本番 DB に対して DROP TABLE を実行しない」というルールは、プロンプトに書くよりも pre-commit フックで機械的にブロックするほうが確実だ。

コンテキスト・エンジニアリングは、モデルに渡すコンテキスト（参照情報・指示・ツール定義）を最適化する技術領域だ。Shopify CEO の Tobi Lutke 氏はこれを「タスクが LLM にとって解決可能になるよう、すべてのコンテキストを整える技芸」と表現している。ハーネスエンジニアリングはこれを包含しつつ、コンテキストの外側——リンターによる制約、テストによる検証、CI/CD による品質ゲート——まで設計範囲を広げている。コンテキスト・エンジニアリングが「エージェントに何を見せるか」なら、ハーネスエンジニアリングは「エージェントが何をできて、何をできないか」を環境レベルで規定する。

注意すべきは、コンテキストウィンドウが大きいほど性能が上がるわけではないという点だ。Chroma の研究では、コンテキスト長が伸びるほどモデルの性能が劣化する傾向が確認されている。ツール定義や指示の蓄積がノイズとなり、エージェントが「何でも知っているが何もうまくできない」状態——いわゆる Dumb Zone——に陥る。ハーネス設計ではコンテキストの量より構造を重視し、必要な情報をオンデマンドで開示する Progressive Disclosure が有効とされている。

AI エージェントの能力が上がるほど、「たまに壊れる」リスクも大きくなる。能力の向上と制御の仕組みは同時に進化させる必要がある。

AI エージェントのデモは華やかだ。コードを書き、テストを実行し、PR を作成する一連の流れを見せられると、すぐにでも導入したくなる。しかし実際にチームで運用を始めると、10 回中 8 回は期待どおりに動くが、残り 2 回で予期しないファイルを削除したり、既存のアーキテクチャを無視した変更を入れたりする。

この「8 割成功・2 割破壊」の状態は、プロンプトの改善だけでは解消しにくい。なぜなら、エージェントの失敗パターンはセッションごとに異なり、プロンプトで網羅的に禁止事項を列挙するのは現実的でないからだ。

Hashimoto 氏は自身のエージェント開発経験から「ミスのたびに仕組みを作る」という原則を発信した。ほぼ同時期に OpenAI のエンジニアリングチームも、社内でのエージェント運用から得た知見を公開している。両者が独立して同じ結論に達した背景には、エージェントの実用化が一定の閾値を超え、「品質の安定化」が共通のボトルネックになったという事情がある。Martin Fowler 氏がこれに言及したことで、ソフトウェアエンジニアリングのコミュニティ全体に認知が広がった。

ハーネスエンジニアリングの構成要素は論者によって分類が異なるが、代表的には 3 つのレイヤーで整理できる。

OpenAI は Context / Constraints / Feedback / Cleanup の 4 軸で説明し、他の実践者は Tools / Docs / Feedback loops を軸にするなど、フレームワークは統一されていない。ここでは実務で取り組みやすい 3 層——ドキュメント、ツール、制約——に整理して解説する。

エージェントが参照するドキュメントに、リポジトリの不変条件やコーディング規約を記述する。OpenAI は AGENTS.md、Claude Code では CLAUDE.md がこの役割を担う。

ただし、Martin Fowler 氏が指摘するとおり「大量のマークダウンをメンテナンスすること」が目的ではない。OpenAI の実践では、100 行程度のインデックスファイルと、構造化された詳細ドキュメント（設計書・仕様書・実行計画）を分離している。エージェントが必要な情報に最短経路でたどり着ける構造にすることが肝要だ。

OpenAI のエンジニア Ryan Lopopolo 氏は「Taste Invariants（趣味の不変条件）」という概念を紹介している。コードレビューで「なんとなく気に入らない」と感じたとき、その理由を言語化できるなら、それをルールとして書き下ろせるという考え方だ。たとえば「並行処理のヘルパー関数が複数箇所に重複定義されている」という不満は、「公式の定義場所以外でその関数を定義することを禁止する」カスタム ESLint ルールに変換できる。主観的な好みを決定的な制約に変えることで、エージェントに「センス」を注入する。

当社でも CLAUDE.md を運用しているが、ルール 1 行の追加がその後のセッション全体の品質を底上げする場面は珍しくない。逆に、ルールが 500 行を超えたあたりからエージェントの遵守率が下がり始めた経験もあり、「書く量」より「構造の設計」が重要だと実感している。

エージェントに「目視確認して」と指示するのではなく、確認を自動化するツールを渡す。スクリーンショット撮影、テストランナー、リンター、MCP サーバーなどが該当する。

MCP（Model Context Protocol）はエージェントが外部ツールやデータソースに接続するための標準プロトコルで、ハーネスのツール層を構築する際の基盤技術になる。たとえば Supabase MCP を接続すれば、エージェントは DB スキーマを直接確認してからクエリを書けるようになり、「存在しないカラムを SELECT する」類のミスが構造的に減る。

ツール層にはさらに 3 つの仕組みが有効だ。Hooks（フック）はエージェントのライフサイクルイベント（ツール呼び出し後、タスク完了時など）に差し込む決定的な制御フローで、成功時は何も出力せず（コンテキストを汚さない）、失敗時だけエラーを浮上させる。Sub-Agents（サブエージェント）は個別タスクを隔離された子エージェントに委任し、親エージェントのコンテキストを保護する「コンテキストファイアウォール」として機能する。Back-Pressure（バックプレッシャー）はエージェントの自己検証能力を高める仕組みで、テスト通過時の出力は飲み込み、失敗時のみ結果を表示することでコンテキスト効率を最大化する。

レイヤー間の依存方向をカスタムリンターで機械的に検証し、エージェントが構造を壊す変更を物理的にコミットできないようにする。OpenAI の実践から読み取れる方針として、非決定的なプロンプト指示より決定的なリンター・テスト・pre-commit フックへの投資を優先する考え方がある。

これはガードレールの考え方とも通じる。AI ガードレールが「モデルの出力を検査・制御する仕組み」であるのに対し、ハーネスの制約層は「エージェントの行動範囲を事前に規定する仕組み」だ。出力を事後チェックするより、行動を事前に制限するほうがコストが低い。

モデルを変えずにハーネスだけを改善して、どの程度の効果が得られるのか。LangChain が Terminal Bench 2.0 で検証した結果は示唆的だ。同一モデルのまま、ループ検出ミドルウェア（同じファイルへの編集が N 回を超えたらアプローチの再考を促す）、完了前チェックリストミドルウェア（エージェントの終了時に検証パスを義務づける）、推論強度の段階切り替え（計画フェーズでは高い推論コスト、実装フェーズでは中程度、検証フェーズで再び高い推論コスト）といったハーネス層の改善だけで、スコアが 52.8% から 66.5% に向上した。モデル自体には一切手を加えていない。

Anthropicも別のアプローチを提示している。Generator-Evaluator パターンでは、実装を担当するエージェントと品質を評価するエージェントを分離する。GAN（敵対的生成ネットワーク）にヒントを得た構造で、エージェントが自分の出力を自己評価すると「明らかに平凡な成果物でも自信たっぷりに褒める」バイアスが生じるため、評価を独立させることで客観性を担保する。実装前にスプリント契約（明示的な受け入れ基準）を定義し、評価エージェントはその基準に沿って採点する仕組みだ。

ハーネスエンジニアリングは大規模な基盤整備から始める必要はない。ミスを 1 つ潰すところから段階的に積み上げられる。

エージェントが失敗するたびに、何が起きたか・なぜ起きたか・どうすれば防げたかを 1 行で記録する。形式は問わない。GitHub Issue でも Notion でもテキストファイルでもよい。重要なのは「同じミスを 2 回観測したら、それは仕組みで防ぐべき問題だ」という判断基準を持つことだ。

エラーログから最も頻度の高い失敗を 1 つ選び、CLAUDE.md（または AGENTS.md）にルールとして追加する。

この 1 行で、以後のすべてのセッションでエージェントがそのミスを繰り返す確率は大幅に下がる。完璧なドキュメント体系を先に設計しようとするより、「1 ミス 1 ルール」で積み上げるほうが実効性が高い。

ドキュメントに書いたルールのうち、機械的に検証できるものは pre-commit フックやカスタムリンターに移行する。ドキュメントのルールは「守ってほしい指針」だが、リンターは「物理的に違反をブロックする壁」になる。DevOps の文脈でいう「シフトレフト」と同じ発想で、問題を検出するタイミングをできる限り早い段階に移す。

エージェントの普及に伴い、エンジニアの仕事は「コードを書く」から「エージェントが正しく動ける環境を整える」方向へシフトしつつある。

OpenAI の実践からは、エンジニアの仕事がシステム基盤（CI/CD・テレメトリ）の安定稼働、リポジトリ構造・ドキュメントの足場作り、AI を通じた人間労力のスケーリングへと重心を移していく方向性が読み取れる。コードの行数で生産性を測る時代から、エージェントが生み出すアウトプットの品質で測る時代への転換ともいえる。

Martin Fowler 氏の共著者 Birgitta Bockeler 氏は、人間とエージェントの関わり方を 3 つのモードで整理している。Outside the Loop（バイブコーディング）は成果だけ指定してエージェントに丸投げするモードで、非効率な解決策が積み重なるリスクがある。In the Loop は出力を人間が逐一レビューするモードだが、エージェントの生成速度に人間のレビューが追いつかないボトルネックが生じる。推奨されるのは On the Loop——出力そのものではなくハーネスを改善することに注力するモードだ。不満を感じたときに成果物を直接修正するのではなく、ハーネスを変更して以後の出力全体を底上げする。この規律を保てるかどうかが、ハーネスエンジニアリングの定着を左右する。

これは HITL（Human-in-the-Loop）の考え方とも整合する。人間が全工程を手作業で実行するのではなく、エージェントの作業を監督・検証・承認する役割にシフトする。ハーネスエンジニアリングは、この監督コストを下げるための投資だ。

放置すると AI 生成物の品質はじわじわ劣化する。OpenAI はゴールデンプリンシプル（守るべき原則）の定義、定期的なスコアリング、自動修正 PR の生成で対処している。興味深いのは、OpenAI がハーネスエンジニアリングを導入した結果、日次のスタンドアップミーティングを増やしたという点だ。エージェントの生成速度が上がるほど、アーキテクチャパターンがチェックイン間に大きく変わりうるため、30 分の日次同期を設けて方向性のドリフトを早期に検知している。この体制で 5 ヶ月間に 1,500 以上の PR を処理し、一人あたりの生産性は当初の 4 分の 1 エンジニア相当から 3〜10 倍にまで向上したと報告されている。

ハーネスは一度構築して終わりではなく、エージェントの能力が上がるたびに再構築される前提で設計するのが現実的だ。Anthropic の検証でも、モデルのアップグレード（Sonnet → Opus）によって従来必要だったコンテキストリセットが不要になるなど、ハーネスの前提がモデル進化に伴って変わることが確認されている。

ハーネスエンジニアリングの導入自体にも落とし穴がある。過剰なドキュメントと過剰な制約が代表的な失敗パターンだ。

CLAUDE.md が 1,000 行を超えると、エージェントのコンテキストウィンドウを圧迫し、かえって重要なルールが埋もれる。OpenAI の実践でも、インデックスは 100 行程度に抑え、詳細は別ファイルに分離する構造が推奨されている。「全部を 1 ファイルに書く」のではなく「必要な情報に最短でたどり着ける構造を作る」ことが設計の要点だ。

禁止事項を際限なく追加すると、エージェントが安全な行動すら取れなくなる。制約は「発生頻度が高く、影響が大きいミス」に絞り、それ以外はドキュメントの推奨事項に留める。制約とガイダンスの使い分けが重要で、すべてをハードブロックにする必要はない。

プロンプトエンジニアリングは「モデルへの入力」を最適化する技術、ハーネスエンジニアリングは「エージェントが動く環境全体」を設計する実践手法だ。プロンプトはハーネスの一部であり、両者は排他的ではなく補完関係にある。

むしろ小規模チームのほうが始めやすい。CLAUDE.md に 1 行ルールを追加するところからスタートでき、大規模な基盤整備は不要だ。ミスが起きるたびに 1 つずつ仕組みを追加していけば、自然とハーネスが育っていく。

エージェントの能力が上がれば、一部のハーネスは不要になるだろう。しかし能力が上がるほど行動範囲も広がり、新しい種類のミスが生まれる。ハーネスの内容は変わっても、「ミスを仕組みで防ぐ」という設計思想自体が不要になることは考えにくい。

Anthropic の検証では、フルハーネス（Generator-Evaluator パターン + スプリント契約 + キャリブレーション付き評価）の構築に約 6 時間・200 ドルかかった一方、ハーネスなしの単独エージェントは 20 分・9 ドルで完了した。ただし成果物の品質には大幅な差が出ている。コスト判断は「エージェントに何を任せるか」の重要度に比例する。使い捨てのスクリプトにフルハーネスは不要だが、本番コードの継続的な生成には投資が見合う。

ハーネスエンジニアリングは、AI エージェントの品質を「祈り」ではなく「構造」で安定させるための実践手法だ。ドキュメントによる知識基盤、ツール（Hooks・Sub-Agents・Back-Pressure を含む）による自動検証、アーキテクチャ制約による行動制限を段階的に構築していく。LangChain の検証ではハーネス改善だけでスコアが 52.8% から 66.5% に向上しており、モデルを変えなくても環境設計で品質は大きく変わる。

最初の一歩は小さい。エージェントのミスを 1 つ記録し、CLAUDE.md に 1 行ルールを追加するだけでよい。そこから始めて、頻度の高い失敗をリンターや pre-commit フックで機械化していけば、チーム全体のエージェント運用品質は着実に上がっていく。重要なのは Fowler 氏らが推奨する「On the Loop」の姿勢——成果物を直接修正するのではなく、ハーネスを改善して以後の出力全体を底上げする——を維持することだ。