Claude Code Sub-Agents 完全解剖：アーキテクチャ設計から実践的応用まで

AnthropicがClaude CodeにSub-Agents機能を導入したことで、単一のAIモデルがすべてのタスクを処理するという限界を打ち破りました。Claude Code Sub-Agentsを使用すると、それぞれが独立したコンテキスト、専用のツール権限、特定のモデル構成を持つ、複数の専門化されたサブエージェントを作成できます。コードレビュー、依存関係チェック、テスト作成といったタスクをすべて1つの汎用AIエージェントに任せるのではなく、Sub-Agentsによって真のタスク分離が実現されます。これは単なる機能の追加ではなく、根本的なアーキテクチャの転換です。

プロジェクトマネージャーとして、部下にリサーチ担当、実行担当、品質保証担当がいると想像してください。リサーチ担当者にコードの変更を実行させることも、品質保証担当者にアーキテクチャの決定を行わせることもありません。Claude Code Sub-Agents は、このロジックを AI レベルで実現したものです。各エージェントは単一の領域に特化することで、コンテキストの汚染を回避し、タスク完了の精度を高めます。

Claude Code の公式ドキュメントによると、サブエージェントのモデル選択は明確な優先順位に従います。環境変数 `CLAUDE_CODE_SUBAGENT_MODEL` > 各呼び出しの `model` パラメータ > サブエージェント定義の `model` フィールド > メイン会話のモデル。この優先順位設計により、エンジニアはグローバル、プロジェクトレベル、呼び出しレベルで細粒度な制御を行うことができます。

本文からSub-Agentsを3つの側面から分解します。第一に、なぜ隔離アーキテクチャなのかを理解します。

単一のAIエージェントが複雑なエンジニアリングタスクに対応できない理由

Claude Code Sub-Agents の分離設計が単一 AI エージェントよりも優れているのはなぜですか？

1つのClaudeコードエージェントがコードレビュー、依存関係チェック、単体テスト作成を同時に行うと、隠れたボトルネックが発生します。それはコンテキスト汚染です。

5分間で3つの全く異なるエンジニアリング分野を切り替えると、エージェントの推論パスが互いに干渉します。ロジックをレビューする決定ルールが、テスト作成の考え方に影響を与えます。ツールの出力を確認することが、その後のコード分析を汚染します。その結果、意思決定の質が低下し、実行時間が長くなり、エラー率が上昇します。

従来の単一モデルアーキテクチャでは、すべてのタスクが同じコンテキストウィンドウを共有することを強制されます。エージェントがプロジェクト A のレビュー規則、プロジェクト B の依存関係設定、プロジェクト C のテストフレームワークを同時に維持する必要があると仮定すると、これら 3 つのセットの規則は、単一のメモリ空間内で注意を奪い合います。Claude Code に Sub-Agents が導入された Anthropic の主な理由は、この制限を打破することです。

Claude Code の 3 つの組み込みサブエージェントタイプと動作メカニズム

Anthropic は Claude Code に 3 種類の専門化されたサブエージェントタイプを内蔵しており、それぞれが特定のエンジニアリングタスク向けに設計されています[citation:8]。これは単なる機能分類ではなく、読み書き権限、モデル構成、自動ルーティングロジックにおけるアーキテクチャの違いに基づいています。

型子代理：唯讀專家

型子代理のコアとなる制限は、読み取り専用であることです。コードベース全体をスキャンし、ファイル構造を分析し、依存関係リストを抽出することはできますが、ファイルを変更することはできません。

新しいプロジェクトのアーキテクチャを素早く理解する必要がある場合、Explore 型サブエージェントが特に役立ちます。例えば、新入社員が 50 個のファイルからなる Node.js プロジェクトを引き継ぐ場合、Explore 型サブエージェントは 30 秒以内に完全なディレクトリツリーとコアモジュールの関係図を生成します[citation:4]。この読み取り専用設計により、コードベースのセキュリティが確保されると同時に、迅速なアーキテクチャの理解が可能になります。

型子代理：執行の専門家

型子代理は書き込み権限を持ち、コードの直接編集、設定ファイルの更新、変更のコミットが可能です。コードのリファクタリング、依存関係のアップグレード、テストの修正の自動化に適しています。

監査型子代理：監査の専門家

Audit 型子代理により、読み取りと検証の機能が統合され、コード品質、セキュリティ脆弱性、コンプライアンスの問題をチェックできますが、ファイルを直接変更することはできません。

サブエージェントのモデル選択の優先度とコスト最適化戦略

Anthropic の Claude Code は、サブエージェントがどのモデルを使用するかを決定するために、4 段階の優先度システムを設計しています[citation:1]。優先度が高い順に、環境変数 CLAUDE_CODE_SUBAGENT_MODEL、単一呼び出し時の model パラメータ、サブエージェント定義の model フィールド、そして最後にメイン会話のモデルとなっています。

最高優先度の環境変数は、コードを変更せずに環境構成を通じてすべてのサブエージェントのモデルをグローバルに切り替えることを可能にします。これは、コストまたはパフォーマンスを迅速に調整する必要がある本番環境で特に価値があります。

実務上、Haiku、Sonnet、Opus の 3 つのモデルを組み合わせて構成することで、コストとパフォーマンスのバランスを効果的に取ることができます。コードレビュー（詳細な意味解析が必要）を Opus に、依存関係チェック（ルール検証）を Sonnet に、コード探索（高速スキャン）を Haiku に割り当てます。このような構成により、全体コストを40%以上削減しつつ、高品質なレビュー結果を維持することができます。

権限管理、ツールアクセス、および条件付きルールの設計パターン

これはオプションではなく、サブエージェントがその責務範囲を超えた操作を実行するのを防ぐために不可欠な設計です。権限管理は「最小権限の原則」に由来し、各サブエージェントが特定のタスクを完了するために必要なリソースとツールにのみアクセスできるようにします。

ツールアクセスリストは第一の防衛線です。各サブエージェントがどのツールを使用できるかを明確に定義できます。監査エージェントは、コードを変更することなく、ファイルとバージョン管理履歴のみを読み取れるようにする必要があります。例えば、`git log` や `grep` のような読み取りツールは許可し、`git push` や `rm` のような破壊的なコマンドは禁止します。

依存関係チェックエージェントは、パッケージ管理ツールのバージョン検証を行う必要がありますが、`package.json` の直接変更は禁止されるべきです。監査エージェントが誤って書き込み権限を取得した場合、重要なコードが誤って削除される可能性があり、依存関係エージェントが設定を編集できる場合、互換性のないバージョンが導入される可能性があります。

条件ルールは第二の防御線です。エージェントの決定を検証するための論理条件を設定できます。例えば、エージェントがコード変更を実行する前に静的解析チェックに合格しなければならないように変更したり、依存関係エージェントがバージョンをアップグレードする前に後方互換性を検証しなければならないようにしたりします。これらの条件ルールは、自動化プロセスの安全性と制御可能性を保証します。

よくある質問

サブエージェントのコンテキストサイズに制限はありますか？

各サブエージェントは独立したコンテキスト環境を持っています [citation:4]。これは、他のエージェントと会話履歴を共有しないことを意味します。実際には、メインの会話で 80% のコンテキストウィンドウが使用されている場合、新しく作成されたサブエージェントはまったく新しいコンテキストから開始され、親エージェントの履歴を継承することはありません。これは長期プロジェクトを扱う上で極めて重要です。コードレビュー用のサブエージェントが、以前の依存関係チェックのログによって汚染されることがないからです。

プロキシの継承の優先順位は何ですか？

モデルの選択は明確な優先順位に従って行われます [citation:1]。まず、CLAUDE_CODE_SUBAGENT_MODEL 環境変数を確認し、次に単一呼び出し時の model パラメータ、その次に Sub-Agent 定義の model フィールド、最後にメインの会話モデルの順となります。明示的に指定しない場合、Sub-Agent はメインの会話モデルをデフォルトで継承します [citation:3]。サポートされているエイリアスには、「sonnet」、「opus」、「haiku」、または「claude-opus-4-8」のような完全なモデルIDが含まれます [citation:2]。

自動ルーティングに失敗した場合、どのようにトラブルシューティングするべきですか？

3つの側面をチェックしてください。まず、サブエージェントのツールアクセス権限が正しく構成されているか検証します[citation:7]。次に、条件付きルールのロジックが実際のタスクと一致しているか確認します。最後に、モデルエイリアスがサポートされている形式で使用されているかチェックします。一般的な原因は、権限モードの設定が厳しすぎ、サブエージェントが必要なツールにアクセスできないことです。

複数のサブエージェントは同じツールを共有できますか？

はい、ただし権限レベルで明確に定義する必要があります。異なるサブエージェントは同じツールにアクセスできますが、それぞれの権限範囲は独立しています。例えば、コードレビューサブエージェントはファイル読み取り権限のみを持つことができ、テスト実行サブエージェントは実行権限を持つことができます。この階層的な設計は情報漏洩を防ぎます[citation:5]。

サブエージェントはどのようなエンジニアリングシナリオに適していますか？

専門性と再利用性が主な強みである [citation:6]。代表的な用途としては、静的解析専用エージェント、依存関係管理エージェント、コード生成エージェントなどが挙げられる。各エージェントは単一の領域に特化しており、汎用エージェントよりも精度が30～40%高い。関連トピック：「Subagent モデルの選択における優先順位とコスト最適化戦略」。

結論

Claude Code のサブエージェントアーキテクチャは、単一モデルが複雑なエンジニアリングタスクに対応するのが難しいという現状を変革します。分離、専門化、権限制御という 3 つのコア設計原則により、開発チームはコスト効率を維持しながら、より安定した監査可能な自動化ワークフローを構築できます。分離は、障害が連鎖的に広がるのを防ぎます。専門化は、各エージェントが得意分野に集中することで、幻覚のリスクを低減します。権限制御は、不正なシステム変更を防ぎます。実践においては、適切なモデル優先度（高頻度タスクには claude-3-5-sonnet、複雑な推論には claude-3-opus）の選択、明確なツールアクセスの境界線の定義、エージェントの決定を検証するための条件付きルールの確立が、概念から本番環境への実現の鍵となります。これは単なる技術的なアップグレードではなく、ソフトウェア開発ワークフローのアーキテクチャ方法を再考するものです。

主なポイント

• サブエージェントによる透過的な分離と専門化により、複雑なエンジニアリングタスクにおける単一AIエージェントの能力のボトルネックを解決
• 三つの組み込み型（コード実行、ツール利用、推論）は、それぞれ明確な動作境界とコスト特性を持っています。
• モデル選択の優先度とツールへのアクセス権限の設計は、システムの安定性と監査能力に直接影響します。
• 条件規則と権限制御は、エージェントの越権操作を防ぐための防御線であり、本番環境で必須のメカニズムです。
• 開発からデプロイまで、鍵となるのは、より多くのモデル能力を積み重ねることではなく、明確なエージェントの境界を定義することです。

情報源

1. サブエージェントモデルの選択は、優先順位の階層に従います — code.claude.com
2. Claude Codeサブエージェント機能により、独立したコンテキストを持つ複数の専門的な子エージェントを作成できます — ithelp.ithome.com.tw
3. Claude Code には 3 種類の組み込みサブエージェントタイプが同梱されています — ksred.com