【AI開発】ハーネスエンジニアリング【入門と実践】

最近、AIエージェントを実務に導入する企業が増えていますが「動かしてみるとすぐ脱線する」「コード生成がカオス化する」といった問題が頻発しています。

これらの問題を体系的に解決するために登場したのが ハーネスエンジニアリング です。

この記事は個人的な見解を含んでいます。
また、AIで添削もさせています。
技術進化の速度が著しく、考えや表現がすぐに古くなる可能性がありますので、ご留意頂いた上でご覧ください。
不備不足があればご指摘ください。ご意見や要望もお受けいたします。

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

ハーネスエンジニアリングは、大規模言語モデル（LLM）を中核とするAIエージェントが、 複雑な実務環境において信頼性と一貫性を保ちながら動作し続けるために必要な、周辺環境、制約、およびフィードバックループ全体を設計・構築する技術規律（ルール）です。

2026年初頭にハッシュコープ（HashiCorp）の共同創設者であるミッチェル・ハシモト（Mitchell Hashimoto）や、OpenAIの開発チームによって提唱・定式化され、急速に普及した考え方で、結構出来立てほやほやです（とはいえ、もうAIの世界での数か月、半年の差は結構致命的な変化を及ぼしつつありますね）

ハーネス（Harness）という言葉は、馬具（バグ）のことであり、手綱、鞍、轡（くつわ）などを意味しています。

AIを暴れ馬に例え、手綱で馬を制御しながら正しい方向へ走るということを意図した設計思想です。
※AIに目的（ゴール）だけ与えるのではなく、そのプロセスや制約、フィードバックなどさせるようにし、過程のところもしっかり人が介入してレギュレーションを定めましょうという考えと理解しています。

アーキテクチャの観点では以下のように定義付けられています。
$$Agent = Model + Harness$$
Harness（ハーネス）はモデルの推論能力以外の全てを包含し、例えばツールのインターフェース、メモリ管理、状態の永続化、エラー回復の仕組み、制約の強制や検証ゲートなどを含んでいます。

ハーネスエンジニアリングの背景

AIエージェントが実務レベルで使われ始めた2025〜2026年、従来のアプローチでは限界が見え始めました。

ここで特に深刻だったのが、次の3つの課題です。

• 第一の課題
  長時間にわたるタスク実行における「ドリフト（脱線）」と「エントロピー（不確実さ）」の問題です。
  AIエージェントは、ステップ数が増えるにつれて当初の指示や守るべきルールから徐々に逸脱し、最終的には無意味なループに陥ったり、予期せぬ破壊的な操作を行ったりする傾向があります。
  従来のプロンプトエンジニアリングでは、このような動的な逸脱をリアルタイムで防ぎ、修正することは困難でした。

• 第二の課題
  実務レベルのソフトウェア開発においての信頼性の要求です。
  OpenAIによる内部実験では、Codexを用いた完全自動のソフトウェア開発プロジェクトにおいて、人間がコードを一行も書かずに100万行規模のシステムを構築しようとした際、最大のボトルネックはAIの推論能力ではなく、エージェントが生成したコードの品質を担保し、既存のアーキテクチャとの整合性を保つための「検証インフラ」の欠如であることが判明しました。
  この実験が、エンジニアの仕事は「コードを書くこと」から「エージェントが正しく動ける環境を作ること」へシフトしたきっかけに繋がりました。

• 第三の課題
  組織知の共有と永続化の困難さです。
  つまり、個々の開発者が優れたプロンプトを作成しても、それは属人的なスキルに留まり、チーム全体で再利用可能な資産にはなりにくく、個別のコミュニケーション（Slackなど）での議論や個人の記憶に依存する知識は、AIエージェントにはアクセス不可能です。
  そのため、リポジトリ内の構造化されたドキュメントや、自動化された制約ルールとして知識を「外部化」する必要性があります。

ミッチェル・ハシモトは、自身のAI活用プロセスにおいて、エージェントが失敗するたびにその失敗が二度と起きないような恒久的な修正をエージェントの環境（ハーネス）に組み込むという習慣を形式知化し、これがハーネスエンジニアリングという呼称の普及につながりました。

従来の手法との比較

ハーネスエンジニアリングは、先行する二つの主要な技術規律であるプロンプトエンジニアリングおよびコンテキストエンジニアリングを包含しつつ、その外側にある実行システム全体を統治する次世代の技術規律と位置付けられています。

• プロンプトエンジニアリング（第1世代）は、AIに対する「指示の表現（How to ask）」を最適化する技術であり、主にシングルターンのやり取りにおいて、期待される出力を引き出すことに焦点を当てる
• コンテキストエンジニアリング（第2世代）は、AIが思考する際に「何を見せるか（What to show）」を制御し、RAG（検索拡張生成）やメモリ管理を通じて、適切な情報を適切なタイミングで提供することに主眼を置く
• ハーネスエンジニアリング（第3世代）は、AIが「どのように動作し、どのように制御されるか（How to operate and govern）」を設計する
  イメージとしては、プロンプトが「お願いをすること」であり、コンテキストが「参考資料を提供すること」であるならば、ハーネスは「チェックリスト、マネージャーによるレビュー、および安全プロトコルの既定」するようなものとなります。

各手法の違い

比較項目	プロンプトエンジニアリング	コンテキストエンジニアリング	ハーネスエンジニアリング
主な焦点	意図の精緻化（入力テキストの最適化）	情報の管理（インプット環境の設計）	実行の制御（ランタイムシステムの構築）
中心的な問い	「何を依頼すべきか？」	「何を見せるべきか？」	「どう統治し、完遂させるか？」
主要な成果物	システムプロンプト、Few-shotの例示	RAG、メモリ、セッション履歴	リンター、テスト、制約ファイル、検証ゲート
例え	頭での業務指示	業務マニュアルや地図	管理職（プロセス管理）＋ 安全装置（強制力のある制約）
時間軸とスコープ	単発の対話（Single-turn）	一連のセッション（Multi-turn）	長期間の自律稼働（Multi-session）
失敗への対処	言い回しを変えて再試行する	検索精度や要約の質を向上させる	失敗を検知し自動復旧・修正する
限界点	事実の欠如や実行の脱線を防げない	実行時の判断ミスやループを阻止できない	モデル自体の知能（推論能力）は向上させない

従来のソフトウェアエンジニアリングとハーネスエンジニアリングの役割の変化

従来のソフトウェアエンジニアリングとハーネスエンジニアリング（AI開発）の役割の変化も以下のように変化していると考えられます。

役割の変化	従来のソフトウェアエンジニアリング	ハーネスエンジニアリング
コードの記述	人間が手動で行う主要な業務	エージェントが生成し、人間は書かない
アーキテクチャ設計	業務の一部として行われる	強制可能な境界を定義する中心業務
ドキュメント作成	補助的または後回しにされることが多い	マシンリーダブルな必須インフラ
コードレビュー	人間がコードの行を精査する	エージェントの挙動とハーネスの有効性を評価する
デバッグ	ソースコードを読み、修正する	エージェントの失敗パターンを分析・環境改善する
テスト	個別のテストケースを記述する	エージェントが実行すべきテスト戦略を設計する

ハーネスエンジニアリングの具体的な構築手法と構成要素

効果的なハーネスを構築するためには、単なるコードの集まりではなく、多層的な「制御システム」としてアーキテクチャを設計する必要があります。

1.物理的な制約とガードレールの導入

AIエージェントの行動範囲を「お願い」ではなく「物理的・構造的な制約」で制限する。

• サンドボックス環境の提供： エージェントが操作できる範囲を、隔離されたDockerコンテナや仮想ファイルシステム内に限定する。
  これにより、システム全体に影響を与えることなく、エージェントが自由に試行錯誤できる環境を確保する。
• 決定論的な検証ゲート： リンター（コード解析ツール）、型チェッカー、および単体テストを、CI/CDパイプラインにおける「ハードゲート（失敗すればマージ不可）」として設定する。
  エージェントは、これらの機械的なチェックをすべてパスするまで、タスクの完了を宣言できないように物理的にブロックされる。

2.フィードバックループの自動化

エージェントが失敗を検知し、自律的に修正するための情報を構造化して返す仕組みを構築する。

• エラーメッセージのプロンプト化： 単に「ビルド失敗」と返すのではなく、リンターの指摘箇所、期待される修正案、および関連するコーディング規約をエラーメッセージに含め、それをエージェントへの次の入力として自動的に供給する
• PEV (Plan-Execute-Verify) パターンの採用：
  ・Plan： エージェントに、まず具体的な実行計画と受け入れ基準を記述させる。
  ・Execute： 承認された計画に基づき、一歩ずつツールを呼び出して作業を進める。
  ・Verify： 生成物をテストスイートや別の検証用エージェントによって、計画通りに動作するか多角的にチェックする 。

3. コンテキストの外部化と構造化

エージェントが共有すべき知識を、リポジトリ内のマシンリーダブルなファイルとして永続化する。

• AGENTS.md による規約の強制： プロジェクトの構造、命名規則、使用すべき技術スタック、および回避すべきアンチパターンを AGENTS.md に集約する 。このファイルはエージェントが作業を開始する際に必ず読み取られ、行動の基準となる。
• Map, Not Manual（百科事典ではなく地図）： 指示を一つの巨大なファイルに詰め込むと、トークンの限界や注意力の分散により、重要な制約が無視される 。これを避けるために、AGENTS.md は最小限のインデックスとし、詳細なドキュメントは別ディレクトリ（例：docs/）に配置して、エージェントが必要に応じて読みに行くように誘導する 。

※OpenAIの記事から抜粋（リポジトリ内のナレッジストアのレイアウト）

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

4. メモリと状態の永続化管理

長期間のタスクにおいて「デジタル健忘症」を防ぐための仕組みである。

• 進捗管理ファイルの自動更新： エージェントが現在どのステップにおり、次に何を行うべきかをprogress.md や todo.json といったファイルに書き込ませる 。これにより、システムがクラッシュしたりコンテキストがリセットされたりしても、次のセッションで正確に作業を再開できる。
• セッションのコンパクション（要約）： 長い会話履歴はノイズを増やすため、定期的に過去の履歴を要約し、重要な状態（ステート）だけを残して新しいクリーンなコンテキストでセッションを再開する仕組みを導入する。

ハーネスエンジニアリングに関する高度理解と組織相性

ハーネスエンジニアリングを実務に導入する上で、考慮すべき高度な概念や、組織的なインパクトについても理解しておく必要がります。

ここではハーネスエンジニアリングを実務に導入する際に特に重要となる3つの高度概念を解説します。

• ハーネス可能性（Harnessability）
• エントロピー管理
• 評価ハーネスとの役割分離

ハーネス可能性（Harnessability）とコードの質

すべてのシステムが等しくハーネスを実装できるわけではありません。
Thoughtworksなどは、システムがどれほどエージェントによる制御を受け入れやすいかを示す「ハーネス可能性（Harnessability）」という概念を提唱しています。

• 静的型付けの優位性： TypeScriptやRustのような強力な型システムを持つ言語は、それ自体がハーネスの「センサー（検知器）」として機能し、エージェントの誤りを即座に検知できるため、ハーネス可能性が高い。
• 明確なアーキテクチャ境界： モジュール化が進み、依存関係がクリーンなシステムほど、エージェントは変更の影響範囲を正確に把握でき、自律的なリファクタリングが成功しやすくなる。

エントロピー管理と「ガベージコレクション・エージェント」

AIエージェントによる大量のコード生成は、人間が理解できない複雑なコードの蓄積（AI Slope）を招くリスクがあります。
これに対処するため、ハーネスの一部として「エントロピー管理」を担当するバックグラウンドエージェントを稼働させることが推奨されます。
これらのエージェントは、使われなくなった古いコードの削除、重複するロジックの統合、および古くなったドキュメントの更新を継続的に行い、システムの清浄度を保つ役割を果たします。

評価ハーネス（Evaluation Harness）との混同回避

「エージェント・ハーネス」と「評価ハーネス」で異なる役割を持たせます。

• エージェント・ハーネス（実行用）： 本番環境でエージェントを動かし、目的を達成させるためのランタイムシステム。
• 評価ハーネス（測定用）： 複数のモデルやエージェントの性能を公平に比較・測定するためのベンチマーク用インフラ。
  優れた開発プロセスでは、評価ハーネスによってエージェントの「弱点（失敗しやすいパターン）」を特定し、その弱点を克服するための制約を実行用ハーネスに組み込むという改善サイクルを回すことが重要となります。

「人間の舵取り（Humans Steer, Agents Execute）」

ハーネスエンジニアリングの究極の目的は、人間を細かな作業から解放し、高次の設計と意図の定義に集中させることにあります。
人間は「舵取り（Steer）」を行い、エージェントは「実行（Execute）」する。このパートナーシップにおいて、ハーネスは重要な技術規程になります。ハーネスがあることにより、モデルの性能への信頼ではなく、モデルを取り囲むシステムの堅牢性に対する信頼につながります。

さいごに

AIの進化はすさまじいです。
出来ることが多くなっているということは、それだけ人間が見きれない範囲も大きくなってしまいます。
この状態を、何も手を打たずに目的達成のために闇雲に使っていくと、技術的負債やセキュリティ上のリスクが知らぬ間に内在し、将来の大きな損失を産んでしまう可能性があります。
そうならないよう、規定を作り、正しく付き合うことが自分自身を守りつつ生産性を最大化できると思います。
ただ、これらの規程は「AIだから。人間だから」必要になっているのではなく、パートナーとして共に仕事をする上では必要なレギュレーションであり、AIだろうが人間だろうが必要なことだと考えています。
※人間だって間違えるし、嘘をつく。

去年の今頃では考えられない速度で進化をしていると思いますが、きっとこれでもまだ進化の途中で、来年の今頃もきっと今では想像もつかない世界になっているかもしれませんので、便利だから使う、というだけでなく、きちんとルールを定めて、AIとも信頼関係築きながらじっくりと向き合っていきたいと思います。

最後まで見ていただきありがとうございます。