ハーネスエンジニアリング入門 — AIエージェントの性能はモデルではなく「周辺設計」で決まる
朱雀氏のポストが、Claude Code や Codex の仕組みを理解するうえで「ハーネス」の概念が重要だと紹介しています。2026 年に入り、AI エージェント開発の焦点は「どのモデルを使うか」から「モデルの周囲をどう設計するか」に移りました。この周辺設計を指す言葉がハーネスエンジニアリングです。
Claude CodeやCodexの仕組みを詳しく理解したい人にはこれがおすすめ。「ハーネス」について詳しく解説してくれている。
ハーネスとは何か
ハーネスとは、AI モデルを囲む運用インフラのことです。Phil Schmid 氏の解説では、コンピュータに例えて次のように整理しています。
| コンピュータ | エージェント |
|---|---|
| CPU | モデル（推論エンジン） |
| RAM | コンテキストウィンドウ（作業メモリ） |
| OS | ハーネス（コンテキスト管理、ツール処理、起動シーケンス） |
| アプリケーション | エージェント（ユーザー固有のロジック） |
モデルが CPU なら、ハーネスは OS です。どれだけ高性能な CPU を積んでも、OS が貧弱では実用的なアプリケーションは動きません。
具体的には、ハーネスは以下の要素を管理します。
- 会話・コンテキスト管理: セッション間の記憶、コンテキストウィンドウの最適化
- ツール呼び出し層: MCP/SDK ツールの提供と制御
- 権限管理: 実行可能な操作の制御
- セッション・ファイルシステム状態: 作業ディレクトリ、Git 状態の管理
- ループ制御・エラーハンドリング: リトライ、ガードレール、検証
- 観測性: ログ、メトリクス、テレメトリ
モデルではなくハーネスが性能を決める
2026 年に入ってから、ハーネスの重要性を示す数値データが相次いで公開されています。
ハーネス変更だけで性能が 10 倍に
ベンチマーク結果によると、ツール形式を変えただけで 15 モデルすべてのスコアが改善しました。最も劇的だったのは Grok Code Fast 1 で、6.7% から 68.3% に跳ね上がり約 10 倍でした。モデルの重みには一切手を加えていません。
同じモデルでもスキャフォールドで倍近い差
Claude Opus 4.5 は、あるスキャフォールドで 42%、別のスキャフォールドで 78% を達成しました。同じモデルでも、ハーネスの設計次第で性能が倍近く変わります。
ツール削減で成功率が劇的に改善
Vercel はエージェントツールの 80% を削除した結果、失敗から成功へ転換しました。ツールは多ければ良いわけではなく、適切に絞り込むことが重要です。
Cursor のトークン効率化
Cursor は遅延ツール読み込みにより、トークン使用量を 46.9% 削減しました。必要なときに必要なツールだけをロードする Progressive Disclosure の考え方です。
各社のハーネス実装
OpenAI Codex: 100 万行のコードを 3 人で
OpenAI のハーネスエンジニアリング記事は、小規模チーム（3 人のエンジニア）が Codex エージェントを活用して約 100 万行のコードを生成し、約 1,500 件の PR を作成・マージした事例を報告しています。
OpenAI が得た 5 つの教訓は以下の通りです。
- 環境設計 > モデル能力: 進捗が遅い原因は AI ではなく環境の未整備だった
- 地図を渡せ: 1,000 ページの説明書ではなく、構造化された地図を提供する
- アーキテクチャ制約を機械的に強制する: 依存関係の方向を構造テストで検証する
- 観測性を統合する: ログ、メトリクス、スクリーンショットでエージェントが自己検証できるようにする
- 段階的フィードバックループ: PR と CI を通じた反復的改善を設計する
特に「地図を渡せ」は重要な教訓です。大量のドキュメントをすべて渡すのではなく、マップ（構造化された概要）、実行計画、デザイン仕様を単一情報源として機械可読形式で管理することが効果的でした。
Anthropic: 長時間稼働エージェントのハーネス
Anthropic の研究では、複数のコンテキストウィンドウにまたがって動作するエージェントの課題と解決策を示しています。
2 種類のエージェントによる分業
| エージェント | 役割 | 実行タイミング |
|---|---|---|
| Initializer Agent | 環境構築、進捗追跡ファイルの作成、初期コミット | 最初に 1 回 |
| Coding Agent | 機能の段階的実装、セッション間の進捗引き継ぎ | 以降繰り返し |
設計上のポイント
- 機能リストを JSON 形式で管理する（Markdown よりもモデルが不適切に変更しにくい）
- 1 セッション 1 機能の段階的アプローチ
- ブラウザ自動化ツールによるエンドツーエンド検証を必須化
- 各セッションの開始時に標準化されたシーケンス（ディレクトリ確認 → 進捗確認 → 機能リスト確認 → 開発サーバー起動 → テスト）を実行
Manus: 6 ヶ月で 5 回の再構築
Manus はハーネスを 6 ヶ月間で 5 回再構築しています。LangChain も「Open Deep Research」を 1 年で 3 回再設計しました。ハーネスは「壊して作り直す」前提で設計するのが現実的なアプローチです。
ハーネスエンジニアリングの設計原則
各社の事例から共通する設計原則をまとめます。
1. シンプルに始める
複雑な制御フローを最初から構築しないことが重要です。堅牢な個別ツール（アトミックツール）を提供し、計画はモデルに任せます。ガードレール、リトライ、検証は後から追加します。
2. 削除可能に設計する
新しいモデルが登場すると、以前は必要だったハーネスの機能が不要になることがあります。複雑なパイプラインが必要だった処理が、2026 年には単一のコンテキストウィンドウで処理可能になるケースも増えています。モジュール構造にしておき、不要になった部品を気軽に外せるようにします。
3. ハーネスがデータセットである
プロンプトの品質ではなく、ハーネスが捉えた「エージェントの行動軌跡」こそが競争優位性になります。どのツールをどの順序で呼び、どこでつまずき、どう回復したかという記録が、次のハーネス改善の材料になります。
Claude Code のハーネスを読み解く
Claude Code 自体が、ハーネスエンジニアリングの実装例です。
コアループ
Claude Code は以下の 3 フェーズを繰り返すエージェントループで動作します。
- コンテキスト収集: ファイル検索、コード読み取り
- アクション実行: コード編集、コマンド実行
- 結果検証: テスト実行、出力確認
各フェーズでツールを使い、その結果が次の判断にフィードバックされます。
ハーネス要素の対応表
| ハーネス要素 | Claude Code での実装 |
|---|---|
| コンテキスト管理 | CLAUDE.md（常時ロード）+ Skills（オンデマンド） |
| ツール呼び出し層 | Read, Edit, Bash, Grep 等のビルトインツール + MCP |
| 権限管理 | settings.json の allow/deny ルール |
| セッション状態 | Git 状態の追跡、ワーキングディレクトリの保持 |
| ループ制御 | auto-compact によるコンテキスト管理 |
| 観測性 | システムプロンプト内の 110 以上の設定文字列 |
CLAUDE.md はハーネスの一部
前の記事で紹介した CLAUDE.md と Skill のレイヤー分離は、まさにハーネスエンジニアリングの実践です。
- CLAUDE.md = ハーネスの「地図」（OpenAI の教訓 2 に対応）
- Skills = ハーネスの「ツールセット」
- .claude/rules/ = ハーネスの「条件付きコンテキスト制御」
OpenAI が「1,000 ページの説明書ではなく地図を渡せ」と言っているのは、CLAUDE.md を 50 行以内に絞り、詳細は参照先に置くという設計と同じ考え方です。
エンジニアの役割の変化
ハーネスエンジニアリングの台頭は、エンジニアの役割を根本的に変えています。
従来: コードを書く → テストする → デプロイする
2026 年: 環境を設計する → 意図を指定する → フィードバックループを構築する
OpenAI のチームは、「エンジニアの主な仕事はもはやコードを書くことではなく、環境を設計し、意図を明確にし、Codex エージェントが信頼性の高い仕事をできるフィードバックループを構築すること」だと述べています。
これは「コードを書かない開発者」という意味ではありません。環境設計、ドキュメント作成、アーキテクチャ制約の定義、テスト戦略の構築といった「メタ作業」が、実装作業よりも重要になっているということです。
関連記事: コンテキスト設計の 3 原則と Bitter Lesson
本記事の姉妹記事として、AIエージェントの勝負所は「モデル性能」ではなく「ハーネス設計」にあるがあります。本記事が「ハーネスとは何か」「各社はどう実装しているか」という入門・事例編であるのに対し、前回記事は設計思想・原則編として、より深い論点を掘り下げています。
2 つの記事の位置づけ
| 観点 | 本記事（入門編） | 前回記事（設計思想編） |
|---|---|---|
| 主な問い | ハーネスとは何か、なぜ重要か | ハーネスをどう設計すべきか |
| 各社の事例 | OpenAI（5 つの教訓）、Anthropic（2 種類のエージェント分業） | Manus（コンテキスト設計の実装詳細）、LangChain |
| 設計原則 | シンプルに始める、削除可能に、データセットとしてのハーネス | Reduce・Offload・Isolate の 3 原則 |
| 理論的背景 | なし | Bitter Lesson（賢く作るほどモデル進化で無駄になる） |
| Claude Code 分析 | ハーネス要素の対応表 | ユーザー操作とハーネス層のマッピング、Mermaid 図による詳細解説 |
本記事で触れなかった重要な論点
前回記事では、本記事では扱いきれなかった以下のテーマを深掘りしています。
Bitter Lesson のパラドックス: ハーネスは重要だが、賢く作り込んではいけないという逆説です。Manus が 6 ヶ月で 5 回再構築した事実は、精巧な設計がモデル進化で陳腐化することを示しています。「シンプルに始める」という本記事の設計原則の背景にある理論的根拠が、前回記事では Bitter Lesson として詳しく解説されています。
コンテキスト管理の 3 原則（Reduce・Offload・Isolate）: 本記事では「コンテキスト管理」をハーネスの要素の 1 つとして紹介しましたが、前回記事ではこれをハーネスの最重要責務として位置づけ、3 つの具体的な手法に分解しています。
| 原則 | 手法 | Claude Code での実装 |
|---|---|---|
| Reduce | 古い情報を要約・圧縮 | auto-compact（自動メッセージ圧縮） |
| Offload | 情報を外部に退避 | CLAUDE.md、docs/、ファイルシステム |
| Isolate | 重い作業をサブエージェントに隔離 | Agent ツール（Explore、Plan 等） |
自律性の設計と承認ポイント: エージェントの自律性をどの程度にするかという設計判断も、前回記事では CNCF の 4 本柱フレームワーク（Golden Paths、Guardrails、Safety Nets、Manual Review）を使って体系的に整理されています。
2 つの記事を合わせて読むと
本記事で「ハーネスとは何か」「なぜ重要か」を理解したうえで、前回記事の「どう設計すべきか」を読むと、全体像が見えてきます。
- 本記事: ハーネスの概念理解 → 各社の事例 → 設計原則の概要
- 前回記事: Bitter Lesson の教訓 → コンテキスト管理の 3 原則 → Claude Code での実践マッピング
まとめ
- ハーネスはモデルを囲む運用インフラ: コンテキスト管理、ツール呼び出し、権限管理、ループ制御、観測性を含む
- 性能はモデルではなくハーネスで決まる: 同じモデルでもハーネス次第で 42% と 78% の差が生まれる
- シンプルに始め、削除可能に設計する: Manus は 6 ヶ月で 5 回再構築している
- 「地図を渡せ」が鍵: 大量のドキュメントではなく、構造化された概要を提供する
- Claude Code 自体がハーネスの実装例: CLAUDE.md、Skills、rules がハーネスの各要素に対応する
- エンジニアの仕事は「環境設計」に: コードを書くことからフィードバックループの構築へ
参考
- 朱雀氏のポスト（X）
- Effective harnesses for long-running agents - Anthropic
- Harness engineering: leveraging Codex in an agent-first world - OpenAI
- The importance of Agent Harness in 2026 - Phil Schmid
- OpenAI Introduces Harness Engineering - InfoQ
- AIエージェントの性能差のキー、ハーネスエンジニアリング - 高橋氏（note）
- The Agent Harness Is the Architecture - DEV Community
- How Claude Code works - Claude Code Docs
- AIエージェントの勝負所は「モデル性能」ではなく「ハーネス設計」にある（姉妹記事）