結論：ハーネスはモデル以外の全部#

業界での共通の整理は、次の式になっている¹²。

Agent = Model + Harness

モデルは推論する。ハーネスは、その推論を現実の作業に変える。

モデルは1回呼ぶと、テキストか「このツールをこの引数で呼んで」という宣言を返すだけだ。実際にファイルを読む、シェルを叩く、結果をもう一度モデルに渡す、止めどきを決める、危ない操作を止める。これらは全部モデルの外側、つまりハーネスがやっている。

チャット UI の「履歴を足して、もう一度モデルを呼ぶ」だけの while ループも、最小のハーネスだ²。ハーネス開発とは、このループを本番で壊れにくくするために周辺機能を足していく作業だと言える。

Philipp Schmid は、ハーネスを「長時間タスクを管理するためにモデルを包むインフラ」と定義し、コンピュータに例えている³。

CPU がどれだけ速くても、OS がなければファイル1つ開けない。モデルとハーネスの関係もこれに近い。

何を作らないのか#

まず、混同しやすいものを切り分けておく。

いちばんまぎらわしいのはフレームワークとの違いだ。Schmid の整理では、フレームワークはツールやループの「ビルディングブロック」を提供するもので、ハーネスはそこにプロンプトのプリセット、ツール呼び出しの扱い、ライフサイクルフック、計画・ファイルシステム・サブエージェントの管理までを、設計判断込みで同梱した上位レイヤになる³。Atlan も、フレームワークはプログラミングモデル、ハーネスは本番で回る組み立て済みのシステムだと書いている⁴。

ただし「ハーネス」に厳密な定義はない。Schmid は「フレームワークの上」、LangChain は「モデル以外のすべて」、Databricks は「実行レイヤ」と、指す範囲が少しずつ違う。この記事では、どれにも共通する中核（ループ・ツール・状態・権限・検証）をハーネスとして扱う。

部品一覧：Claude Code で言うとどれか#

MindStudio の整理では、最小構成は while ループ＋ツールレジストリ＋権限チェック で⁵、本番ではその周りに状態・検証・観測が付く。調べた内容を11の部品にまとめ、Claude Code の機能に当てはめるとこうなる。

こうして並べると、Claude Code で「便利な機能」だと思って使っていたものは、ほぼ全部がハーネスの部品だった。Anthropic 自身も Claude Agent SDK を「Claude Code を動かしているエージェントハーネス」と呼び、SDK として切り出している⁶⁷。以下、部品ごとに作るものを見ていく。

1. エージェントループ（心臓部）#

Claude Agent SDK のループは、次の流れになっている⁶。

1. システムプロンプト・ツール定義・会話履歴と一緒に、プロンプトをモデルに渡す
2. モデルが次の行動を決める（テキスト、ツール呼び出し、またはその両方）
3. ハーネスがツールを実行し、結果をモデルに戻す
4. ツール呼び出しのない応答が出るまで 2〜3 を繰り返す
5. 最終結果に、トークン使用量・コスト・セッション ID を付けて返す

Anthropic はこれを gather context → take action → verify work → repeat とも表現している⁷。コーディングエージェントなら「テストを走らせる → 失敗を読む → ファイルを直す → 再テスト」が、ハーネスの回しているものの実体だ。

作るものはこのあたりになる。

• ターン管理（いま何回目か、いつ止めるか）
• 停止条件（成功、予算超過、最大ターン、ユーザーの中断）。SDK では max_turns と max_budget_usd で打ち切れる⁶
• 並列ツール実行。SDK では Read や Grep など読み取り専用のツールは並列に、Edit や Bash など状態を変えるツールは直列に実行する⁶
• ストリーミング（途中経過を UI に出す）

以前、Claude Code・Codex・Cursor をスマホから操作できるかどうかは、エージェントループの置き場所で決まるという記事を書いた。あのとき「どこで回っているか」を問題にしたループが、まさにこの部品だ。

2. ツール実行基盤#

モデルは「このツールをこの引数で呼べ」と宣言するだけで、実際にファイルを読む、コマンドを走らせる、API を叩くのはハーネスの仕事になる¹。Claude Agent SDK が同梱しているツールは、コーディング用ハーネスの典型的なセットだ⁶。

これに加えて、自作のツールや MCP サーバをつなぐ。作るものはこうなる。

• ツールレジストリと JSON スキーマ（名前、説明、引数）
• 実行アダプタ（成功もエラーも、モデルが読める形で返す）
• 大きすぎるツール出力の切り詰めと、ファイルへの退避
• MCP クライアント（認証、ルーティング、遅延ロード）

面白いのは、ツールを増やす方向ではなく減らす方向に進んでいることだ。LangChain は、狭い専用ツールを大量に用意するより、Bash とコード実行を汎用の手段にする流れだと書いている²。Schmid は、Vercel がエージェントのツールを80%削ってステップ数とトークンを減らした例を紹介している³（Vercel 側の一次情報は未確認）。

Claude Code がシェルをどう使っているかは、13,564コマンドを集計した記事で見た。汎用ツール1本でここまでやれるなら、専用ツールを並べる理由は確かに薄い。

3. 権限・ガードレール#

「呼べる」と「実行してよい」は別物だ。ハーネスは、ツールを実行する前に許可の判定を挟む。

Claude Agent SDK の判定は、次の順番で行われる⁸。

1. フック: その場で拒否するか、次に回すかを決める
2. deny ルール: 一致したらブロック。全部許可するモードでも止まる
3. ask ルール: 一致したら人に確認する
4. permission mode: default・acceptEdits・plan・auto・bypassPermissions などのモードに従う
5. allow ルール: 一致したら許可する
6. canUseTool コールバック: ここまでで決まらなければ、実行時に判断する（UI なら承認プロンプトを出す）

Claude Code で Shift+Tab を押して切り替えているあのモードと、settings.json に書いている Bash(npm *) のような許可ルールは、この判定エンジンへの入力だったわけだ。

作るものはこうなる。

• allow / deny / ask のルールエンジン
• 実行時のコールバック
• 削除・メール送信・課金など、取り消せない操作での人間の承認
• ネットワーク隔離やコマンドの許可リスト
• 拒否したことをモデルに返し、別の手を考えさせる仕組み

Databricks は、これがないハーネスはデモにはなるが本番には出せないと書いている¹。

4. コンテキスト管理（ハーネスの主戦場）#

モデルが覚えていられるのは、コンテキストウィンドウの中身だけだ。長いタスクでは窓が埋まり、推論の質が落ちていく（context rot と呼ばれる）¹²。ハーネスは「何を見せ、何を捨て、何をファイルに逃がすか」を決める。

ここで大事なのは、Anthropic が compaction だけでは長時間の作業には足りないと明言していることだ⁹。要約は、次のセッションに曖昧な引き継ぎしか残さない。

これは身に覚えがある。以前、/compact をしたら資料に書くはずだった内容が消えていたという記事を書いた。あれはハーネス側から見ると「compaction の限界を、ファイルへの書き出しで補っていなかった」という話になる。

5. ファイルシステムと永続状態#

チャット履歴だけでは、クラッシュしたあとも、別のセッションでも、複数のエージェントの間でも仕事が続かない。そこでハーネスは、ファイルシステムを作業メモリとして使う²。

• ワークスペース（コード、計画、メモ、途中の成果物）
• セッションの永続化（JSONL への追記と再開）⁵
• 進捗ファイル（例: claude-progress.txt）⁹
• git のコミットをチェックポイントにする⁹
• メモリファイル（MEMORY.md など）

Anthropic の長時間エージェントの実験では、最初に初期化用のエージェントが init.sh・進捗ログ・機能リスト（JSON）・最初の git コミットを用意し、以降のエージェントは「1機能だけ進めて、きれいな状態で終える」ように促された⁹。これはモデルが賢くなったのではなく、ハーネスがセッション間の引き継ぎの形式を決めた例だ。

Claude Code の自動メモリも同じ発想の部品だ。保存先をリポジトリ内に置いた記事では Mac の引っ越しの話として書いたが、ハーネスの目で見ると「記憶をファイルとして外に出しておくと、環境が変わっても仕事が続く」ことの実例になっている。

6. サンドボックス#

Anthropic の設計原則は「エージェントにコンピュータを渡す」だ。ターミナル経由でファイルを探し、書き、lint し、実行し、デバッグできるようにする⁷。OpenAI の Sandbox Agents も、ファイル・コマンド・パッケージ・ポート・スナップショット・再開可能な状態を持つ隔離環境を、エージェントの実行境界として定義している¹⁰。

作るものはこうなる。

• コンテナ・VM・ホストの隔離
• ランタイムやパッケージの事前インストール
• スナップショットと復元
• ブラウザ（E2E の確認、スクリーンショット）
• ポートの公開（プレビューサーバ）

エージェントが書いたコードを手元のマシンで無制限に走らせるのは危ないし、並列に何本も走らせることもできない。サンドボックスは安全のためだけでなく、スケールさせるための部品でもある¹²。

7. 計画と早期終了の防止#

長時間タスクでよくある失敗は2つある⁹。

1. 一度に全部やろうとして途中でコンテキストが尽き、次のセッションが半端な状態から推測で作業を始める
2. 途中までできたのを見て「完成した」と宣言して止まる

ハーネス側の対策はこうなる。

• 初期化のときに機能リストを JSON で書き、全項目を passes: false から始める⁹
• 1セッションで1機能だけ進める⁹
• 完了条件を機械的に判定できる形で定義する（テスト、チェックリスト）
• Ralph loop: モデルが「終わった」と言っても、フックで元のプロンプトを再注入し、完了条件を満たすまで続けさせる²

計画ファイルをファイルシステムに置き、「計画を読み直せ」とリマインダで注入するのもハーネスの仕事だ²。Claude Code のタスクリストや plan mode は、この部品にあたる。

8. サブエージェント#

親エージェントのコンテキストを汚さずに仕事を分ける部品だ²⁷。

• サブエージェントの起動（独立したコンテキスト、絞ったツール）
• 並列の fan-out（調査を複数体に同時に投げる）
• ハンドオフ（専門のエージェントに引き渡す）
• モデルのルーティング（計画は強いモデル、単純作業は安いモデル）
• 結果の集約（親には要約だけ戻す）

Claude Agent SDK の Agent ツールで呼んだサブエージェントは、親のやり取りを見ずに新しい会話から始まり、最終応答だけが親に戻る⁶。親のコンテキストが増えるのはその要約の分だけで、調査の全文ではない。

9. フック#

モデルに任せると揺れる処理を、ハーネスが決定的に差し込むための仕組みだ²¹¹。Claude Agent SDK の代表的なイベントは次のとおり⁶。

「ファイルを編集したら必ずテストを走らせ、失敗したらその出力を次の入力にする」は、モデルの善意に頼るのではなくフックで実装する。フックはエージェントのコンテキストの外で動くので、トークンも消費しない⁶。

10. 検証ループ#

ハーネスの価値の中心は、失敗を次の入力に変えることにある¹⁷。検証にはいくつか種類がある。

• ルールベース: 型チェック、lint、ユニットテスト、JSON スキーマ
• 実行ベース: テストランナー、curl、開発サーバ
• 見た目ベース: ブラウザ操作とスクリーンショット⁷⁹
• LLM as a judge: 文章のトーンなど曖昧な品質。遅くて不安定なので最後の手段⁷

Anthropic の Web アプリ構築の実験では、ユニットテストや curl だけでは「人間のユーザーとして操作したときに動くか」を見落とし、Puppeteer MCP でブラウザから確認させて初めてバグを拾えた⁹。モデルが同じでも、ハーネスに検証の手段を載せるだけで成果が変わる。

前回の記事で Slidev のスライドを PNG に書き出して、エージェント自身に見て直させたのも、この検証ループを自分で組んでいたことになる。

11. 観測・評価#

本番のハーネスでは、何をしたか分からないエージェントは許されない¹。

• トレース（どのツールを、どの引数で呼び、何が返ったか）
• コスト・トークン・レイテンシ
• 失敗の分類（早期終了、ツールの誤用、context rot など）
• 評価セット（代表的なタスクでの回帰テスト）
• 軌跡の保存（次のモデルの学習や、ハーネス改善の材料）

Schmid は「競争優位はプロンプトではなく、ハーネスが記録する軌跡（trajectories）にある」と書いている³。Claude Code のトランスクリプトや、ステータスラインに出している使用量も、この部品の一部だ。

1回の依頼をハーネスの目で分解する#

Claude Agent SDK の公式ドキュメントにある「auth.ts の落ちているテストを直して」という例を、ハーネスの視点で分解するとこうなる⁶。

1. ハーネスがシステムプロンプト・ツール定義・履歴を載せて、モデルを呼ぶ
2. モデルが Bash で npm test を要求する → ハーネスが実行し、失敗3件を返す
3. モデルが Read で auth.ts とテストファイルを要求する → ハーネスが中身を返す
4. モデルが Edit で修正し、npm test の再実行を要求する → ハーネスが編集・実行し、全部通ったことを返す
5. モデルがツール呼び出しのないテキストを返す → ハーネスがループを閉じ、コストとセッション ID を付けて返す

ここでモデルが書いたのは「次に何をしたいか」だけだ。テストの実行、ファイルの読み書き、許可の判定、ターンとコストの管理、メッセージのストリームは、全部ハーネスがやっている。

デモから本番までの段階#

MindStudio は、本番のハーネスに繰り返し出てくる部品として、while ループ・コンテキスト管理・ツールとスキル・サブエージェント管理・組み込みスキル・セッション永続化・システムプロンプトの組み立て・ライフサイクルフック・権限と安全性の9つを挙げている⁵。段階で分けると、目安はこうなる。

「ハーネス開発」という言葉が指しているのは、だいたい社内ツールから本番の層だ。モデルの API を呼ぶだけのラッパではない。

なぜいま「ハーネス」がこんなに言われるのか#

理由は大きく3つある。

作るならこの順番#

公式ドキュメントや解説で繰り返し出てくる順番をまとめると、こうなる³⁷⁹。

1. ループを先に動かす。ツールは少なく、停止条件を必ず付ける
2. 原子的なツールを厚くする。ファイル・シェル・検索を中心にし、専用ツールを増やしすぎない
3. 検証を閉ループにする。テスト・lint・ブラウザの失敗出力を次の入力にする
4. 権限はデフォルト拒否に近づける。必要なものだけ許可する
5. 状態をファイルに逃がす。計画・進捗・git を使い、チャット履歴に全部を持たせない
6. 長くなってきたら compaction とサブエージェントを入れる
7. トレースを見て、足りないツールと余分なツールを見直す

Schmid の助言は短い。巨大な制御フローを書くな。モジュールにして、次のモデルが出たときに昨日の「賢いロジック」を捨てられるようにせよ³。

全部を自作する必要はない#

既存の SDK を自分のアプリに組み込む、ループだけ自作して残りは SDK に任せる、といった選択肢がある⁷。

ただ、全部を自作しないとしても、「どこまでがモデルで、どこからがハーネスか」を理解しておく価値は大きい。エージェントがうまく動かないとき、原因がモデルの能力なのか、ツールや権限、コンテキストの渡し方なのかを切り分けられないと、失敗をモデルのせいにして見当違いの直し方をすることになる。

この分解が役に立ちそうな場面：ローカル LLM 用の小さなハーネス#

冒頭に書いたとおり、Claude Code のようなハーネスを自作して運用する気はない。それでも、この分解が役に立ちそうな場面は1つ思い当たる。ローカル LLM 用に、自分向けのカスタムハーネスを作るときだ。

以前 Ollama のコーディングエージェントは本当に無料かを電気代で計算したとき、ローカルの価値は「無料」ではなく、自分向けに作れる自由さと、LLM 周辺の解像度が上がることにある、という結論になった。ハーネスを自分で組むのは、その両方をいちばん直接に味わえるやり方だ。小さく組むなら、ここまでの部品一覧と順番がそのまま設計図になる。while ループ・少数の原子的なツール・権限チェックの最小構成から始めて、足りなくなった部品だけを足していけばいい。全11部品をそろえる必要はない。

まとめ#

• ハーネスは、モデルの外側で「考える→動く→結果を見る→直す」を回し続ける実行基盤。Agent = Model + Harness で、モデル以外は全部ハーネスの仕事
• 最小構成は while ループ＋ツールレジストリ＋権限チェック。本番ではコンテキスト管理・永続状態・サンドボックス・計画・サブエージェント・フック・検証ループ・観測が付き、全部で11の部品になる
• その部品のほとんどは、Claude Code で普段使っている機能（CLAUDE.md、/compact、hooks、承認プロンプト、自動メモリ、サブエージェント）にそのまま対応している
• 作る順番は、ループ → 原子的なツール → 検証 → 権限 → 状態のファイル化 → compaction とサブエージェント → トレースで見直し。モデルの進化で捨てることになる前提で、モジュールにして作る
• 本格的なハーネスは Anthropic に任せる。この分解を使うとしたら、ローカル LLM 用に最小構成から小さく組むときになる

参考文献#

1. Databricks, What is an AI Agent Harness? https://www.databricks.com/blog/ai-harness
2. LangChain, The Anatomy of an Agent Harness https://www.langchain.com/blog/the-anatomy-of-an-agent-harness
3. Philipp Schmid, The importance of Agent Harness in 2026 https://www.philschmid.de/agent-harness-2026
4. Atlan, How to Build an AI Agent Harness: Step-by-Step Tutorial (2026) https://atlan.com/know/how-to-build-ai-agent-harness/
5. MindStudio, How to Build a Minimal Agent Harness in Python https://www.mindstudio.ai/blog/build-minimal-agent-harness-python-step-by-step
6. Anthropic, Claude Agent SDK: How the agent loop works https://code.claude.com/docs/en/agent-sdk/agent-loop
7. Anthropic, Building agents with the Claude Agent SDK https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk
8. Anthropic, Claude Agent SDK: Configure permissions https://code.claude.com/docs/en/agent-sdk/permissions
9. Anthropic, Effective harnesses for long-running agents https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
10. OpenAI, Sandbox Agents https://developers.openai.com/api/docs/guides/agents/sandboxes
11. Anthropic, Claude Agent SDK: Hooks https://code.claude.com/docs/en/agent-sdk/hooks
12. Anthropic, Harness design for long-running application development https://www.anthropic.com/engineering/harness-design-long-running-apps