**AIエージェント ハーネス設計ガイド（2026年現在）**

「AIエージェント ハーネス設計」とは、単なるプロンプトやツール呼び出しではなく、**Model（知能）＋Harness（制御・検証・安全・永続化のエンジニアリング基盤）**として信頼性・生産性・安全性を確保するシステムを設計することです。

2026年現在、「Harness Engineering」はPrompt Engineering、Context Engineeringに続く第三のパラダイムとして広く認識されています。同じモデルでもハーネスの質で性能が劇的に変わる（例: 同一モデルでGAIAベンチマーク43ポイント向上、LangChainがTerminal Benchで30位→5位、OpenAI Codexチームが人間0行で100万行のプロダクションコード生成）ことが実証されています。[[1]](https://x.com/shao__meng/status/2093228362965651665)

### 1. 基本原則（これを守らないと全部無意味）

- **Ratchet Principle（棘輪原則）**：エージェントが一度犯したミスを「二度と構造的に犯せない」ようにハーネス側で恒久的に修正する（Mitchell Hashimoto由来）。
- **Deterministic First**：可能な限りルール・テスト・スキーマなどの確定性チェックを優先。LLM-as-Judgeは最後に。
- **Bounded Execution**：無限ループを絶対に許さない（リトライ上限3回、トークン/コスト/時間/ツール呼び出し数のハードリミット）。
- **Failure → Test**：本番失敗を即座に回帰テストに変換。
- **Humans steer, Agents execute**：人間はゴール・制約・品質基準・ハーネス設計を担当し、エージェントは実行を担当。

ハーネスが成熟する兆候：ルール追加速度が「毎日5件 → 週1件」に低下する。

### 2. 推奨アーキテクチャ：6層Harness

最も実践的で広く共有されている6層モデルをベースに設計します。[[2]](https://x.com/i/status/2093228362965651665)

1. **Guides層（前馈制御・ルール層）**
- `CLAUDE.md` / `AGENTS.md` / `DOMAIN_RULES.md` などの単一真理源ファイル。
- 内容：硬い実行可能ルールのみ。実失敗にトレース可能にし、日付・根拠を必ず記載。
- 設計ポイント：200行を超えたら定期的に刈り込む（技術的負債化防止）。セッション内の指示よりファイル優先。

2. **Sensors層（検証・フィードバック層）**
- 出力検証機構。
- 優先順位：linter、単体テスト、JSON Schema、型チェック → LLM-as-Judge（高コスト・非確定のため参考値扱い）。
- 設計ポイント：検証失敗時は「部分成功＋理由」を必ず返す。完全な嘘の最終回答より「ここまでできたが失敗」と正直に言う方が価値が高い。

3. **Agentic Loop層（実行ループ）**
- Plan → Execute → Verify → Repair → (Escalate or Continue)の有界ループ。
- 必須実装：各ステップに予算（時間・トークン・コスト・ツール呼び出し数）。超過時は最良の半成品＋説明を返す。
- ミドルウェアとして実装するのがおすすめ（LangGraphのpre/post hooksなど）。

4. **Memory層（状態永続化）**
- モデルは毎回ゼロスタートなので、ハーネスが状態を保証。
- 推奨：ファイルシステム優先（`plan.md`, `decisions.jsonl`, `checkpoint.json`, `current_state/`ディレクトリ）。
- 検証基準：セッションを途中で閉じても、再開時に「どこまでやって、何を決めたか」を完全に復元できること。ベクターDBは補助的に。

5. **Permissions層（安全・境界層）**
- モデルは自分を制約できないため、ハーネスが唯一の信頼境界。
- 4次元で制御：Scope（範囲）、Rate（頻度）、Reversibility（可逆性）、Visibility（可視性）。
- 不可逆操作（本番デプロイ、削除、外部送信）は**人間承認必須**。信頼できる指示と信頼できないデータを厳密に分離（プロンプトインジェクション対策）。

6. **Observability層（可観測性層）**
- 構造化ログ、トレース、コスト帰属、熔断（trip wire）。
- 重要メトリクス：「人間介入なしで検証通過したタスク数」「検証通過あたりのコスト」。単なるトークン数ではない。
- 実装：OpenTelemetry + カスタム `AgentEvent` emitter。

### 3. 全体アーキテクチャ（概念図）

```mermaid
graph TD
subgraph Harness [AI Agent Harness]
Guides[1. Guides
CLAUDE.mdなど] --> Loop
Sensors[2. Sensors
検証レイヤー] --> Loop
Loop[3. Agentic Loop
有界Plan-Act-Verify-Repair] --> Memory
Memory[4. Memory
ファイルベース永続化] --> Permissions
Permissions[5. Permissions
安全境界] --> Observability
Observability[6. Observability
ログ・メトリクス・熔断] --> Loop
end
Model[LLM Model] <--> Loop
External[外部ツール・API
Sandbox] <--> Permissions
Human[Human Approval
Escalation] <--> Permissions
```

### 4. Evaluation Harness（評価ハーネス）の設計

運用ハーネスと密接に連携させます。

- **Regression Suite**：本番で起きた失敗をそのままテストケース化。
- **Capability Suite**：段階的難易度のベンチマーク。
- **End-State Verification**：最終成果物の構造的チェック（「ゲームとして遊べる状態か」「コードがデプロイ可能か」など）を重視。
- **評価フロー**：開発時は詳細トレース表示、検証時は集計スコアのみ返す（HarnessOpt-Bench的な考え方）。
- モデル性能とハーネス性能を分離して測定できるようにする。

### 5. 実装技術おすすめ（2026年現在）

- **コアフレームワーク**：**LangGraph**（状態機械として最強）。カスタムMiddlewareで上記6層を注入しやすい。
- **ルール管理**：Markdownファイル＋専用Loader（優先度・有効期限付き）。
- **Sandbox**：Docker / gVisor / Firecrackerでツール実行を厳密分離。
- **Loop制御**：予算トラッカー + 自動Escalation機構。
- **多剤対応**：サブエージェントは「コンテキストファイアウォール」として使い、共有状態モデルを採用（コンテキスト汚染防止）。
- **ハーネス肥大化対策**（Findy資料参考）：変更容易性を最優先にレイヤー責務を明確化。ルールは「強さの階層」（プロンプト < ガイド < センサー < 環境制約）で管理。[[3]](https://x.com/gota_bara/status/2046794926604931447)

### 6. 7日間MVP構築ロードマップ

- **Day 1-2**：Guidesファイル作成＋実失敗からのルール抽出
- **Day 3-4**：有界Loop + Sensors（テスト優先）
- **Day 5-6**：Memory（チェックポイント）＋ Permissions
- **Day 7**：Observability + 最小Evaluation Harness

その後「1レイヤーずつ、測定可能に、ロールバック可能に」拡張。完成率80%以上＋全センサー通過をゲートにスケール。

### 追加アドバイス

- クリエイティブ領域では「人間に対するハーネス」として設計するケースが多い（完全自律より共同作業支援）。
- ハーネスは**組織固有**の資産。コードベース・失敗履歴・チームの暗黙知が詰まるため、他社から簡単にコピーできない。
- 週次レビュー習慣：「今週の失敗トップ5をどうハーネスに焼き込むか」を必ずやる。

この設計をベースに、あなたのドメイン（コーディング、業務自動化、クリエイティブなど）に合わせてカスタマイズしてください。

具体的な部分（LangGraph実装例、CLAUDE.mdテンプレート、Evaluation Harnessのコード、特定のドメイン向け設計など）が知りたい場合は、詳しく教えてください。すぐに深掘りした設計資料を作成します。