「エージェントはデモでは完璧に動く。でも本番に出した瞬間に崩れる」——この経験を持つエンジニアが急増している。2026年、AIエージェントは技術的には成熟しつつある。それでも本番稼働率は低いままだ。
なぜか。答えはシンプルだ。モデルが問題ではなく、モデルを動かす環境が問題なのだ。
この記事ではClaude Codeに特化して解説します。ハーネスの概念と5流派の比較は ハーネスエンジニアリングとは何か——5つの流派と設計思想を整理する をご覧ください。
本番で88%が壊れる——3つのハーネス欠陥
エージェントプロジェクトの88%が本番に到達しないという市場データがある。この数字で驚くべきは、失敗の原因がほぼ共通していることだ。
調査によると、エンタープライズAI失敗の65%がハーネス欠陥に由来する。3つのパターンに整理できる。
コンテキスト逸脱"] F --> SM["Schema Misalignment
スキーマ不整合"] F --> SD["State Degradation
状態劣化"] CD --> CD1["長時間タスクで指示を忘れる
同じ処理を繰り返す"] SM --> SM1["ツール引数形式が
実行時に変化する"] SD --> SD1["チェックポイントがなく
途中から再実行できない"] style F fill:#E74C3C,color:#fff style CD fill:#F5A623 style SM fill:#F5A623 style SD fill:#F5A623
Context Drift（コンテキスト逸脱）
長時間タスクでエージェントが指示を「忘れる」現象だ。LLMのアテンション機構は、コンテキスト後半ほど注意が薄れる傾向がある。ツール実行結果が積み重なると、最初に与えた制約や目標が実質的に無視されるようになる。
デモは短いセッションで完結するため、この問題は現れない。本番の長時間タスクで初めて顕在化する。
Schema Misalignment（スキーマ不整合）
ツール定義と実際のAPI呼び出しの間に生じる齟齬だ。開発環境では動いていたツール呼び出しが、本番環境の僅かに異なるAPIレスポンスで壊れる。エージェントは「ツールが失敗した」と認識せず、誤った情報を元に次のステップに進む。
State Degradation（状態劣化）
チェックポイントと再開性の欠如だ。エージェントが5ステップ目で失敗したとき、ゼロから再実行しかできない設計では、コスト・時間・副作用（APIコール、ファイル変更）の三重のペナルティが発生する。
3つの欠陥すべてに共通するのは、デモでは見えないという点だ。短いセッション・理想的なデータ・開発環境という組み合わせが問題を隠す。本番のスケール、ノイジーなデータ、長時間実行が露わにする。ハーネスを本番前に検証する仕組みを最初から組み込む必要がある。
Generator/Evaluator分離——自己評価バイアスを排除する
ハーネス設計で最も即効性の高いパターンが Generator/Evaluator分離 だ。
なぜ自己評価が機能しないか
エージェントに「自分の出力をレビューしてください」と指示すると、ほぼ確実に「良い出力です」と評価する。これは怠慢ではなく、LLMのアーキテクチャ上の特性だ。
生成フェーズで「これが正解だ」とある程度確定した出力を、同じモデルが別の指示で「ダメな部分を探せ」と問われても、最初の確信を覆すほどの懐疑的な評価はしにくい。Anthropicのエンジニアリングチームの実験でも「エージェントは人間の目には明らかに質の低い出力を自信を持って褒める傾向がある」と記録されている。
2エージェント構成
最もシンプルな分離は Generator と Evaluator の2エージェント構成だ。
Generator の指示原則: 前向きに実装する。要件を満たすコードを書く。完成させる。
Evaluator の指示原則: 批判的に評価する。バグ、要件漏れ、エッジケース、パフォーマンス問題を探す。問題がなければ承認する。
このポジションの非対称性が重要だ。同じモデルでも、システムプロンプトの設計次第で出力の傾向は大きく変わる。
3エージェント構成（Planner/Generator/Evaluator）
複雑なタスクには Planner を加えた3構成が有効だ。
依頼"] --> P["Planner
要件を仕様に展開
フェーズ分割"] P --> G["Generator
フェーズごとに実装
ツール実行"] G --> E["Evaluator
Playwright等で
動作確認・テスト"] E -->|"フィードバック"| G E -->|"承認"| O["最終出力"] style P fill:#4A90D9,color:#fff style G fill:#7ED321,color:#fff style E fill:#BD10E0,color:#fff
Planner: 簡素な要件を詳細な仕様に展開する。フェーズ分割し、Generatorが1フェーズずつ処理できるタスクリストを作る。
Generator: フェーズごとに実装を進める。Evaluatorから承認されるまで修正を繰り返す。
Evaluator: Playwright等のブラウザ自動化ツールで動作確認する。Generatorが見逃すラストマイルの問題を捉える。
重要な知見：モデルが改善されるほど、Plannerの必要性は薄れる。Claude Opus 4.6レベルの能力では、以前は必須だったPlannerスプリント構造がなくても十分な計画能力を持つ。Evaluatorはモデルの能力限界付近のタスクで継続的に価値を発揮する。
Generator/Evaluatorの評価コスト
この構成は単一エージェントより約20倍のコストがかかる場合がある。品質とコストのトレードオフとして考えるべきだ。
| 構成 | コスト | 品質 | 適用場面 |
|---|---|---|---|
| 単一エージェント | 1x | 標準 | 単純タスク・試作 |
| Generator + Evaluator | 3〜5x | 高 | 本番機能・重要タスク |
| Planner + Generator + Evaluator | 10〜20x | 最高 | 複雑な長時間タスク |
タスクの重要度と許容コストに応じて構成を選ぶ。すべてのタスクに3エージェント構成が必要なわけではない。
Evaluatorの評価基準設計
Evaluatorに「なんでも指摘してください」という曖昧な指示は機能しない。評価基準を事前に定義することで、Evaluatorの出力が一貫し、Generatorとのやり取りが効率化する。
設計・コードレビュー用のEvaluatorには以下のような評価軸を与える。
- 機能要件の充足: 依頼された機能がすべて実装されているか
- エッジケース: 空入力・最大値・並行処理など境界条件を処理しているか
- エラーハンドリング: 失敗時に適切なフィードバックをユーザーに返しているか
- パフォーマンス: 明らかなボトルネック（N+1クエリ等）がないか
評価軸が明確であるほど、Evaluatorは「どこを見ればいいか」が明確になり、重要な問題を見逃しにくくなる。
ラチェット原則——失敗を永続的制約に変える
Addy OsmaniがAgent Harness Engineeringで命名した「Ratchet Principle（ラチェット原則）」は、ハーネス設計の核心をつく思想だ。
ラチェットは逆回りできない歯車だ。ハーネスの品質も同様に、失敗から学ぶたびに前進し、後退しない仕組みを作る。
実践フロー
1. エージェントにタスクを実行させる
2. 失敗・不具合を観察する
3. 「その失敗が物理的に起きない」ルールをAGENTS.mdに追記する
4. 次回以降、そのクラスの失敗は再発しない
5. 繰り返す
Mitchell Hashimotoが実践しているこのアプローチは、最初から完璧なハーネスを設計しようとしない。実運用の中でハーネスを育てるという考え方だ。
難しい設計から始める必要はない。エージェントに何か作業させて、失敗したら「なぜ失敗したか」をAGENTS.mdに1行追加する。これだけで始められる。特別なアーキテクチャより、この地道な繰り返しの方が現場では機能する。
具体的なルール追記パターン
失敗例とAGENTS.mdへの追記例を示す。
失敗例1: エージェントが git push を誤って実行した
# AGENTS.md への追記
## 禁止操作
- git push は絶対に実行しない。変更はローカルにのみ保存する。
完了後、ユーザーに「git push できる状態です」と報告する。
失敗例2: エージェントが未テストのコードをマージした
# AGENTS.md への追記
## コード変更後の必須手順
1. `npm test` を実行し、全テストがパスすることを確認する
2. テストが1件でも失敗した場合は、マージせずユーザーに報告する
3. 完了基準: テスト全件パス + ユーザー承認
失敗例3: エージェントが既存ファイルを確認せずに新規作成した
# AGENTS.md への追記
## ファイル作成前の確認ルール
- 新規ファイルを作成する前に、同名ファイルの存在を必ずGlobで確認する
- 既存ファイルがある場合は上書き作成ではなく編集を優先する
各ルールは「何をするか・しないか」を具体的に書く。「注意する」「気をつける」という曖昧な記述は避ける。
AGENTS.md/CLAUDE.mdの実践設計
ラチェット原則と表裏一体なのが、ルールファイルの実践的な設計だ。Agentハーネスは魔法ではない。実装例から学ぶ基本構造 でも述べた通り、AGENTS.mdはエージェントの行動を規定する最重要ファイルだ。
60行ルール
AGENTS.mdは60行以下に収める。
LLMはファイルを先頭から処理する。長すぎるファイルは、後半の記述がアテンションの薄い領域に押し込まれる。重要なルールが「書いてあるのに守られない」状態になりやすい。
Addy Osmaniの実践では「本質的な規約のみ。なぜそのルールがあるかの説明は最小限。コマンド例と完了の定義を明記」としている。
記述の優先順位
# AGENTS.md の構造（優先順高→低）
## 必須（上部に配置）
- プロジェクト固有のコマンド（build/test/lintの正確な実行コマンド）
- 絶対禁止事項（本番データへのアクセス禁止等）
- 完了の定義（何をもって「完了」とするか）
## 推奨（中部に配置）
- コードスタイルの要点
- ファイル構造のルール
- 外部APIの扱い方
## 省略可（必要なければ書かない）
- プロジェクトの背景説明
- なぜそのルールがあるかの理由
- ベストプラクティス集
CLAUDE.md vs AGENTS.md の使い分け
| ファイル | 用途 | 永続性 |
|---|---|---|
| CLAUDE.md | Claude Code専用。システムプロンプトとして常に参照 | コンパクション後も保持 |
| AGENTS.md | 標準仕様。複数AIツール共通のルール | エージェントが参照 |
重要なルールはCLAUDE.mdに書く。AGENTS.mdは長いセッションでコンパクション（コンテキスト圧縮）が発生すると内容が削られる可能性がある。CLAUDE.mdはシステムプロンプトとして扱われるため、コンパクション後も確実に参照される。
Context Rotの検出と対策
ハーネスエンジニアリングとは何か でも触れたContext Rotは、長時間タスクの最大の敵だ。具体的な検出方法と対策を整理する。
Context Rotの症状チェックリスト
- 以前に完了したステップを再度実行しようとする
- 最初に指定した制約条件を無視した提案をする
- 「どこまで完了しましたか？」と聞かれたかのような確認をしない
- 同じエラーを繰り返す（修正したはずのエラーが再発する）
- 応答の品質が時間とともに低下する
2つ以上が当てはまれば、Context Rotが始まっている可能性が高い。
外部アーティファクト戦略
最も効果的な対策は、状態をコンテキスト外に書き出すことだ。
# todo.md（タスク進捗の外部化例）
## 完了済み
- [x] データベーススキーマの設計
- [x] ユーザー認証APIの実装
- [x] 単体テスト（全48件パス）
## 進行中
- [ ] フロントエンドフォームとの接続（現在: バリデーション実装中）
## 未着手
- [ ] E2Eテスト
- [ ] ドキュメント更新
このファイルを定期的にエージェントに読み込ませることで、コンテキストが肥大化しても「どこまで完了したか」を正確に把握できる。
Active Context Compression
コンテキストが肥大化してきたら、エージェント自身に圧縮を依頼する手法だ。
# エージェントへの指示例
これまでの会話履歴を要約してください。
以下を含めてください：
- 完了したタスクの一覧
- 現在の状態
- 次に取り組むべきこと
- 重要な決定事項と理由
要約が完了したら、その要約だけを持って新しいセッションを開始します。
この方法でトークン使用量を22.7%削減しつつ、精度を維持できたという実証データがある。
コンテキストリセットのタイミング
| タスク種別 | リセット推奨タイミング |
|---|---|
| コーディング（中規模） | 300〜500コンテキストターン後 |
| 長時間デバッグ | 問題1件解決ごと |
| マルチファイル編集 | ファイルセット（5〜10ファイル）ごと |
| テスト・検証 | フェーズ完了ごと |
リセットを恐れない。新しいコンテキストで始めた方が、劣化したコンテキストを引きずるより品質が高くなる。
ガードレールと権限設計
エージェントが予期しない操作をしないよう、3層のガードレールを設計する。
システムプロンプトでスコープ限定
許可/禁止のスコープ定義"] IL --> A["エージェント
（モデル+ハーネス）"] A --> TL["ツール実行層ガードレール
危険コマンドの許可リスト制御
読み取り専用モードの活用"] TL --> T["ツール実行"] T --> OL["出力層ガードレール
フォーマット検証
機密情報スキャン"] OL --> O["出力"] style IL fill:#4A90D9,color:#fff style TL fill:#7ED321,color:#fff style OL fill:#BD10E0,color:#fff
Claude Codeの権限設定
Claude Codeでは .claude/settings.json でツール権限を細かく制御できる。
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git diff*)",
"Bash(npm test*)",
"Read(*)",
"Edit(*)"
],
"deny": [
"Bash(git push*)",
"Bash(rm -rf*)",
"Bash(sudo*)"
]
}
}
最小権限の原則: エージェントに必要なツールだけを許可する。「必要になったら追加する」より「最初は最小限にして段階的に広げる」方が安全だ。
サンドボックス設計
本番環境への直接アクセスは避ける。エージェントには必ずサンドボックス環境で作業させる。
# 危険な設計（避けるべき）
エージェント → 本番データベース直接アクセス
# 安全な設計（推奨）
エージェント → テスト/ステージング環境 → 人間確認 → 本番反映
エージェントへの指示にも「本番環境の変更は人間の確認後」というルールを明記する。
ハーネスの「厚さ」という設計判断
どれだけのロジックをハーネス側に配置するか——これが「ハーネスの厚さ」という設計軸だ。
（大きな責任）"] TH["ハーネス
（シンプル）"] end subgraph Thick["厚いハーネス"] KM["モデル
（限定的な責任）"] KH["ハーネス
（豊富な制御）"] end Thin -->|"モデル性能向上で移行"| Thick style TM fill:#4A90D9,color:#fff style KH fill:#7ED321,color:#fff
| 薄いハーネス | 厚いハーネス | |
|---|---|---|
| 実装コスト | 低 | 高 |
| モデル依存度 | 高 | 低 |
| 制御の細かさ | 低 | 高 |
| 適用場面 | 高性能モデル・シンプルタスク | 重要タスク・制約が多い環境 |
モデルが改善されるほど薄くできるのがこの軸の特徴だ。Claude Opus 4.6以前は必要だったPlannerスプリント構造が、同モデルでは不要になったというのが典型例だ。モデル更新のたびにハーネスを見直し、不必要に厚くなっていないかチェックする。
新しいプロジェクトでは「できるだけ薄く始める」ことを推奨する。エージェントを実際に動かして失敗パターンが見えてから、必要な厚みを加える。最初から厚く設計しても、実際の失敗モードとズレる可能性が高い。
オブザービリティ——ハーネスを可視化する
ハーネスを設計しても、エージェントが実際にどう動いているかを観察できなければ改善できない。オブザービリティ（可観測性）はハーネス設計の最終層だ。
記録すべき3つのログ
ツール呼び出しログ: エージェントがどのツールを何回呼び出したか、引数と戻り値を記録する。Context Driftの検出（同じツールを繰り返し呼ぶ）とコスト分析に使える。
判断ログ: エージェントがどんな理由で判断を下したかを記録する。Claude Codeでは拡張思考（extended thinking）を有効にすると、判断プロセスが可視化される。デバッグと改善に直結する。
エラーログ: 失敗したツール呼び出し、リトライ回数、最終的なエラーメッセージを記録する。これがラチェット原則のインプットになる——エラーパターンを見つけてAGENTS.mdに反映する。
「成功は沈黙、失敗は饒舌に」
Addy Osmaniが提唱する設計原則だ。エージェントが正常に動いているときは余分な出力を減らし、問題が発生したときは即座に詳細なエラー情報を出力する。この非対称なフィードバック設計により、ノイズを減らしながら問題の早期発見ができる。
# AGENTS.md へのオブザービリティルール
## レポートのルール
- 正常完了時: 「完了: [実行内容の要約]」の1行のみ
- エラー発生時: エラーメッセージ・試みた手順・失敗の原因を詳述する
- 不確実な場合: 推測ではなく「不明です。確認が必要です」と明示する
コスト監視
トークン使用量の急増は、Context Rotやエラーループの早期警告だ。通常の2〜3倍のトークンを消費するセッションには、必ず問題が潜んでいる。
本番移行前チェックリスト
以上の内容を踏まえ、本番移行前の確認事項をまとめる。
ハーネス欠陥の対策確認
- Context Drift対策: 重要なルールがCLAUDE.mdに記述されているか
- Context Drift対策: 長時間タスク用の外部アーティファクト（todo.md等）があるか
- Schema Misalignment対策: ツール呼び出しのスキーマを本番APIで検証したか
- State Degradation対策: チェックポイントと再開の仕組みがあるか
評価設計の確認
- 単一エージェントのリスク: 自己評価でなく外部評価があるか
- Evaluatorの設定: 懐疑的な視点を持つよう明示的に指示しているか
- 評価基準: 何をもって「承認」とするか定義されているか
ラチェット原則の適用
- AGENTS.md存在: プロジェクトルートまたは.claudeにAGENTS.mdがあるか
- 60行以内: AGENTS.mdが適切な長さか
- 禁止事項の明記: 危険な操作が明示的に禁止されているか
- 完了定義: 「タスク完了」の定義がAGENTS.mdに書かれているか
権限・安全性の確認
- 最小権限: エージェントに必要最小限のツール権限のみ付与しているか
- サンドボックス: 本番環境への直接アクセスをブロックしているか
- 危険コマンドの制限: rm -rf、git push等の危険操作が制限されているか
運用準備の確認
- コスト監視: トークン使用量のアラートを設定したか
- ログ: エージェントの行動ログを記録する仕組みがあるか
- ロールバック: エージェントの変更を元に戻す手順があるか
ハーネス設計は「モデルをラップする面倒な作業」ではない。エージェントが持つ能力を実際の価値に変換するエンジニアリングだ。
Addy Osmaniが言う通り、「それなりのモデルと優れたハーネスは、優れたモデルとダメなハーネスに勝る」。モデルの比較・選定より先に、ハーネスの設計に投資する価値がある。
実装パターンの詳細については Agentハーネスは魔法ではない。実装例から学ぶ基本構造 も合わせて参照してほしい。
参照ソース
- Harness design for long-running application development - Anthropic Engineering
- Harness engineering for coding agents - Martin Fowler
- Agent Harness Engineering - Addy Osmani
- The Anatomy of an Agent Harness - Avi Chawla
- Agent Harness: 12 Agentic Harness Patterns from Claude Code - Medium
- awesome-harness-engineering - GitHub
