Claude Codeにおけるエージェントとサブエージェントの構造理解
Claude Codeを理解する上で重要なのは、私たちがターミナルで対話している「メインエージェント」と、その背後で動く「サブエージェント（subagents）」の役割の違いを明確にすることです。
1. メインエージェント：常に起動している「指揮官」
Claude Codeを立ち上げた瞬間、そこにはすでにエージェントが存在しています。
- 構造: LLM + ツール（ファイル操作、Bash実行、検索） + エージェンティックループ
- 状態: 起動した瞬間から「ツールを使って課題を解決する」というループの中にいるため、これを「使う/使わない」という選択肢はありません。
2. サブエージェント：役割を分離した「専門部隊」
最近話題になっている「エージェントを活用する」という話の多くは、このサブエージェント（subagents）のオーケストレーションを指します。メインエージェントから別のコンテキストを持った子エージェントを spawn（生成）する仕組みです。
なぜサブエージェントを使うのか？
- コンテキストの分離: メインの会話履歴（コンテキストウィンドウ）を汚さずに、膨大な調査やログ解析を別枠で実行できる。
- 権限の制限（Tool Restrictions）: 「読み取り専用（read-only）」などの制限をかけられるため、安全にコードベースを探索させることができる。
- 並列処理: メインが思考している間に、別のタスクをバックグラウンドで走らせることが可能。
- コスト最適化: モデルのルーティングにより、軽量なタスクを安価なモデル（Haiku等）に割り振る。
3. サブエージェントの分類
Claude Codeには、用途に応じて複数のサブエージェントの形態が用意されています。
A. ビルトイン・サブエージェント
システムに最初から組み込まれており、必要に応じてClaudeが自動的に呼び出します。
- Explore: コードベースの検索・分析専用。高速かつRead-onlyで動作。
- Plan:
plan mode中に、現状を把握し、実装のロードマップを立てるために動く。 - General-purpose: メインから特定のタスクを委譲（delegate）される汎用エージェント。
B. カスタム・サブエージェント
ユーザーが独自の役割を定義できる仕組みです。.claude/agents/ ディレクトリ内にMarkdown形式で定義ファイルを置くことで、特定の専門性を持たせることができます。
- 例:
code-reviewer（コード規約チェック）、test-runner（テスト実行と修正）、security-scanner（脆弱性診断）。 - 管理:
/agentsコマンドで一覧の確認や呼び出しが可能。
C. 次世代のマルチエージェント（実験的）
- Agent Teams: 複数のClaude Codeセッションが相互に通信し、協力して巨大な課題を解決する仕組み。
- Background Agents: 複数のセッションをバックグラウンドで並列稼働させ、一つの画面からそれらをモニタリングする機能。
4. エージェントを「使いこなす」とは
「Claude Codeを起動しただけ」の状態は、一人の有能なエンジニアと対話している状態です。
一方で、サブエージェントを理解し、意図的に権限分離やタスク委譲を行う状態は、「エンジニアリングチームのマネージャー」としてAIを指揮している状態と言えます。特にカスタムサブエージェントによる「役割の定義」と「ツールの制限」を使いこなすことが、Claude Codeのポテンシャルを最大限に引き出す鍵となります。
サブエージェント導入の推奨ステップ：まずは「2つの特化型」から
Claude Codeのサブエージェント機能を使いこなすには、最初から多くのエージェントを作成するのではなく、まずは役割が明確な2つのエージェントで「サブエージェントが効く感覚」を掴むのが近道です。
以下のステップでの導入を推奨します。
1. 最初の1週間：2つのエージェントに絞る
まずは、汎用性の高い以下の2つを作成し、1週間集中的に運用してみてください。
explorer-readonly- 役割： コードベースの調査・分析。
- メリット：
read-only権限を明示することで、意図しないコードの書き換えを防ぎ、安全に構造把握を任せられる。
test-runner- 役割： テストの実行とエラー修正のループ。
- メリット： メインエージェントが機能実装に集中している間に、テストの実行とデバッグを分離して任せることができる。
これらで「コンテキストが分離され、作業が並列化される恩恵」を実感できたら、特定の外部API連携や、特定のクラウドインフラ操作に特化したエージェントへ拡張していくのが理想的です。
2. エージェント定義のバージョン管理
エージェントの挙動を安定させるためには、.claude/agents/*.md 自体もプロジェクトのコードと同様に管理することを推奨します。
- 管理手法： ファイル内に
v1.0/v1.1といったバージョン表記を記述する。 - 利点： 指示（プロンプト）を微調整した際に、どのバージョンの時に期待通りの挙動をしたか、あるいは挙動が悪化したかをGitの履歴と合わせて追跡可能になります。
3. 具体的なエージェント定義（テンプレート）
導入の足がかりとして、すぐに使える定義の叩き台を以下に示します。
explorer-readonly.md
---
name: explorer-readonly
description: MUST BE USED for codebase exploration and file discovery.
Use PROACTIVELY before making any code change to find relevant files and patterns.
Returns concise summary only.
tools: Read, Grep, Glob
model: haiku
---
You are a codebase exploration specialist.
Process:
1. Glob で候補ファイルを絞る
2. Grep でパターン検索
3. 有望なファイルを Read で確認
4. サマリを返す
出力フォーマット:
- 関連ファイル: path:line ranges
- 実装パターン: 簡潔に
- 関連する依存箇所
- 次に見るべき場所の提案
制約:
- 絶対に書き込まない
- サマリは 500 words 以内
- 見つからなければ「見つからない」と明示
test-runner.md
---
name: test-runner
description: MUST BE USED after any code change to verify tests pass.
Use PROACTIVELY when fixing bugs.
Returns only failing tests with concise error messages, not full output.
tools: Bash, Read
model: sonnet
---
You are a test execution specialist.
Process:
1. package.json / pyproject.toml からテストコマンドを検出
2. 実行
3. 結果をパース
4. 簡潔に報告
出力フォーマット:
✅ X passed / ❌ Y failed
Failing tests:
- test_name (file:line): error summary
全部通った場合は一行のみ: "All N tests passed."
制約:
- ファイル変更しない
- 修正提案はしない、報告のみサブエージェントの基本的な使い方：自動と明示の二段構え
サブエージェントを定義したあと、実際にどうやって動かすのか。Claude Codeには「サブエージェント・モード」のような切り替えスイッチはありません。基本は「自動で勝手に動く」、必要なら「明示的に指名する」という二段構えで運用します。
1. 自動デリゲーション（基本の動き）
メインエージェントは、定義された各サブエージェントの description（説明文）を読み、「このタスクはあの子に任せるべきだ」と判断すると勝手に呼び出します。
- 発動のコツ：
descriptionには強い表現を使うのがポイントです。- ❌ 「〜のレビューに使える」といった弱い表現
- ✅ 「MUST BE USED after any code change.（コード変更後は必ず使用すること）」といった命令形
- 強い言葉を入れることで、メインエージェントが「あ、今はこいつを呼ぶタイミングだ」と認識しやすくなり、自動発動率が上がります。
2. 明示的に指名して呼び出す
「自動で呼ばれるのを待ちたくない」「今このタイミングで動かしたい」という時は、チャットの中で直接指示します。
指示の例：
自動呼び出し：
> 認証 middleware 修正した、テスト通る?
→ test-runner が自動起動
> RBAC 周りを直したいんだけど、まず全体像を知りたい
→ explorer-readonly が自動起動
明示的呼び出し：
> explorer-readonly で webhook 受信ハンドラを全部洗って
> test-runner だけ走らせて、結果見せて
> いまの変更について、test-runner サブエージェントに verify させて
並列呼び出し：
> 以下を explorer-readonly で並列調査して:
> 1. HMAC 検証の実装箇所
> 2. レート制限ハンドリング
> 3. アクセストークンの保管方法
サブエージェント名を文章に含めるだけでOKです。@test-runner のように @ 記法を使うこともできますが、必須ではありません。
3. サブエージェント実行中の挙動
サブエージェントが動き出すと、画面には Task(...) というツールコールが表示されます。
- 見えること： どのサブエージェントが呼ばれたか、完了後の最終サマリ。
- 見えないこと： サブエージェント内部の思考プロセスや細かいツール実行の詳細は、リアルタイムでは表示されません。
- 注意点： 内部が見えないため「本当に動いているか？」と不安になることがありますが、完了まで待つのが仕様です。
4. パフォーマンスを最大化する「並列起動」
複数のサブエージェントに異なるタスクを同時に依頼できます。
- 「
explorer-Aに X を、explorer-Bに Y を、同時に調べさせて」と指示。 - 完了タイミングはバラバラでも、最終的にメインエージェントが結果をまとめて報告してくれます。
- 3つの調査を並列で行えば、単純計算で1/3の時間で結果が揃うため、最も速度向上を実感できる瞬間です。
5. 長時間タスクはバックグラウンドへ
テストスイートの全実行や大規模なコード調査など、時間がかかるタスクは Ctrl+B でバックグラウンドに飛ばせます。サブエージェントが裏で作業している間、メインエージェントで別の対話を続けることができ、完了すると通知が届きます。
6. 管理用の /agents コマンド
セッション中にエージェントの状態を確認・操作したいときは /agents コマンドを使用します。これは「呼び出し」ではなく、あくまで「管理」のための機能です。
- 定義済みエージェントの一覧表示
- エージェントの作成・編集
- 有効 / 無効の切り替え
長時間タスクを効率化する「バックグラウンド実行」
Claude Codeを使いこなす上で、作業効率を劇的に変えるのがバックグラウンド実行（Ctrl+B）です。これを知っているかどうかで、AIとの「待ち時間」の使い方が大きく変わります。
1. 基本フロー：タスクを「裏」へ送る手順
Ctrl+B は「タスクを指定して実行する」機能ではありません。「走り出したタスクから視線を外す」ための機能です。
- 依頼する： 普通にプロンプトを投げる（例：「全体のセキュリティ調査をして」）
- 動き出す： Claudeがサブエージェントを起動し、調査を開始する
- 裏へ送る： タスクが走っている最中に
Ctrl+Bを押す - 自由になる： メインの入力欄が解放され、別の作業や指示を打ち込めるようになる
- 完了： バックグラウンドでの作業が終わると、結果が通知・表示される
【重要】
Ctrl+Bはエージェントが「実行中」に押す必要があります。完了した後に押しても意味がありません。
2. 「モニターしない」ことで得られる「並列性」
「Ctrl+B は単にモニター（監視）を止めるだけ？」という問いへの答えは「YES」です。しかし、その最大のメリットはメインセッションのブロックが解除されることにあります。
| 観点 | そのまま見守る | Ctrl+B で裏に送る |
|---|---|---|
| タスクの動作 | 同じ | 同じ |
| 出力の見え方 | リアルタイムで見える | 完了後にまとめて見る |
| メインの自由度 | 終わるまで何も打てない | すぐに次の指示が打てる |
| 並列性 | 1つずつ実行 | 複数同時実行OK |
つまり、数分かかる調査やテストを Ctrl+B で裏へ飛ばし、その間に別の修正を指示する……という「AIチームを並列でこき使う」運用が可能になります。
3. 管理用ショートカット・コマンド
裏に送ったタスクがどうなっているかは、以下のコマンドで確認できます。各タスクには bash_1 bash_2 のようなIDが振られます。
| ショートカット / コマンド | 用途 |
|---|---|
Ctrl+B | 実行中のタスクを裏に送る |
Ctrl+T | 裏で走っているタスクの一覧を表示 |
/btw | 「ところで、裏のタスクどうなった？」と進捗を聞く |
Ctrl+F (2回押し) | すべてのバックグラウンドエージェントを停止する |
Tips:
tmuxを使っている方は、tmux側のプレフィックスと衝突するため、Ctrl+Bを2回叩く必要があります。
4. 便利な自動設定（auto-backgrounding）
毎回 Ctrl+B を押すのが面倒な定型コマンド（npm run dev や重いテストスイートなど）は、CLAUDE.md に記述しておくことで自動的にバックグラウンド送りにできます。
## Always Run in Background:
- `npm run dev`
- `docker-compose up`
- `npm test` (大規模なもの)
まとめ：使い分けの判断基準
- 数十秒で終わるタスク： そのまま見ていたほうが、思考が途切れずスムーズです。
- 数分以上かかるタスク： 迷わず
Ctrl+Bで裏に飛ばし、自分は次の指示に進みましょう。
「モニターしない」という選択をすることで、あなたの作業スピードはAIの処理待ちから解放され、真の意味で「複数のエージェントを指揮する」次元へと進化します。