ハーネスエンジニアリング：AIエージェントを実際に機能させるシステム構築の完全ガイド

2026年3月 — 2025年がAIエージェントがコードを書けることを証明した年だったとすれば、2026年は**「難しいのはエージェントではなく、ハーネス（制御機構）である」**ことを学んだ年です。

OpenAIのCodexチームは、100万行以上のコードを含む本番アプリケーションを構築しましたが、そこには人間が書いたコードは1行もありません。エンジニアはコードを書きませんでした。彼らは、AIが確実にコードを書けるようにするシステムを設計したのです。このシステム — 制約、フィードバックループ、ドキュメント、リンター、ライフサイクル管理 — こそが、現在業界でハーネスと呼ばれているものです。

ハーネスエンジニアリングは、これらのシステムを設計する新しい規律です。そして、それはソフトウェアエンジニアであることの意味を変えようとしています。

---

ハーネスエンジニアリングとは？

馬の比喩

「ハーネス（馬具）」という言葉は、手綱、鞍、ハミなど、強力だが予測不可能な動物を正しい方向に導くための装備一式に由来しています。この比喩は意図的なものです。

• 馬はAIモデルです — 強力で速いですが、自分ではどこへ行くべきか分かりません。
• ハーネスはインフラです — モデルの力を生産的に導くための制約、ガードレール、フィードバックループです。
• 乗り手は人間のエンジニアです — 走るのではなく、方向を指示します。

ハーネスがなければ、AIエージェントは広大な野原に放たれたサラブレッドのようなものです。速くて印象的ですが、何かを成し遂げるためには全く役に立ちません。

正式な定義

ハーネスエンジニアリングとは、以下のことを行うシステムの設計と実装です。

1. 制約（Constrain）: AIエージェントができることを制限する（アーキテクチャの境界、依存関係のルール）。
2. 通知（Inform）: エージェントが何をすべきかを教える（コンテキストエンジニアリング、ドキュメント）。
3. 検証（Verify）: エージェントが正しく実行したかを確認する（テスト、リンティング、CI検証）。
4. 修正（Correct）: エージェントが間違ったときに修正する（フィードバックループ、自己修復メカニズム）。

Martin Fowlerはこれを*「AIエージェントを抑制するために使用できるツールとプラクティス」*と表現していますが、それは単なる安全性以上のものです。優れたハーネスは、エージェントを単に制御するだけでなく、より有能にします。

---

なぜ今、ハーネスエンジニアリングが重要なのか

モデルはコモディティ。ハーネスが参入障壁（モート）。

AI業界が直面している不都合な真実があります。それは、**「基盤となるモデルよりも、その周囲のシステムの方が重要である」**ということです。

LangChainはこれを決定的に証明しました。彼らのコーディングエージェントは、モデルを一切変更することなく、ハーネスを変更するだけでTerminal Bench 2.0のスコアを52.8%から66.5%に向上させ、ランキングを30位圏外からトップ5へと押し上げました。

変更点	具体的な内容	影響
自己検証ループ	完了前のチェックリストミドルウェアを追加	提出前にエラーを捕捉
コンテキストエンジニアリング	起動時にディレクトリ構造をマッピング	エージェントが最初からコードベースを理解
ループ検出	繰り返されるファイル編集を追跡	「無限ループ」を防止
推論サンドイッチ	計画/検証には高度な推論、実装には中程度の推論を使用	時間予算内で品質を向上

同じモデル。異なるハーネス。劇的に優れた結果。

OpenAIによる100万行の証明

OpenAIの実験は、これまでで最も説得力のある証拠です。

• 5ヶ月の開発期間
• 最終製品には100万行以上のコード
• 手動で書かれた行はゼロ — すべての行がCodexエージェントによって生成された
• 人間が作成する場合の約1/10の時間で構築
• 製品には社内のデイリーユーザーと外部のアルファテスターが存在
• 出荷、デプロイ、破壊、修正のすべてがハーネス内のエージェントによって行われる

エンジニアの仕事は？ハーネスの設計、意図の指定、フィードバックの提供です。コードを書くことではありません。

---

ハーネスエンジニアリングの3つの柱

OpenAIのフレームワークは、ハーネスエンジニアリングを3つの主要なカテゴリに分類しています。

1. コンテキストエンジニアリング

コンテキストエンジニアリングは、エージェントが適切なタイミングで適切な情報にアクセスできるようにすることです。

静的コンテキスト:

• リポジトリ内のドキュメント（アーキテクチャ仕様、APIコントラクト、スタイルガイド）
• プロジェクト固有のルールをエンコードした AGENTS.md や CLAUDE.md ファイル
• リンターによって検証された、相互リンクされた設計ドキュメント

動的コンテキスト:

• エージェントがアクセス可能なオブザーバビリティデータ（ログ、メトリクス、トレース）
• エージェント起動時のディレクトリ構造マッピング
• CI/CDパイプラインのステータスとテスト結果

重要なルール: エージェントの視点からは、コンテキスト内でアクセスできないものは存在しません。Googleドキュメント、Slackのスレッド、あるいは人の頭の中にある知識は、システムからは見えません。リポジトリが唯一の真実のソース（Single Source of Truth）でなければなりません。

2. アーキテクチャ制約

これは、ハーネスエンジニアリングが従来のAIプロンプティングと最も大きく異なる点です。エージェントに「良いコードを書いて」と頼む代わりに、良いコードとは何かを機械的に強制します。

依存関係のレイヤリング:

Types → Config → Repo → Service → Runtime → UI

各レイヤーは、その左側にあるレイヤーからのみインポートできます。これは単なる提案ではなく、構造テストとCI検証によって強制されます。

制約強制ツール:

• 決定論的なリンター — 違反を自動的にフラグ立てするカスタムルール
• LLMベースの監査役 — アーキテクチャの準拠性を確認するために他のエージェントのコードをレビューするエージェント
• 構造テスト — ArchUnitのようなものですが、AI生成コード向けのもの
• Pre-commitフック — コードがコミットされる前の自動チェック

なぜ制約が出力を向上させるのか: 逆説的ですが、解決空間を制約することで、エージェントはより生産的になります。何でも生成できる状態では、エージェントは行き止まりを探索してトークンを無駄にします。ハーネスが明確な境界を定義すると、エージェントはより速く正しい解決策に収束します。

3. エントロピー管理（「ガベージコレクション」）

これは最も過小評価されている構成要素です。時間の経過とともに、AI生成のコードベースにはエントロピーが蓄積されます。ドキュメントが現実から乖離し、命名規則がバラバラになり、デッドコードが蓄積されます。

ハーネスエンジニアリングでは、定期的なクリーンアップエージェントでこれに対処します。

• ドキュメント整合性エージェント — ドキュメントが現在のコードと一致しているか検証する
• 制約違反スキャナー — 以前のチェックをすり抜けたコードを見つける
• パターン強制エージェント — 確立されたパターンからの逸脱を特定し、修正する
• 依存関係監査役 — 循環参照や不要な依存関係を追跡し、解決する

これらのエージェントは、毎日、毎週、または特定のイベントをトリガーとして実行され、人間と将来のAIエージェントの両方にとってコードベースを健全な状態に保ちます。

---

実践：ハーネスエンジニアリングの導入方法

OpenAIのアプローチ：人間によるコードゼロ

ハーネスエンジニアリングのためのOpenAIのチーム構造：

役割	従来型	ハーネスエンジニアリング
コードを書く	主要な業務	決して行わない
アーキテクチャ設計	業務の一部	主要な業務
ドキュメント作成	後回しにされがち	重要なインフラ
PRのレビュー	コードレビュー	エージェントの出力とハーネスの有効性のレビュー
デバッグ	コードを読む	エージェントの行動パターンの分析
テスト	テストを書く	エージェントが実行するテスト戦略の設計

Stripeのアプローチ：大規模な「ミニオン」

Stripeの社内コーディングエージェント（Minionsと呼ばれる）は、現在週に1,000件以上のプルリクエストをマージしています。

1. 開発者がSlackにタスクを投稿する
2. Minionがコードを書く
3. MinionがCIをパスさせる
4. MinionがPRを作成する
5. 人間がレビューしてマージする

ステップ1からステップ5の間、開発者の介入はありません。ハーネスが、テストの実行、CI検証、スタイル準拠、ドキュメントの更新など、すべてを処理します。

LangChainのアプローチ：ミドルウェア優先

LangChainは、ハーネスを構成可能なミドルウェアレイヤーとして構築しています。

エージェントへのリクエスト
  → LocalContextMiddleware (コードベースをマッピング)
  → LoopDetectionMiddleware (重複を防止)
  → ReasoningSandwichMiddleware (計算を最適化)
  → PreCompletionChecklistMiddleware (検証を強制)
  → エージェントのレスポンス

各ミドルウェアレイヤーは、コアのエージェントロジックを変更することなく、特定の機能を追加します。このモジュール式のアプローチにより、ハーネスのテストと進化が容易になります。

---

初めてのハーネス構築：実践的フレームワーク

レベル 1：基本ハーネス（個人開発者）

個人プロジェクトでClaude Code、Cursor、またはCodexを使用している場合：

設定すべきこと：

• プロジェクトの規約を記載した CLAUDE.md または .cursorrules ファイル
• リンティングとフォーマットのためのPre-commitフック
• エージェントが自己検証のために実行できるテストスイート
• 一貫した命名規則を持つ明確なディレクトリ構造

セットアップ時間: 1〜2時間 影響: 最も一般的なエージェントのミスを防止

レベル 2：チームハーネス（小規模チーム）

コードベースを共有する3〜10人の開発者チームの場合：

レベル1に追加:

• チーム全体の規約を記載した AGENTS.md
• CIによって強制されるアーキテクチャ制約
• 一般的なタスクのための共有プロンプトテンプレート
• リンターによって検証される「Documentation-as-code」
• エージェント生成PR専用のコードレビューチェックリスト

セットアップ時間: 1〜2日 影響: チーム全体で一貫したエージェントの動作を実現

レベル 3：本番ハーネス（エンジニアリング組織）

数十のエージェントを同時に実行する組織の場合：

レベル2に追加:

• カスタムミドルウェアレイヤー（ループ検出、推論の最適化）
• オブザーバビリティの統合（エージェントがログやメトリクスを読み取る）
• 定期実行されるエントロピー管理エージェント
• ハーネスのバージョン管理とA/Bテスト
• エージェントのパフォーマンス監視ダッシュボード
• エージェントが行き詰まった際のエスカレーションポリシー

セットアップ時間: 1〜2週間 影響: エージェントが自律的なコントリビューターとして機能する

---

ハーネスエンジニアリングでよくある間違い

1. コントロールフローの過剰設計

「コントロールフローを過剰に設計すると、次のモデルアップデートでシステムが壊れます」

モデルは急速に進化します。2024年に複雑なパイプラインを必要とした機能が、今では単一のコンテキストウィンドウのプロンプトで処理できるようになっています。ハーネスは**取り外し可能（Rippable）**に構築してください。モデルが十分に賢くなり、特定の「スマート」なロジックが不要になったら、それを削除できるようにすべきです。

2. ハーネスを静的なものとして扱う

ハーネスはモデルと共に進化する必要があります。新しいモデルのリリースで推論能力が向上した場合、推論最適化ミドルウェアがかえって逆効果になる可能性があります。主要なモデルアップデートのたびに、ハーネスの構成要素をレビューして更新してください。

3. ドキュメントレイヤーの無視

最も効果的なハーネスの改善は、しばしば最も単純なものです。それは、より良いドキュメントです。AGENTS.md が曖昧であれば、エージェントの出力も曖昧になります。エージェントの「グラウンドトゥルース（正解の根拠）」として機能する、正確でマシンリーダブルなドキュメントに投資してください。

4. フィードバックループがない

フィードバックのないハーネスはガイドではなく、檻です。エージェントは、いつ成功し、いつ失敗したかを知る必要があります。以下の機能を組み込んでください。

• タスク完了前の自己検証ステップ
• エージェントワークフローの一部としてのテスト実行
• タスクタイプ別のエージェント成功率のメトリクス

5. 人間専用のドキュメント

アーキテクチャの決定事項が人の頭の中や、エージェントがアクセスできないConfluenceのページにある場合、ハーネスには欠陥があります。エージェントが必要とするものはすべてリポジトリ内になければなりません。

---

ハーネスエンジニアリング vs. 関連概念

概念	範囲	焦点
プロンプトエンジニアリング	単一のやり取り	効果的なプロンプトの作成
コンテキストエンジニアリング	モデルのコンテキストウィンドウ	モデルが見る情報
ハーネスエンジニアリング	エージェントシステム全体	環境、制約、フィードバック、ライフサイクル
エージェントエンジニアリング	エージェントのアーキテクチャ	エージェント内部の設計とルーティング
プラットフォームエンジニアリング	インフラ	デプロイ、スケーリング、運用

ハーネスエンジニアリングはコンテキストエンジニアリングを包含し、プロンプトエンジニアリングの知見を取り入れますが、より高いレベルで機能します。それは単一のやり取りへの入力ではなく、エージェントを信頼できるものにするためのシステム全体に関するものです。

---

これがソフトウェアエンジニアにとって何を意味するか

仕事が変わる

ハーネスエンジニアリングは、ソフトウェアエンジニアの業務における真の進化を象徴しています。

以前	以後
コードを書く	AIがコードを書く環境を設計する
コードをデバッグする	エージェントの動作をデバッグする
コードをレビューする	エージェントの出力とハーネスの有効性をレビューする
テストを書く	テスト戦略を設計する
ドキュメントを維持する	マシンリーダブルなインフラとしてドキュメントを構築する

これはエンジニアの技術力が不要になるという意味ではありません。むしろ、ハーネスエンジニアリングには、より深いアーキテクチャ思考が必要です。自分の絶え間ない介入なしに機能しなければならないシステムを設計しているからです。

重要なスキル

NxCodeでAI駆動の製品を構築してきた経験に基づくと、以下のスキルが重要になります。

1. システム思考 — 制約、フィードバックループ、ドキュメントがどのように相互作用するかを理解する
2. アーキテクチャ設計 — 強制可能で生産的な境界を定義する
3. 仕様作成（Spec Writing） — エージェントが実行できるほど正確に意図を言語化する
4. オブザーバビリティ — エージェントの動作パターンを明らかにするモニタリングを構築する
5. 反復速度 — ハーネスの構成を迅速にテストし、洗練させる

私たちの経験：実務で役立つこと

私たちは、複数のエージェントシステム（Claude Code, Codex, Cursor）を使用してAI駆動のWebアプリケーションを構築してきました。私たちにとって最も大きな違いを生んだパターンは以下の通りです。

• リポジトリ優先のドキュメント: すべてのアーキテクチャの決定、命名規則、デプロイプロセスがリポジトリ内にあります。SlackやGoogleドキュメントには何も残しません。
• 漸進的な制約の構築: 基本的なリンティングから始め、パターンが見えてくるにつれてアーキテクチャの制約を追加します。最初から完璧なハーネスを設計しようとしないでください。
• エージェント固有のレビューチェックリスト: AI生成コードは、人間が書いたコードとは異なる失敗モードを持っています。私たちのレビュープロセスでは、一般的なエージェントのパターン（過度な抽象化、不要なエラーハンドリング、ドキュメントの乖離など）を考慮しています。
• マルチプロバイダーのハーネス設計: 私たちのハーネスは、Claude、GPT、Geminiモデルで動作します。プロバイダーに依存しない設計にすることで、システム全体を再構築することなくモデルを切り替えることができます。

---

まとめ

1. ハーネスエンジニアリングは新しい規律であり、AIエージェントを信頼できるものにするためのシステム（制約、フィードバックループ、ドキュメント、ライフサイクル管理）を設計することです。
2. モデルはコモディティであり、ハーネスが参入障壁である — LangChainは、ハーネスを変更するだけでベンチマークの順位を30位圏外からトップ5に引き上げました。
3. OpenAIは人間によるコードなしで100万行以上を構築した — これは、ハーネスエンジニアリングが本番規模で機能することを証明しています。
4. 3つの柱: コンテキストエンジニアリング、アーキテクチャ制約、エントロピー管理。
5. シンプルに始める: 優れた AGENTS.md とPre-commitフックは、複雑なミドルウェアよりもインパクトがあります。
6. エンジニアの仕事は進化している — コードを書くことから、AIがコードを書く環境を設計することへ。
7. 取り外し可能なハーネスを構築する — モデルが向上したときに過剰設計が仇とならないよう、適応性を保ちましょう。

---

関連リソース

• エージェンティック・ウェブ解説：AGENTS.md、MCP vs A2A — ハーネスエンジニアリングの基盤となるプロトコルレイヤー
• Cursor Cloud Agents：仮想マシン上での自律コーディングガイド — 実践におけるクラウドベースのエージェントハーネス
• Claude Code リモートコントロール：ターミナル引き継ぎガイド — リモートでのエージェントセッション管理
• NxCodeでWebサイトを構築する — マルチプロバイダー・ハーネスアーキテクチャによるAI駆動のWeb開発