ハーネスエンジニアリング完全ガイド：AIエージェントが働ける環境を設計する

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

ハーネスエンジニアリングとは、モデルがエージェントとして仕事を進めるための実行環境、指示、ツール、権限、状態管理、検証、観測可能性を設計することです。

Anthropicは、エージェントハーネスを「モデルが入力を処理し、ツール呼び出しを調整し、結果を返せるようにするシステム」と説明しています。OpenAIのCodexチームは、モデルそのものよりも、エージェントが検査・検証・修正できる環境とフィードバックループへ投資しました。

ハーネスは「長い指示書」ではありません。エージェントが正しい行動を取り、失敗を検知し、安全に止まれる仕組み全体です。

Model・Agent・Harnessの関係

Agent system ├─ Model: 推論と生成 └─ Harness ├─ Instructions ├─ Tools ├─ Permissions ├─ Runtime ├─ State ├─ Evaluation └─ Observability

同じモデルでもハーネスが変われば、達成できる仕事、失敗率、費用、安全性が変わります。

Prompt・Context・Harness・Loop・Graphの違い

領域	主な対象	代表的な成果物
Prompt Engineering	指示の内容と表現	プロンプト、例、出力形式
Context Engineering	推論時に見せる情報	RAG、メモリ、履歴、ツール定義
Harness Engineering	1回の実行を支える環境	AGENTS.md、CLI、権限、テスト、サンドボックス
Loop Engineering	反復と停止	評価、再試行、予算、エスカレーション
Graph Engineering	複数経路の制御	ノード、エッジ、分岐、並列、合流

ハーネスは1回の実行を成立させます。継続的に回す制御はループ、複雑な経路はグラフで扱います。

ハーネスの7要素

1. Instructions：指示

プロジェクトの目的、アーキテクチャ、規約、禁止事項、基本コマンド、完了条件を伝えます。

AGENTS.mdやCLAUDE.mdは百科事典ではなく、エージェントが最初に読む短い入口として使います。詳細は正本となる仕様・設計・運用文書へ分けます。最適な行数に普遍的な固定値はありません。重複を避け、現行の仕事に必要な情報だけを残します。

2. Tools：ツール

ファイル操作、検索、シェル、ブラウザ、テスト、APIなど、仕事に必要な行動手段を与えます。

良いツールは次を備えます。

• 名前と説明から用途が分かる
• 入力スキーマが狭く検証可能
• 成功と失敗を区別できる
• 出力が簡潔で次の判断に使える
• 副作用と権限が明示されている

3. Environment：実行環境

依存関係、ビルド、テスト、ローカルデータ、サンドボックスを再現可能にします。エージェントが毎回セットアップ方法を推測する状態を避けます。

OpenAIの事例では、コード、テスト、CI、ドキュメント、観測ツールを同じリポジトリでエージェントが検査・変更できる形へ寄せました。

4. Permissions：権限

読み取り、書き込み、ネットワーク、外部送信、本番操作を分けます。

• 最小権限を既定にする
• 不可逆操作は承認を要求する
• 秘密情報をコンテキストへ入れない
• 許可範囲を実行環境で強制する

文章で禁止するだけでなく、サンドボックス、ポリシー、Hook、CIなどで機械的に制御します。

5. State：状態

長時間タスクでは、会話履歴の外に進捗、タスク一覧、成果物、検証結果、再開点を保存します。

Anthropicの長時間エージェントでは、初期化役が環境、機能一覧、進捗ファイルを作り、後続の実装役が1機能ずつ進めてGit履歴と進捗を残しました。これは1つの有効なパターンであり、すべてのタスクの固定解ではありません。

6. Evaluation：検証

モデルの自己申告ではなく、実環境の結果を確認します。

• フォーマット、型、静的解析
• 単体・統合・E2Eテスト
• スキーマとデータ整合性
• セキュリティ検査
• 独立した評価エージェント
• 人間レビュー

検証器は、エージェントが修正に使える具体的な失敗情報を返します。

7. Observability：観測可能性

実行した操作、状態遷移、ツールエラー、変更差分、費用、停止理由を追跡します。思考過程全文ではなく、再現と監査に必要なイベントと証拠を記録します。

OpenAIの事例から学べること

OpenAIは2025年8月から約5か月、Codexがすべてのコードを書く内部プロダクト開発を実施しました。2026年2月の公開記事では、約100万行規模、人間による手書きコード0行、従来見積もりの約10分の1の期間という実験結果を報告しています。

重要なのは数値の一般化ではなく、チームが行った環境設計です。

• AGENTS.mdを詳細文書への入口にした
• アーキテクチャ境界をカスタムlintと構造テストで強制した
• ログ、アプリ状態、テストをエージェント自身が確認できるようにした
• 人間は意図と判断を担当し、エージェントは実装を担当した
• 失敗を次のルール・ツール・検証へ反映した

これはOpenAIの特定チームによる自己報告であり、他組織でも同じ速度や規模を再現できる保証ではありません。

Anthropicの事例から学べること

Anthropicは長時間エージェントについて、次のパターンを公開しています。

複数セッションをつなぐ

• 最初のセッションで環境とタスク一覧を作る
• 1回に1つの機能へ集中する
• Git履歴と進捗ファイルで次のセッションへ引き継ぐ
• E2Eテストで実際の動作を確認する

Planner・Generator・Evaluator

2026年3月の実験では、計画、生成、評価を分けた構成が、単一エージェントより高品質なアプリを生成しました。一方で実験例では、単一エージェントが20分・9ドル、フルハーネスが6時間・200ドルと大きなコスト差も報告されています。

モデル進化に合わせて簡素化する

ハーネスの各部品は「モデルが単独ではできない」という仮定を持ちます。モデルが改善すると、以前必要だった細かな分割や評価頻度が不要になることがあります。Anthropicは、部品を1つずつ外して性能への影響を確認する方法を勧めています。

フィードフォワードとフィードバック

フィードフォワード：失敗前に導く

• 指示ファイル
• アーキテクチャルール
• 許可ツール
• スキーマ
• テンプレート
• 権限制御

フィードバック：実行後に修正する

• テスト
• lint・型チェック
• 実行ログ
• E2E確認
• 評価エージェント
• 人間レビュー

どちらか一方では不十分です。説明だけではルール違反を防げず、検証だけでは修正コストが増えます。

導入手順

Step 1：1つの仕事を選ぶ

リポジトリ全体を自律化せず、明確な完了条件を持つ小さな仕事から始めます。

Step 2：実行環境を再現可能にする

セットアップ、開発サーバー、テスト、ビルドを短いコマンドで実行できるようにします。

Step 3：入口となる指示を作る

目的、正本、基本コマンド、禁止事項、完了条件を記載します。詳細は既存文書へリンクします。

Step 4：権限と副作用を分ける

読み取り、ローカル変更、外部書き込み、本番反映に境界を設けます。

Step 5：決定論的な検証を先に置く

型、テスト、スキーマ、リンクなど機械判定できるものから自動化します。

Step 6：状態と再開点を外部化する

長時間化する場合だけ、進捗、タスク一覧、チェックポイントを追加します。

Step 7：観測して最小限の部品を足す

実際の失敗に対応するルール、ツール、評価器だけを追加します。

失敗しやすい設計

指示ファイルを長くし続ける

失敗のたびに文章を足すと、重複や矛盾が増えます。機械検証できる規則はlintやテストへ移します。

すべてをモデル判断にする

許可判定、状態遷移、スキーマ検証など、コードで決められる部分は決定論的に実装します。

評価器を増やせば安全だと考える

評価器も誤り、費用も増やします。タスク難度とリスクに応じて使い、機械的な証拠を優先します。

ツールを無制限に与える

選択肢、権限、攻撃面、コンテキスト消費が増えます。必要なツールを必要なタイミングだけ公開します。

モデル更新後も同じ制約を残す

古い回避策が新しいモデルの能力を妨げることがあります。評価を固定してハーネスを定期的に簡素化します。

成熟度の目安

段階	状態
1. Manual	人間が毎回指示・確認する
2. Guided	指示ファイルと基本コマンドがある
3. Verified	型・テスト・CIで成果を検証する
4. Durable	状態保存と再開ができる
5. Controlled	権限・承認・観測・停止条件が統合される

最上位を目指す必要はありません。仕事の頻度、リスク、失敗コストに見合う段階を選びます。

次に読む記事

• AGENTS.md / CLAUDE.md設計
• CI/CDガードレール
• 長時間実行エージェント
• ループエンジニアリング完全ガイド
• グラフエンジニアリング完全ガイド

参考資料

• Harness engineering: leveraging Codex in an agent-first world（OpenAI）
• Demystifying evals for AI agents（Anthropic）
• Effective harnesses for long-running agents（Anthropic）
• Harness design for long-running application development（Anthropic）
• Building Effective AI Agents（Anthropic）
• ハーネスエンジニアリングとは（Findy Team+）