第3章 — ハーネスの5層モデル
設計図を手に入れる
ミサキがユウキをホワイトボードの前に連れていった。
「ハーネスエンジニアリングの全体像を教える。コーディングエージェントのハーネスは 5つの層 で構成される」
ミサキは図を描き始めた。
「この5つが、エージェントの振る舞いを決めるすべてだ」
第1層: メモリ（Memory）
エージェントが常に知っていることを定義する層。セッションをまたいで持続する知識。
代表的な実装
| 実装 | 説明 | 例 |
|---|---|---|
| CLAUDE.md | プロジェクトルール | コーディング規約、スタック情報 |
| .claude/rules/ | パス限定ルール | テストファイルの書き方 |
| 自動メモリ | AI が自分でメモを取る | ユーザーの好み、過去の修正 |
# CLAUDE.md の例
- TypeScript strict mode を使用
- テストカバレッジ 80% 以上を維持
- API: tRPC、DB: PostgreSQL + Drizzle ORM重要な原則
WARNING
メモリは「助言（Advice）」である。「こうしてほしい」と書いても、AI が必ず従う保証はない。本当に強制したい場合は、上位の層（フックや権限）を使う。
「CLAUDE.md に『rm -rf を使うな』と書いても、AI が無視する可能性がある。でも Hook でブロックすれば、物理的に実行できない。この違いが決定的に重要なの」
第2層: ツール（Tools / MCP）
エージェントが何にアクセスし、何を操作できるかを定義する層。
ビルトインツール
Read— ファイルを読むWrite/Edit— ファイルに書くBash— シェルコマンドを実行するWebSearch/WebFetch— Web を検索・取得する
MCP サーバー
外部ツールとの接続を標準化するプロトコル。
{
"mcpServers": {
"github": {
"command": "gh",
"args": ["mcp"]
},
"database": {
"command": "mcp-server-postgres",
"args": ["--connection-string", "postgresql://..."]
}
}
}設計のポイント
ツールは最小権限の原則で設計する。エージェントに必要なツールだけを渡し、不要なアクセスは与えない。
第3層: 権限（Permissions）
エージェントが何をしていいか、何をしてはいけないかを定義する層。
3つのレベル
| レベル | 意味 | 例 |
|---|---|---|
| Allow | 確認なしで実行可能 | ファイルの読み取り |
| Ask | 実行前にユーザーに確認 | ファイルの書き込み |
| Deny | 絶対に実行不可 | 機密ファイルの読み取り |
{
"permissions": {
"allow": [
"Read",
"Write(src/**)",
"Bash(pnpm test)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force)",
"Read(.env)"
]
}
}第4層: フック（Hooks）
ツール呼び出しの前後に自動実行されるスクリプト。権限が「何ができるか」を決めるのに対し、フックは「実行時に何を強制するか」を決める。
メモリとフックの決定的な違い
INFO
「メモリは助言。フックは法律」——この区別が安全性の鍵。
フックの種類と用途
| フック | タイミング | 代表的な用途 |
|---|---|---|
| PreToolUse | ツール実行前 | 破壊的コマンドのブロック、秘密鍵の検出 |
| PostToolUse | ツール実行後 | 自動 lint/format、Mermaid 検証 |
| Stop | 応答完了時 | セッション引き継ぎ資料の生成 |
| SessionStart | セッション開始時 | 環境チェック、前回の引き継ぎ表示 |
第5層: 観測（Observability）
エージェントが何をしたか、どう振る舞ったかを記録し、後から確認できるようにする層。
なぜ重要か
本番 AI システムにおいて、観測可能性はオプションではなく必須。デバッグ、コスト管理、リスク低減——すべてが観測の上に成り立つ。
記録すべきもの
| 対象 | 内容 |
|---|---|
| メトリクス | トークン使用量、応答時間、成功率 |
| トレース | ツール呼び出しの連鎖、判断の流れ |
| ログ | エージェントの決定内容、エラー情報 |
| 評価 | 出力品質のスコアリング |
| コスト | API 呼び出しの費用追跡 |
業界標準: OpenTelemetry
業界は OpenTelemetry（OTEL） をエージェントのテレメトリデータ収集の標準として収束しつつある。ベンダーロックインを防ぎ、フレームワーク間の相互運用性を確保する。
2つの執行レイヤー
ミサキは最後に、重要な区別を強調した。
「ハーネスにはプロセス内部とプロセス外部の2つの執行レイヤーがある」
| レイヤー | 制御対象 | 具体例 |
|---|---|---|
| プロセス内部 | エージェントが発行できるツール呼び出し | 権限、フック、MCP スコープ |
| プロセス外部 | エージェントが実際に実行できること | OS 権限、コンテナ、ネットワーク |
「たとえばハーネスが『ファイルの書き込みを許可』しても、OS ユーザーにその権限がなければ実行されない。多層防御が大切」
5層の相互作用
各層は独立ではなく、互いに補完し合う:
- メモリが方向を示し、フックが強制する
- 権限がアクセス範囲を決め、ツールが能力を提供する
- 観測がすべてを可視化し、改善のサイクルを回す
ユウキはメモを取り終えて顔を上げた。「5層のうち、どこから始めればいいですか？」
「メモリ（CLAUDE.md）から。一番簡単で、一番効果が大きい。次の章で詳しくやろう」
次の章では、5層モデルの第1層——CLAUDE.md の設計——に踏み込む。