Claude Code エージェントハーネス：アーキテクチャ解説

自分でツール呼び出しの仕組みを作っていたとき、同じ問いに何度もぶつかった：なぜプロンプトよりも「配線」のほうがずっと難しく感じるのか？

モデル部分はすぐ理解できた。でも、モデルに実際に「何かをさせる」必要が出た途端——ファイルを読む、シェルコマンドを実行する、外部サービスと通信する——あらゆる意思決定が何かを壊しかねないように感じられた。パーミッション境界。コンテキスト上限。ツールのディスパッチ。

そして2026年3月下旬、Claude Codeのソースコードがバージョン2.1.88のnpmソースマップを通じて偶然公開された。50万行を超えるTypeScriptが、数時間以内にミラーされた。Anthropicはパッケージングミスだったと認め——顧客データへの影響はなく——DMCAテイクダウンの手続きを始めた。

しかしアーキテクチャは公知の知識となった。そして明らかになったのは、モデルではなくハーネスだった。

情報源についての注記：ここで述べる内容は、コミュニティによる分析、オープンソースの再現実装、Anthropicの公開ドキュメントおよびエンジニアリングブログに基づいている——リークされたコード自体ではない。不確かな詳細には注記を付けている。

エージェントハーネスとは何か？

定義とエージェントシステムにおける役割

エージェントハーネスとは、言語モデルと現実世界の間にあるすべてのものだ。モデルはテキストを生成する。ハーネスは、そのテキストが何に触れられるかを決める。

AnthropicのClaude Codeドキュメントにはこう直接書かれている：Claude Codeは「言語モデルを有能なコーディングエージェントに変えるツール、コンテキスト管理、実行環境を提供する」。モデルが推論し、ハーネスが行動する。

エージェントがファイルを読もうとするとき、ハーネスはその読み取りが許可されているか、結果をどう扱うか、次のプロンプトにどれだけの応答が収まるかを決める。モデルがファイルシステムに直接触れることはない。

なぜプロダクション環境でハーネス設計が重要なのか

ほとんどのエージェントデモはこの部分を省く。モデルが関数を呼び出し、結果を受け取り、別の関数を呼び出す。綺麗に見える。しかし実際のコードベースで45分間動かすと、静かに崩壊していく——コンテキストがオーバーフローし、パーミッションが緩すぎたり煩わしすぎたりし、モデルが知らないうちにツールの結果が切り捨てられる。

Anthropicのエンジニアリングチームはこう書いている：複数のコンテキストウィンドウにわたってループを実行するフロンティアモデルでも、よく設計されたハーネスなしではパフォーマンスが低下する。エージェントは一度に多くをやろうとしすぎたり、作業が終わっていないのに完了と宣言したりする。ハーネスはその傾向に構造を課す。

Claude Codeのツールサーフェス

コアツールカテゴリ

公式Claude Codeドキュメントとパブリックな分析に基づくと、Claude Codeはおよそ19のパーミッションゲート付きツールを公開している。主なカテゴリ：ファイルの読み書き、シェル実行（Bash）、Git操作、ウェブフェッチ、ノートブック編集、MCPツール呼び出し。LSP統合、サブエージェント生成、内部調整ツールを含めると、40近くになるとコミュニティ分析は示唆している。

各ツールは独立してサンドボックス化されている。「エージェントがファイルシステムにアクセスできる」ではなく——「エージェントはReadツールを使うことができ、Readは実行前にルールパイプラインをチェックする独自のパーミッションゲートを持つ」という構造だ。

ツールの登録とディスパッチの仕組み

モデルが何を試みるかを決める。ツールシステムが何が許可されるかを決める。アーキテクチャ的に分離されている。

すべてのツール呼び出しは、実行前にパーミッションチェックを通過する。コミュニティの詳細分析では、deny/ask/allowのルールをその順番で評価するコア関数が記述されている——denyが常に優先される。三つの結果がある：サイレントに実行、ユーザーへのプロンプト、またはブロック。

侵害されたモデルが説得力を持って安全チェックをバイパスすることはできない。ハーネスはモデルの主張を気にしない。ルールはルールだ。

パーミッションの階層

Claude Codeのパーミッションモデルは、複数のコミュニティアナリストによっておおよそ三段階の階層として説明されている：

第1層——自動承認：読み取り専用または本質的に安全なアクション。ファイルの読み取り、テキスト検索、コードナビゲーション。状態を変更しないため、中断なく実行される。

第2層——確認を求める：制御された方法で状態を変更するアクション。ファイルの編集、特定のシェルコマンド。2026年3月に導入されたオートモードでは、Sonnet 4.6上で動作するバックグラウンド分類器が、確認なしに進められるかを評価する。分類器はユーザーのリクエストとツール呼び出しを見るが、モデルの散文は見ない——モデルがゲートをうまく丸め込めないようにするための意図的な設計選択だ。 第3層——明示的な承認が必要またはブロック：高リスクな操作。システム状態を予測不可能に変更する可能性のあるシェルコマンド、作業ディレクトリ外の操作、データ漏洩のように見えるすべてのもの。

注意点：三段階のフレームワークはコミュニティ分析から来ており、Anthropicの公式ドキュメントではない。公式システムはallow/ask/denyルールと六つのパーミッションモード（default、acceptEdits、plan、auto、dontAsk、bypassPermissions）を使用する。「三段階」は有用なメンタルモデルだが、単純化だ。

セッションとコンテキスト管理

Claude Codeのセッション状態追跡の仕組み

Claude Codeはセッション全体でコンテキストを蓄積する——読み取られたファイル、実行されたコマンド、grep結果、diff、エラー出力。それらすべてが一つの成長するプロンプトに積み上がる。各メッセージがある程度独立しているチャットインターフェイスとは異なり、Claude Codeのセッションは継続的な作業記憶だ。

セッションはローカルに保存される。各メッセージ、ツール使用、結果が保存され、巻き戻し、再開、フォークが可能になる。コード変更の前に、ハーネスは影響を受けるファイルのスナップショットを撮るので、元に戻すことができる。

出力の切り捨てとトークンコストの処理

大きなツール出力は本物の問題だ。Claude CodeはMCPツール出力のデフォルト最大値を25,000トークンに設定し、10,000トークンで警告を出す。サーバー作者はツールにアノテーションを付けてより大きな結果（最大500,000文字）を許可でき、それらはコンテキストに保持されるのではなくディスクに永続化される。

これは、ツール結果が切り捨てられてエージェントが静かに情報を見失うまで気づかないたぐいのものだ。ディスクベースのフォールバック付きの明示的で設定可能な制限——取り入れる価値がある。

コンパクション動作

理解する前にこれに手こずった。トークン使用量がコンテキストウィンドウの約98%に達すると、Claude Codeは自動コンパクションを行う：スペースを確保するために以前の履歴を要約する。重要なメタデータは保持される。画像とPDFは削除される。

厄介な点：コンパクションは重要な詳細を失う可能性がある。実践的な解決策：重要なものはすべてCLAUDE.mdに記載する。ハーネスは毎ターンそれを再読する。

Anthropicのハーネス設計に関する研究では、新しいエージェントインスタンスがハンドオフアーティファクトから引き継ぐ完全なコンテキストリセットが、長時間セッションではコンパクションよりもうまくいくことがあると分かっている。オーケストレーションの複雑さは増すが、コンテキストの忠実度は向上する。

MCP統合レイヤー

Claude CodeがMCPサーバーに接続する方法

MCP（Model Context Protocol）はAIツールを外部サービスに接続するためのオープン標準だ。Claude Codeは三つのトランスポートモードをサポートする：HTTP（リモートサーバーに推奨）、stdio（ローカルプロセス用）、SSE。

サーバーの追加はコマンド一つ：claude mcp add server-name --transport http "URL"。その後、サーバーのツールはセッション内で呼び出し可能なツールとして表示され、組み込みツールと同じパーミッションパイプラインに従う。

ツール検索と認証フロー

感銘を受けた一つの詳細：ツール検索。MCPサーバーを接続する際、Claude Codeはすべてのツールスキーマを最初からコンテキストに読み込まない。セッション開始時にはツールの名前だけを読み込み、タスクが実際にそれらを必要とするときに検索メカニズムを使って関連するツールを見つける。Claudeが使うツールだけがコンテキストに入る。

これによってMCPのオーバーヘッドを低く保てる。認証フローはサーバーによる——OAuth、APIキー、ヘッダー。Claude Codeは新しいMCPサーバーに対してユーザーの明示的な承認を要求する。

プロダクション対応済みと進化中のもの

MCP統合は機能しており、活発に使用されている。ただし知っておく価値のある実用的な制限がいくつかある：

推奨される上限はアクティブMCPサーバー5〜6個程度で、それぞれがサブプロセスを起動するためだ。ツール検索はコンテキストのオーバーヘッドを助けるが、それを超えるとレイテンシが忍び込む。 大きなMCPレスポンスには慎重な処理が必要だ。 25Kトークンのデフォルト上限はほとんどのユースケースで機能するが、データベーススキーマには窮屈になる。ディスクへの永続化フォールバックは助けになるが、モデルはコンテキスト内で完全な結果ではなく参照だけを得る。

コミュニティ製のMCPサーバーは品質にばらつきがある。Anthropicのドキュメントはサードパーティサーバーがプロンプトインジェクションの経路になりうると明示的に指摘している。パーミッションシステムは助けになるが、信頼はあなた次第だ。

構築者へのレッスン

このアーキテクチャがプロダクショングレードのエージェントシステムについて示すもの

Claude Codeの設計から一般化できると思うパターンをいくつか：

推論とパーミッション強制を分離する。 モデルが何をしたいかを決める。別のシステムが許可されるかどうかを決める。ジェイルブレイクされたモデルは安全チェックをオーバーライドできない。文字通り別のコードパスだからだ。

コンテキスト管理を明示的にする。 コンパクション、切り捨て制限、ツール検索、ディスク永続化——これらはすべてモデルが何を見るかを積極的に管理するメカニズムだ。ほとんどの趣味のエージェント構築はコンテキストを底なしの袋として扱う。そうではない。

セッション継続性を設計に組み込む。 スナップショット、元に戻せるファイル変更、永続的なアンカーとしてのCLAUDE.md。長時間実行エージェントには、コンテキスト圧縮を生き延びるメモリが必要だ。

パーミッションの粒度は報われる。 ツールごと、パターンごと、ディレクトリごとのルール、deny優先の評価。「すべてを許可する」フラグよりも多くの作業が必要だが、デモとデプロイ可能なシステムの違いはそこにある。

独自ハーネスを構築するかマネージドレイヤーを使うかの判断

狭く明確に定義されたタスク——テストを実行して結果を投稿するCIボット——なら最小限のハーネスを自分で組める。いくつかのツール、シンプルなパーミッションチェック、固定されたコンテキストウィンドウ。

長時間セッション、コンテキストリセットをまたぐ状態、信頼できないツール出力、数十のツール——既存のハーネスの上に構築するか、一つを詳しく研究する。Claude Agent SDK、OpenAIのCodexアーキテクチャ、LangGraphは、あなたが必ずぶつかる問題をすでに解決している。

ほとんどのチームはハーネスの複雑さを過小評価する。私も確かにそうだった。モデルは簡単な部分だ。

FAQ

Claude Codeのエージェントハーネスとは何ですか？

Claudeモデルと現実世界の間のインフラストラクチャレイヤー——ツールディスパッチ、パーミッション、コンテキスト管理、セッション状態、MCP接続。Anthropicはそれを「言語モデルを有能なコーディングエージェントに変えるもの」と説明している。

Claude Codeはツールのパーミッションをどのように処理しますか？

ルールベースのパイプラインがすべてのツール呼び出しを評価する：allow、ask、またはdeny、denyが常に優先。オートモードでは、別のモデルインスタンス上のバックグラウンド分類器が曖昧なケースを評価する——プロンプトインジェクションを防ぐために、エージェントの散文出力を意図的に見ない。

Claude CodeのMCP統合はプロダクション対応済みですか？

機能しており活発に使用されているが、サーバー数、レスポンスサイズ、サードパーティの信頼に関する実用的な制限がある。急速に進化している。

同じパターンを使って独自のハーネスを構築できますか？

できる。Claude Agent SDKは同じパーミッションモード、フック、コンテキスト管理を公開している。Everything Claude Codeのようなコミュニティプロジェクトも再利用可能なパターンをドキュメント化している。

スペックパリティと動作パリティの違いは何ですか？

スペックパリティとは同じツールと設定をサポートすること。動作パリティとはエッジケースを同じように処理すること——コンパクションが重要なルールを削除する、ツールが100Kトークンを返す、モデルがパーミッションをバイパスしようとする。スペックのマッチングは簡単だ。動作のマッチングには数ヶ月かかる。

ずっと心に残っていること：ハーネスこそが難しい部分だ。誰もがモデルが競争上の優位性だと思っている。そしてそれは正しい——5分以上確実に何かをさせようとするまでは。そこにこそエンジニアリングが宿っている。

過去の記事：