Claude Codeで自律作業を加速！サブエージェント/バックグラウンドエージェント徹底活用ガイド

Claude Codeで自律作業を加速！サブエージェント/バックグラウンドエージェント徹底活用ガイド Claude Code活用

導入：コンテキスト過多を乗り越え、Claude Codeで真の並列開発を実現する

Claude Codeを使っていると、大規模なコードベースの調査や複雑なタスクの実行時に、メインの会話が大量のログ、ファイル内容、検索結果で溢れかえり、「コンテキスト過多」に陥ることがよくあります。重要な情報を見失い、エージェントの思考も散漫になりがちです。

そこで本記事では、Claude Codeの強力な機能であるサブエージェントとバックグラウンドエージェントを深掘りします。これらを活用することで、メインの会話をクリーンに保ちながら、並列タスク、大規模なリサーチ、そして多段階のワークフローを効率的に実行する方法を、具体的なプロンプトと成功判定付きで解説します。

公式ドキュメントには書かれていない実践的な使い分けのコツや、思わぬ「つまずき所」も共有しますので、あなたのClaude Code活用レベルを一段引き上げましょう。

1. サブエージェントとは？：独立した思考を持つ分身たち

サブエージェントは、メインのClaude Codeセッションから特定のタスクを委譲される、独立したAIアシスタントです。最大の特長は、メインの会話とは分離された独自のコンテキストウィンドウでタスクを実行する点にあります。

1.1. コンテキスト分離のメカニズムとメリット

  • 独自のコンテキスト: サブエージェントは、カスタムのシステムプロンプト、特定のツールアクセス、独立した権限を持ちます。メインの会話履歴やその時点で呼び出されているスキルは継承しません。
  • メインセッションの保護: 大量のファイル読み込みや広範なWeb検索が必要なタスクでも、その過程で発生する膨大な中間出力やログがメインの会話を汚しません。結果の要約だけがメインセッションに返されます。
  • 専門化: 特定の役割（例: コードレビュアー、リサーチャー、デプロイ担当）に特化させ、効率と精度を高めることができます。

1.2. フォアグラウンド実行とバックグラウンド実行

サブエージェントは、そのタスクの性質に応じて「フォアグラウンド」または「バックグラウンド」で実行されます。

  • フォアグラウンドサブエージェント: メインの会話をブロックし、完了するまで待機します。途中でツール実行の許可が必要になった場合、そのプロンプトは直接ユーザーに表示されます。
    • 使いどころ: メインのタスクがサブエージェントの結果を即座に必要とする場合、またはリアルタイムでの監視・介入が必要な場合。
  • バックグラウンドサブエージェント: メインの会話と並行して実行されます。ユーザーはサブエージェントが作業している間も、メインセッションで別の作業を進めることができます。Claude Code v2.1.198以降、サブエージェントはデフォルトでバックグラウンドで実行されるようになりました。ツール実行の許可が必要な場合も、メインセッションに通知が表面化し、そこで承認・拒否が可能です。
    • 使いどころ: 時間のかかるリサーチ、監視タスク、ビルドやテストの実行など、完了を待つ必要のないタスク。

1.3. ツールセットの制限とつまずき所

バックグラウンドサブエージェントは、メインセッションよりも利用可能な組み込みツールが制限されるという重要な制約があります。

  • 制限されるツール: 例えば、Agentツール（別のサブエージェントの起動）やEnterWorktree/ExitWorktree以外のgit関連ツールの一部、特定の高レベルな操作ツールなどがデフォルトで削除されます。
  • 利用可能なツール: Read, Grep, Glob, Bash, PowerShell, Edit, Write, WebFetch, WebSearch, Skill など、基本的なファイル操作や情報収集、コード編集に関するツールは引き続き利用可能です。
  • つまずき所: 「メインセッションで動いたプロンプトが、バックグラウンドサブエージェントではツール不足で失敗する」という事態に遭遇することがあります。これは、バックグラウンドサブエージェントが「予期せぬ破壊的変更を防ぐ」「過剰なリソース消費を抑制する」といった安全性と効率性のために意図的に制限されているためです。
    • 対策: サブエージェントに委譲するタスクは、可能な限りシンプルなツールセットで完結するように設計するか、必要に応じてtools:フィールドで明示的に許可するツールを定義する必要があります。ただし、許可できないツールもあります。

2. サブエージェント実践手順：業務フローを再構築する

ここでは、サブエージェントを活用した具体的な業務フローを3つの例で紹介します。それぞれにプロンプト、期待結果、成功判定を明記します。

2.1. 例1: 大規模コードベースの依存関係を効率的に調査する（Synthesis & Context Control）

新機能開発やリファクタリングの際、特定のクラスや関数の依存関係を理解するために、関連ファイルを芋づる式に調査することがよくあります。メインセッションでこれをやると、あっという間にコンテキストが溢れます。

ここでは、特定のファイルが依存する他のファイルのリストを抽出し、その概要をメインセッションに要約させるサブエージェントを作成します。

シナリオ: src/features/user_profile/UserProfileService.ts が、プロジェクト内のどのユーティリティ関数やサービスに依存しているかを調査したい。

プロンプト1: サブエージェントを定義して依存関係を調査させる

この例では、サブエージェントにプロジェクト全体から特定のファイルのインポートを検索させ、その結果を要約させます。

あなたは「依存関係アナライザー」サブエージェントです。
メインエージェントから渡されたファイルパスに対し、そのファイルが`import`している他のプロジェクト内ファイル（`src/`または`utils/`配下）を再帰的に検索し、依存パスと簡単な概要を抽出してください。
抽出後、メインエージェントに簡潔なサマリーと、依存関係マップ（Markdown形式）を返してください。
検索には`grep`と`read`を使用し、不要なファイルは無視してください。

以下のタスクを実行してください:
1. `src/features/user_profile/UserProfileService.ts`がimportしているファイルを特定する。
2. 特定された各importについて、それが`src/`または`utils/`配下のどのファイルに該当するかを特定する。
3. 各依存ファイルの最初の数行を読み、その役割を簡潔にサマライズする。
4. 最終的に、発見された依存関係のリストとその概要を、メインエージェントにMarkdownリスト形式で報告する。
  • 期待結果: UserProfileService.tsが依存するファイルパスと、各ファイルの簡単な説明がMarkdownリスト形式で出力される。メインセッションのコンテキストは肥大化しない。
  • 成功判定: メインエージェントの応答として、「依存関係アナライザー」からのサマリーと、src/やutils/内の依存ファイルのリスト（各々に簡単な説明付き）が、5行以上のMarkdownリストで表示される。

2.2. 例2: 新規開発における並列でのフロントエンド・バックエンドAPIスタブ作成（Parallel Execution）

新しい機能では、多くの場合、フロントエンドのUIと連携するバックエンドAPIが必要になります。メインエージェントがUI実装に着手しつつ、同時にバックエンドAPIのスタブ作成をサブエージェントに委譲することで、開発を並列で進めることができます。

シナリオ: 新しいユーザーダッシュボード機能のために、メインエージェントはReactコンポーネントの作成を進め、サブエージェントにはそのダッシュボードが利用するAPIエンドポイントのスタブをGo言語で作成させたい。

プロンプト2: バックエンドAPIスタブ作成をサブエージェントに委譲

あなたは「バックエンドAPIスタブジェネレーター」サブエージェントです。
メインエージェントが要求するAPI仕様に基づき、Go言語で基本的なAPIエンドポイントのスタブコードを作成してください。
具体的なタスクは以下の通りです。

タスク:
`api/users/dashboard.go` というファイルを新規作成し、以下の要件を満たすGo言語のAPIハンドラスタブを実装してください。
- エンドポイント: `/api/users/dashboard`
- メソッド: GET
- レスポンス: ダミーのJSONデータ（ユーザー名、メールアドレス、最近のアクティビティリストなどを含む）を返す。
- エラーハンドリング: 基本的なエラーレスポンスも含む（例: 認証失敗時の401）。
- コメント: 各セクションに簡単な説明コメントを追加してください。

完了後、作成したファイルパスとコードの概要をメインエージェントに報告してください。
  • 期待結果: メインエージェントがUIコンポーネント開発を継続中に、サブエージェントがapi/users/dashboard.goファイルを生成し、その内容の概要を報告する。
  • 成功判定: api/users/dashboard.goファイルがプロジェクト内に存在し、指定されたGo言語のAPIスタブコードが含まれていることを、ファイル内容の確認（readツールなど）で確認できる。報告された概要がコード内容と一致する。

プロンプト3: メインエージェントにフロントエンドUIコンポーネント作成を指示（Parallel Execution）

サブエージェントがバックエンドスタブを作成している間に、メインエージェントにフロントエンドのUIコンポーネントを作成させます。

私は新しいユーザーダッシュボード機能のフロントエンド開発を進めます。
`src/components/dashboard/UserDashboard.tsx` に、ReactのTypeScriptコンポーネントを作成してください。
このコンポーネントは、バックエンドAPI `/api/users/dashboard` からデータを取得し、以下の要素を表示するダミーUIを実装してください。

- ユーザーのウェルカムメッセージ（例: 「こんにちは、[ユーザー名]さん！」）
- プロフィール画像（ダミーのプレースホルダーを使用）
- 最近のアクティビティリスト（簡単なリスト表示）
- データ取得中を示すローディングステート
- エラー発生時のメッセージ表示

API呼び出しには`fetch`APIを使用し、Goで作成されたAPIスタブのエンドポイントを想定してください。
コンポーネントはシンプルなFunctional Componentとしてください。
  • 期待結果: src/components/dashboard/UserDashboard.tsxファイルが作成され、指定されたReactのTypeScriptコンポーネントが実装される。
  • 成功判定: src/components/dashboard/UserDashboard.tsxファイルが存在し、ダッシュボードUIの基本的なReactコードが含まれていることを確認できる。コード内にfetch('/api/users/dashboard')のようなAPI呼び出しロジックが存在する。

2.3. 例3: ネストされたサブエージェントによるコード品質の自動検証（Nested Subagents）

大規模プロジェクトのコードレビューでは、レビュアーが特定のコード変更に対して複数の観点（セキュリティ、パフォーマンス、コードスタイルなど）で検証を依頼したいことがあります。ネストされたサブエージェントを活用することで、この多段階レビューを自動化できます。

シナリオ: プルリクエスト（PR）の一部として提案された変更について、メインエージェントが「セキュリティレビュー」サブエージェントを起動。このセキュリティレビュアーは、さらに「SQLインジェクションチェック」と「XSS脆弱性チェック」のサブエージェントを起動し、それぞれの専門領域でコードを検証させる。

プロンプト4: セキュリティレビューサブエージェントを起動

まず、メインエージェントからセキュリティレビューサブエージェントを起動します。

あなたは「セキュリティレビュアー」サブエージェントです。
メインエージェントから渡されたコードスニペットに対し、一般的なWebアプリケーションのセキュリティ脆弱性（SQLインジェクション、XSS、CSRFなど）がないかを総合的にレビューしてください。
必要に応じて、さらに専門的なサブエージェントを起動し、詳細なチェックを委譲しても構いません。
最終的なレビュー結果（発見された脆弱性とその対策、または問題なし）をメインエージェントに報告してください。

以下のコードスニペットをレビューしてください:

```python
# users.py
def get_user_data(username):
    conn = get_db_connection()
    cursor = conn.cursor()
    query = f"SELECT * FROM users WHERE username = '{username}'"
    cursor.execute(query)
    return cursor.fetchone()

def update_profile(user_id, profile_data):
    conn = get_db_connection()
    cursor = conn.cursor()
    # Assume profile_data is a dict like {'email': 'new@example.com', 'bio': 'updated bio'}
    set_clauses = [f"{k} = '{v}'" for k, v in profile_data.items()]
    query = f"UPDATE users SET {', '.join(set_clauses)} WHERE id = {user_id}"
    cursor.execute(query)
    conn.commit()
    return True


*   **期待結果**: 「セキュリティレビュアー」サブエージェントが起動され、コードスニペットのレビューを開始する。その過程で、SQLインジェクションやXSSに関連するサブエージェントを内部的に起動する思考プロセスが見られる。
*   **成功判定**: メインエージェントの応答として、「セキュリティレビュアー」サブエージェントからの詳細なレビュー結果が表示され、与えられたPythonコードにSQLインジェクションの脆弱性があることを指摘し、対策を提案する。

#### プロンプト5: （内部的なネスト例）SQLインジェクションチェックサブエージェントの思考プロセス

セキュリティレビュアーは、上記のコードスニペットを見て、内部的にこのようなサブエージェントを起動するかもしれません。（ユーザーが直接このプロンプトを指示する必要はありませんが、エージェントの思考プロセスを理解するために記載します。）

```claude
あなたは「SQLインジェクションチェッカー」サブエージェントです。
渡されたPythonコードスニペットに対し、SQLインジェクションの脆弱性がないかを専門的にチェックしてください。
特に、ユーザー入力がSQLクエリに直接埋め込まれている箇所を特定し、その危険性を指摘し、プリペアドステートメントやORMの利用など、安全な代替案を提案してください。
  • 期待結果: （セキュリティレビュアーサブエージェントの内部で）SQLインジェクションチェッカーが起動し、get_user_data関数とupdate_profile関数におけるSQLインジェクションの脆弱性を正確に特定する。
  • 成功判定: 最終的な「セキュリティレビュアー」からの報告に、get_user_dataおよびupdate_profile関数におけるSQLインジェクションの具体的な脆弱性の指摘と、プリペアドステートメントの使用といった改善策が含まれている。

3. 注意点とトラブルシューティング

サブエージェントを効果的に活用するためには、いくつかの注意点があります。

  • ツールの制限を理解する: バックグラウンドサブエージェントはメインセッションと同じツールセットを持つわけではありません。特に、gitコマンドを使った複雑な操作や、高度なCLIツールが必要な場合は、メインセッションで実行するか、サブエージェントのtools:定義で明示的に許可する必要があるか、フォアグラウンドサブエージェントの利用を検討してください。
  • コンテキストの受け渡し: サブエージェントはメインセッションの会話履歴を継承しません。そのため、タスクに必要な情報をプロンプト内で明示的に渡すか、ファイルとして共有するなどの工夫が必要です。過不足なく情報を渡すことが、サブエージェントのパフォーマンスを最大化する鍵となります。
  • ネストの深さ制限: デフォルトではサブエージェントは最大3層までネストできます。それ以上の深いネストが必要な複雑なワークフローは、設計を見直すか、エージェントチームの活用を検討してください。
  • バックグラウンドタスクの無効化: 環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に設定することで、すべてのバックグラウンドタスク機能を無効にできます。予期せぬバックグラウンド実行を防ぎたい場合に利用しますが、基本的にはデフォルト設定のままで問題ありません。
  • 進捗の確認: バックグラウンドサブエージェントの進捗はメインセッションに要約として返されますが、詳細なログが必要な場合は--forward-subagent-textフラグ（v2.1.211以降）を利用して、サブエージェントの思考プロセスをメインセッションに出力させることも可能です。ただし、これによりメインセッションのコンテキストが再び肥大化する可能性があるので注意が必要です。

4. 他の機能との比較：スキルとエージェントチーム

サブエージェントはClaude Codeの強力な機能ですが、似たような目的で利用される「スキル」や「エージェントチーム」との違いを理解し、適切に使い分けることが重要です。

4.1. スキルとの違い

  • スキル: 再利用可能な指示、知識、ワークフローの集まりです。メインのコンテキストにロードされ、必要に応じて呼び出されます。コンテキストウィンドウに「追加」される形で利用されます。
  • サブエージェント: 独立した作業者であり、独自の分離されたコンテキストで動作します。メインの会話のコンテキストウィンドウを消費せずに、タスクを実行し、結果を要約して返します。
  • 使い分け:
    • スキル: 定型的な手順、APIリファレンス、常に参照すべきコーディング規約など、メインエージェントが知識として持つべき情報やワークフローに最適です。
    • サブエージェント: 大量のファイルを読み込むリサーチ、並列実行したいタスク、中間結果がメインの会話を汚すべきではない分離された作業に最適です。

4.2. エージェントチームとの違い

  • サブエージェント: 単一のセッション内で、リードエージェントがタスクを委譲し、結果を受け取るという、親子関係のような構造で動作します。結果はメインエージェントに要約されて戻ります。
  • エージェントチーム: 複数の独立したClaude Codeセッション（エージェント）が互いにメッセージを送り合い、共同でタスクを解決する協調的な構造です。各エージェントは完全に独立したコンテキストを持ち、複雑な議論やコラボレーションが可能です。
  • 使い分け:
    • サブエージェント: 迅速かつ焦点を絞った作業、結果の要約だけで十分な場合に適しています。コストもエージェントチームより低く抑えられます。
    • エージェントチーム: 複数の視点からの議論、競合する仮説の検証、大規模なリファクタリングのように各エージェントが独立した部分を担当し、互いに調整が必要な複雑で高度なコラボレーションが必要な場合に適しています。コンテキストの限界に達した場合の次のステップとしても検討されます。

5. 締め：Claude Codeで自律エージェントの可能性を最大限に引き出す

サブエージェントとバックグラウンドエージェントは、Claude Codeを単なる強力なAIアシスタントから、真に自律的な開発パートナーへと昇華させるための鍵となる機能です。コンテキストの効率的な管理、並列でのタスク実行、そして複雑なワークフローの自動化を通じて、あなたの開発プロセスは飛躍的に改善されるでしょう。

今回紹介した活用例や注意点を参考に、ぜひ今日からあなたのプロジェクトでサブエージェントを導入してみてください。最初は少し戸惑うかもしれませんが、その恩恵は計り知れません。Claude Codeの真の力を引き出し、よりスマートな開発体験を手に入れましょう。

あわせて読みたい

コメント

タイトルとURLをコピーしました