**AIエージェント ハーネス設計（2026年実務版）**

「モデルではなく、ハーネスが本質」というのが2026年現在のコンセンサスです。モデルはエンジンで、ハーネスが「車全体の設計」です。特に日本コミュニティでは、**Claude Code / Cursor / DeepSeek Harness** などの実務で「任せられるかどうか」のほとんどがハーネス品質で決まることが分かってきています。

以下に、**生産環境で実際に使えるレベルのハーネス設計**をまとめます。

### 1. ハーネスの全体アーキテクチャ

```mermaid
graph TD
subgraph ガバナンスレイヤー [Governance & Policy Layer]
Policy[Policy Engine
許可・禁止ルール]
Guard[Guardrails & Approval Gate]
Audit[Audit & Cost Control]
end

subgraph 制御レイヤー [Orchestration Layer]
Loop[Main Loop Engine
Plan → Act → Observe → Reflect]
Graph[Graph Engine
既知パターンの構造化]
State[State Machine + Checkpoint]
end

subgraph 知能拡張レイヤー [Intelligence Layer]
Memory[Hierarchical Memory
Working / Semantic / Episodic / Procedural]
Tool[Tool & Skill Abstraction
MCP対応]
Reflection[Reflection & Self-Correction]
end

subgraph 実行レイヤー [Execution Layer]
Sandbox[Secure Sandbox
File / Code / API / Browser]
Executor[Action Executor]
end

subgraph 観測レイヤー [Observability Layer]
Trace[Full Trace & Visualization]
Eval[Evaluation & Scoring]
Learning[Failure Pattern Learning]
end

User[ユーザー/タスク] --> Loop
Loop <--> Policy
Loop <--> Memory
Loop <--> Tool
Tool --> Sandbox
Loop --> Reflection
Everything --> Trace & Eval
```

### 2. 各コンポーネントの詳細設計

#### (1) Policy & Governance Layer（最も重要）
- **Positive List（Skills）**：このエージェントが得意とする作業の明示的定義
- **Negative List（Do Not）**：絶対にしてはいけない行動（ファイル削除、外部API無制限呼び出し、機密情報扱いなど）
- **Permission Matrix**：ツール×操作レベル×確認要否をYAMLで定義
- **Approval Gate**：破壊的アクション時はHuman-in-the-Loop or Multi-LLM Consensusを自動挿入
- **Budget & Rate Limit**：タスク単位のコスト上限と自動停止

#### (2) Orchestration Layer（Loop vs Graph）
- **Loop**：探索的・不確実性の高いタスク（新規調査、複雑な要件定義）
- **Graph**：パターンが既知の繰り返し作業（PR作成フロー、テスト実行、ドキュメント更新）
- **動的切り替え**：最初はLoopで探索 → パターンが固まったらGraphにコンパイルして効率化（これが2026年の先進パターン）
- **Checkpointing**：各ステップ終了時に状態を永続化。失敗時は直前のチェックポイントから復旧可能

#### (3) Hierarchical Memory System
- **Working Memory**：直近の会話・思考（短期）
- **Semantic Memory**：RAG（長期知識）
- **Episodic Memory**：過去のタスク実行履歴と結果（何が成功し、何が失敗したか）
- **Procedural Memory**：スキルとベストプラクティス（「この種のタスクはこう構造化せよ」）
- **Retrieval Gate**：不要な記憶をロードしない仕組み（これがないとコンテキスト汚染が起きる）

#### (4) Tool & Sandbox Layer
- MCP（Model Context Protocol）対応を推奨（2026年標準化が進んでいる）
- すべてのツール実行はSandbox経由（E2B, Firecracker, 専用コンテナなど）
- Dry-run機能：破壊的アクションはまずシミュレーションして影響範囲を表示
- ツールの粒度は「小さく明確に」（1ツール1責任）

#### (5) Observability & Evaluation Layer
- 必須ログ項目：
- Thought → Action → Observationの完全トレース
- 各ステップのトークン消費・コスト・所要時間
- 失敗パターンとその原因仮説
- Human Feedback（承認/修正ポイント）
- 自動評価：タスク完了後に「成功度・効率・安全遵守度」を複数LLMでスコアリング
- 失敗パターンは自動的にPolicyにフィードバック（学習ループ）

### 3. 実装時の推奨構成（2026年現在）

**推奨スタック例**
- **Orchestration**: LangGraph（最も成熟）または自前実装（Temporal + TypeScript/Python）
- **Memory**: PGVector + Redis（ワーキングメモリ）+ Episodic Store
- **Policy Engine**: 自前Rule Engine（シンプルなものから始めて徐々に強化）
- **Observability**: OpenTelemetry + 自前ダッシュボード or LangSmith/Phoenix
- **Sandbox**: E2B or 自前セキュアコンテナ
- **Frontend for Control**: シンプルなWeb UI（タスク投入・承認・進捗可視化）

**特に効く設計パターン**
1. 「ハーネスは先に失敗パターンを集めて設計する」 — 実際に動かしてみて死ぬパターンを全部記録し、それを防ぐ仕組みを最初に作る。
2. 「人間が介入するポイントを明確に設計する」 — 完全自律ではなく、適切な場所で人間が承認・方向修正できるようにする。
3. 「ループの終了条件を厳密に定義する」 — 曖昧だと無限ループになる。

### 4. 設計時に考えるべき質問（チェックリスト）

- このエージェントに「何を任せて、何を任せない」のか明確か？
- 失敗したときに人間がすぐに原因を理解できるか？
- 破壊的アクションを本当に実行する前に確認の仕組みはあるか？
- 同じ失敗を2回繰り返さない仕組みはあるか？
- コストが暴走したときに自動停止するか？
- 後から「なぜその判断をしたのか」追跡できるか？

---

この設計をベースに実際に作る場合、まずは**最小ハーネス**（Loop + Policy + Simple Memory + Sandbox + Trace）から始めて、実際にタスクを回しながら強化していくのが最も効果的です。

具体的にどの部分を深掘りしたいですか？

- Policy Engineの詳細設計とYAML例
- Loop Engineの状態遷移図と実装パターン
- Memory階層の具体的な実装
- 企業内導入時のガバナンス設計
- コード生成エージェント特化ハーネス

用途（コード生成、業務自動化、研究、顧客対応など）を教えていただければ、それに最適化した設計に調整します。