
【ハーネスエンジニアリング入門】AIエージェントの品質を実行環境から改善する #516
このブログは、ITエンジニアの筆者がAIインテグレーションの専門性を高めていくための学習用アウトプットです。
開発業務はAI活用が前提になりつつありますが、日々次のような問題に直面しがちです。
・固有のルールを守らせるのが大変
・既存の設計意図を伝えるのが面倒
・テストが実行されてない
・以前の判断や進捗を見失う
・同じ指示でも実行のたびに結果が異なる
これらはプロンプトを工夫したり、より高性能なモデルに切り替えることで改善はします。
一方で、AIエージェントが適切に作業できる環境そのものを設計するというアプローチもあり、それが今回取り上げる「ハーネスエンジニアリング(Harness Engineering)」です。
ハーネスエンジニアリングとは
ハーネスエンジニアリングは、AIエージェントが安定して目的を達成できるよう、周辺の実行環境や制御の仕組みを設計・改善することです。
つまりハーネスとは、LLMそのものではなく、LLMが動作するための周辺システムを指します。
ユーザー
│
│「ユーザー登録APIを実装して」
▼
┌───────────────────────────────┐
│ Harness │
│ │
│ Instructions / Skills │
│ Context / Documentation │
│ Tools / MCP │
│ Permissions / Sandbox │
│ │
│ ┌──────────────┐ │
│ │ LLM │ │
│ │ 推論・判断 │ │
│ └──────────────┘ │
│ │
│ Workflow / State │
│ Hooks / Tests / CI │
│ Logs / Evals │
│ │
└───────────────────────────────┘
│
▼
実装・検証された成果物ハーネスは、AIが判断に必要な情報を提供したり、利用できるツールを制限したり、実装結果を検証したりします。
設計パターン例
いくつかの事例をもとに、設計パターンを紐解いてみました。
指示と知識の管理
AIが開発業務をこなすには、対象プロジェクト固有の情報が必要です。
・アーキテクチャの全体感
・各種設計方針
・その事業特有の制約や事情
これらを毎回チャットで説明するのは面倒すぎます。
そこでハーネスでは、AGENTS.mdやCLAUDE.md、CursorのRulesなどで、プロジェクト固有の指示をファイル管理します。
これにより、前提知識を省いてAIへの指示出しに集中できます。
Progressive Disclosure(段階的開示)
とはいえ、何でもかんでも一つのファイルに詰め込み、全てのコンテキストで全情報を渡すのは非効率です。
AIが要点を掴みにくくなりますし、トークン消費も激しくなります。
そのため【概要→詳細】の順で参照させる Progressive Disclosure(段階的開示) という考え方が有効になります。
例
AGENTS.md
│
├── docs/architecture.md
├── docs/coding-rules.md
└── docs/testing.md上記のように分ければ、architecture (設計)、coding-rules (実装)、testing (テスト)、それぞれの場面に必要な前提知識だけ渡すことができます。
実行フローを作る
開発タスクを一度のLLM呼び出しで完了させるのは難しい場合がほとんどです。結局、色んな直しが発生します。
なので次のような工程に分け、それぞれでLLMを呼び出しても良いです。
要件を理解
↓
既存コードを調査
↓
実装方針を決定
↓
コードを変更
↓
テストを実行
↓
問題があれば修正
↓
完了各工程を明示的に管理することで、どこまで作業が進んだのか、次に何をするべきかを人もAIも把握しやすくなります。
動作を記録し、評価・改善する
より良くしていく、という観点で、例えば次のような指標を計測できます。
・ルール違反の発生数
・作業完了までの試行回数
・トークン消費量
・実行時間
・人間による修正が必要だった回数
ハーネスの導入初期にはオーバーかもですが、運用が安定すると人間の関与が薄くなるので、計測して監視した方が安心感もあります。
OpenAIとAnthropicの実践事例
ハーネスエンジニアリングを理解するうえで、OpenAIとAnthropicの事例は参考になります。
OpenAI:Codexによるソフトウェア開発
OpenAIは2026年2月、Codexを使ってソフトウェア製品を構築した事例を公開しました。公開記事によると、約5か月間で100万行規模のコードベースを構築し、約1,500件のPull Requestをマージしています。
特徴的なのは、
開発者がコードを直接記述するのではなく、
Codexが開発を進められる環境を整備することに注力した
という点です。
① AGENTS.md はドキュメントの目次として利用
AGENTS.md は、AIエージェントが毎回参照するファイルです。
そこに全ての開発ルールをまとめるのではなく、ドキュメントの目次として利用します。詳細な設計資料は別ファイルに分割し、必要に応じて参照する形です。
上記のProgressive Disclosure(段階的開示)ですね。
② アーキテクチャ上の制約を機械的に強制
モジュール間の依存方向や命名規則などについて、カスタムLintや構造テストを実装しているようです。
LLMにルールを守るよう指示するだけでなく、違反を検出できる仕組みを用意する形ですね。
③ 人間よりAIにとっての理解しやすさを意識
具体的には、設計判断や作業計画をリポジトリ内のドキュメントとして管理しているようです。
要は 人間がコードを直接書くことより、エージェントが適切に動ける環境を整備することが重要になる 、という考え方が読み取れます。
参考資料:OpenAI:Harness engineering
Anthropic:長時間動作するエージェントの設計
この事例の面白さは、作業が複数のコンテキストウィンドウにまたがる場合の状態管理です。
例えばあるセッションで途中まで実装しても、次のセッションで状況を正しく理解できなければ、作業の重複や不具合が発生します。
これに対して、次の二種類のエージェントを使う方法を紹介しています。
① Initializer Agent
最初のセッションで、開発環境や機能一覧、進捗管理用のファイルなどを準備します。
② Coding Agent
後続のセッションでは、機能を一つずつ実装し、テストを実行して、Gitと進捗ファイルに作業結果を残します。
Initializer Agent
↓
機能一覧・開発環境・進捗ファイルを作成
↓
Coding Agent(1回目)
↓
実装・テスト・進捗記録
↓
Coding Agent(2回目)
↓
前回の進捗を確認して作業を継続ポイントは、LLMのコンテキストだけに作業状態を依存させないことです。
作業状態をファイルやGitに保存しておくことで、別のセッションでも作業を再開しやすくなります。
参考資料:Anthropic:Effective harnesses for long-running agents
まとめ
ハーネスエンジニアリングの対象は、プロンプトやコンテキストだけではありません。必要な知識の提供、ツールの接続、権限管理、ワークフローの制御、状態の保存、テスト、評価など、幅広い仕組みが含まれます。
特に重要なのは、LLMによる非決定的な判断と、プログラムによる決定論的な制御を適切に組み合わせることです。
AIエージェントの性能を改善するために、「そのエージェントがどのような環境で作業しているのか」に目を向ける、、新しい種類のエンジニアリングで面白いですね。