エンジニアがCLI上でAIと対話する際、一つの窓口だけで膨大なコードベースを修正させるのは限界があります。Claude Codeには「サブエージェント」と呼ばれる仕組みがあり、メインのAIが自律的に複数の子AIを立ち上げて並列作業を行うことが可能です。
この記事では、Claude Codeのサブエージェントを効率よく動かし、リファクタリングやバグ修正を爆速で終わらせるコツを解説します。複雑なタスクを丸投げして、本来の設計や意思決定に集中できる環境を整えましょう。
サブエージェントが自律的に動く仕組み
Claude Codeを動かしているとき、ターミナル上で「Sub-agent spawning…」といった表示を見たことはないでしょうか。これはメインのAIが、自分一人では処理が重すぎる、あるいは専門的な調査が必要だと判断したときに、特定の役割を持った子AIを呼び出している状態を指します。メインエージェントが現場監督となり、サブエージェントが各現場の作業員として動くような階層構造をイメージすると分かりやすいはずです。
メインエージェントとの役割分担
メインエージェントは、ユーザーとの対話を維持しつつ全体の進捗を管理する司令塔です。一方で、サブエージェントは指示された「特定のファイル群」や「特定のテスト項目」だけに集中して作業を行います。
この分離により、メインエージェントが道筋を見失うリスクを最小限に抑えられます。メインが全体の整合性をチェックし、サブが泥臭い修正作業を代行する、という分業が自動で行われます。
子AIが並列でタスクを処理する流れ
複雑な修正指示を出すと、メインエージェントはタスクを細分化します。次に、それぞれの断片を処理するためにサブエージェントを立ち上げ、並列でファイル操作や検索を実行させます。
最終的にサブエージェントが作業結果をメインに報告し、メインがそれらを統合してユーザーに提案します。複数のファイルを同時に読み解きながら、一貫性のある修正案を作り上げるのはこの機能のおかげです。
コンテキストを分離して精度を高める理由
AIには一度に扱える情報の限界（トークン制限）がありますが、サブエージェントはこの問題を解決します。各サブエージェントは必要なファイルの文脈だけを持って動くため、情報過多によるミスを防げます。
深い階層にあるディレクトリを調査する際、サブエージェントがその階層専用のメモリを持って動く仕組みです。大規模なリポジトリでも、AIが「今何をしているか」を忘れずに正確なコードを書けるのは、このコンテキスト分離が機能しているからです。
複雑なタスクを分解して依頼する方法
サブエージェントを上手に活用するには、AIがタスクを分解しやすいように「外枠」を固めてから指示を出すのが近道です。あいまいな指示ではサブエージェントが効率よく立ち上がらず、メインエージェントが無理に一人で解決しようとして失敗することがあります。テクニカルな詳細を詰め込みつつ、AIが「これは分担が必要だ」と判断できる具体的な依頼を心がけましょう。
全体設計と個別の実装を分ける
いきなり「全部直して」と言うのではなく、まず全体の構成案をAIに作らせます。その構成案に対して承認を与えてから、詳細な実装をサブエージェントに任せるのが理想的です。
設計フェーズをメインに担当させ、ファイル単位の書き換えをサブに振らせる流れを作ります。作業の「大枠」を人間とメインエージェントで合意しておくことで、サブエージェントの迷走を防げます。
依存関係の調査を優先させるプロンプト
サブエージェントが最も力を発揮するのは、ファイル間の繋がりを調べる「リサーチ」の段階です。修正に入る前に、まずプロジェクトの構造を可視化させる指示を出し、サブエージェントを動員させましょう。
特定の関数がどこで使われているか、インポートの連鎖はどうなっているかをAIに徹底的に洗わせます。依存関係を完全に把握させた状態で次のタスクへ進むと、サブエージェントによる修正の成功率が跳ね上がります。
サブエージェントが起動する指示の出し方
「〇〇を修正して」という単発の指示よりも、「以下の3つのステップでプロジェクト全体を改善して」といった多段階の指示が有効です。
/initでインデックスを作成した後に指示を出す。- 複数のディレクトリにまたがる変更を明示的に要求する。
AIが「一度の出力では書き切れない」と判断したときにサブエージェントが起動しやすくなります。
開発を爆速にする具体的なプロンプト3選
サブエージェントを確実に呼び出し、プロジェクトを前進させるための実践的なプロンプトを紹介します。これらはターミナル上のClaude Codeセッションに直接貼り付けて使用することを想定しています。AIが内部でどのようにタスクを分割し、サブエージェントを割り当てるかに注目してください。
1. 大規模なリファクタリングを完遂させる
コードベース全体で古い記法を駆逐し、モダンな書き方に統一させる指示です。複数のサブエージェントが各フォルダを巡回して修正を行います。
### プロンプト：大規模リファクタリング
プロジェクト全体の .ts ファイルを確認し、共通のバリデーションロジックを
src/utils/validation.ts に集約してください。
依存している全てのコンポーネントを修正し、
import 文の整合性が保たれているかサブエージェントを使って全件チェックしてください。
2. 未知のライブラリを含むバグを修正する
外部APIや不慣れなパッケージが原因のバグを、調査から修正まで一気通貫で依頼します。
### プロンプト：自律デバッグ
現在発生している Prisma の接続エラーを解消してください。
まず既存の schema.prisma と環境設定を分析し、
次にローカルの DB 接続状態をテストコマンドで確認してください。
修正案を作成し、実際にマイグレーションが通るまで自律的に試行してください。
3. プロジェクト全体のドキュメントを自動生成する
ソースコードを読み込み、常に最新の状態を反映したドキュメントを作成させる指示です。
### プロンプト：ドキュメント構築
全ファイルの JSDoc および関数定義をスキャンし、
docs/API.md にマークダウン形式のリファレンスを作成してください。
各エンドポイントの引数、戻り値、エラーレスポンスをテーブル形式で整理してください。
サブエージェントの動作をターミナルで監視する
サブエージェントが動いている間、開発者は何が起きているかを把握しておく義務があります。ターミナル上に流れるインジケーターやメッセージには、AIが直面している課題や進捗のヒントが詰まっています。AIに任せきりにせず、適切に介入するためのサインを見逃さないようにしましょう。
スピナーが示す作業の進行ステータス
ターミナルの隅で回っているスピナーは、サブエージェントが現在「思考中」なのか「ファイル書き込み中」なのかを示しています。
「Searching files…」という表示が出ているときは、広範囲なリサーチが行われています。この表示が長時間止まっている場合は、検索範囲が広すぎて迷っている可能性があるため、指示を具体化して再実行を検討してください。
子AIからの報告内容を読み解く
サブエージェントが作業を終えると、メインエージェントにその結果を渡します。画面には「Sub-agent finished with 5 changes」といった要約が表示されるはずです。
このとき、どのファイルがなぜ書き換えられたのか、メインエージェントが説明を行います。この報告内容を読み、自分の意図とズレがないかを最終確認するプロセスが、AI開発において最も重要です。
処理がループした際の強制終了コマンド
AIが同じファイルの修正を何度も繰り返したり、解決できないエラーで迷走し始めたりすることがあります。
Ctrl + Cを押すと、現在のエージェントプロセスを中断できます。- 中断後、何が問題だったのかをAIに問い正し、別のアプローチを指示します。
無制限にAIを走らせ続けるのではなく、進捗が止まったと感じたら即座に介入して軌道修正を図るのが、プロのAI使いのやり方です。
複数ファイルに跨るリサーチを任せるコツ
サブエージェントの性能は、与えられた「情報の見通し」に左右されます。情報の案内板を適切に配置してやることで、AIはより少ないトークンで正確な答えにたどり着けます。特にディレクトリ構造が複雑な場合や、大量の参考資料がある場合には、以下の下準備が効果を発揮します。
プロジェクト全体のディレクトリ構造を教える
作業を開始する前に、treeコマンドの結果などをAIに見せておくと、サブエージェントがどのフォルダを重点的に探すべきかのアタリをつけやすくなります。
「このプロジェクトはMVCモデルに基づいている」といった設計パターンの名前を伝えるのも有効です。AIが構造を予習しておくことで、不適切なファイルへのアクセスを減らし、結果として回答の速度が上がります。
関連するドキュメントをソースに含める
コードだけでなく、設計書や過去の議事録（Markdown形式）をリポジトリ内に配置しておきましょう。サブエージェントはこれらも「ソース」として読み込み、コードの意図を汲み取ります。
「この関数はAという仕様を満たすために作られた」といったメモ書きがあるだけで、修正の精度は格段に変わります。コード外にある「背景知識」をAIに共有することが、誤修正を防ぐ最大の防御策です。
探索の深さをプロンプトで制御する
「全ファイルを調べて」と言うよりも、「src/services フォルダを中心に、その呼び出し元を2階層先まで辿って」と範囲を限定してください。
| 指示のタイプ | サブエージェントの挙動 |
| 広域リサーチ | プロジェクト全体を浅くスキャンし、関連箇所をリストアップする |
| 集中リサーチ | 特定のフォルダを深く掘り下げ、すべてのロジックを解析する |
| 追跡リサーチ | 特定の変数の流れを、ファイル境界を超えて最後まで追いかける |
目的に合わせて探索の「深さ」と「幅」を指示し分けることで、効率的な並列処理が可能になります。
APIコストを抑えながら作業させる管理術
サブエージェントを動かすことは、複数のAIモデルを同時に走らせることに他なりません。これはつまり、通常のチャットよりもAPIの消費スピードが速くなることを意味します。稼ぐためにAIを使っているのに、コストで利益を圧迫しては本末転倒です。賢いエンジニアは、AIの出力を削ぎ落として最小限のコストで最大の結果を得る工夫をしています。
トークン消費が増える指示の共通点
「全てのファイルを一つずつレビューして」といった、対象範囲が不明確で網羅的な指示は最もコストがかかります。
AIが全てのファイルを読み込み、それぞれに対してサブエージェントを立てるため、一気に数千トークンが消費されます。「修正が必要な可能性のあるファイルだけをまず特定して」と、前段階を設けるだけでコストは劇的に下がります。
サブエージェントの無駄な生成を防ぐ設定
Claude Codeの設定や、指示の出し方一つで、サブエージェントの起動頻度を制御できます。
/compactコマンドをこまめに使い、会話のコンテキストを圧縮する。- 「一気にやらず、一つずつ確認を取りながら進めて」と指示し、並列動作を抑制する。
不必要な並列化を避けることで、メインエージェントだけで処理できるタスクを増やし、追加料金の発生を抑えられます。
予算制限とリアルタイムの使用量確認
Anthropicのコンソール側で、1日あたりの使用上限（Usage Limits）を設定しておくことは必須です。
また、ターミナル上で現在どれだけのトークンを消費したかを常に意識してください。想定よりコストがかかっている場合は、指示が広範すぎてサブエージェントが暴走気味であるサインかもしれません。
テストの自動実行と修正を繰り返す手順
サブエージェントを活用する最大のメリットは、「テストをパスするまで自力で這い上がる」自律性にあります。人間が修正とテストを往復する時間を、AIに完全に委託しましょう。以下の手順で指示を出すことで、サブエージェントがテストエンジニア兼コーダーとして機能します。
単体テストの結果をサブエージェントに渡す
「テストを実行し、失敗した箇所のログを解析して修正して」と指示します。
AIは自らテストコマンドを叩き、標準出力に出たスタックトレースを読み込みます。どこでアサーションが失敗しているかをサブエージェントが特定し、そのファイルを開いてロジックを修正します。
エラーログを元にした自律的なコード修正
サブエージェントは「なぜエラーが出たか」の仮説を立て、それを検証するためにコードを書き換えます。
修正後は再度テストを実行し、まだエラーが出るなら別のアプローチを試みます。この試行錯誤のプロセスを裏側でサブエージェントが代行してくれるため、人間は結果を待つだけで済みます。
修正完了後のコミットメッセージ自動作成
テストがすべてパスしたことを確認したら、そのまま /commit コマンドで記録を完了させます。
- 変更内容をAIに要約させる。
- テスト済みの事実をメッセージに含めるよう指示する。
「動くコード」と「適切な記録」をセットで納品させるのが、サブエージェント使いのゴールです。
まとめ：サブエージェントを司令塔として操る
Claude Codeのサブエージェントは、単なる補助機能ではなく、複雑なソフトウェア開発をAIで行うための心臓部です。司令塔であるメインエージェントを通じて、複数の作業員を適切に配置する感覚を身につければ、あなたの開発速度は何倍にも跳ね上がります。
- タスクを細分化して、サブエージェントが集中できる「狭いスコープ」を与える
- 自律的なテストと修正のループを任せ、自分は最終的なレビューに専念する
- コストを意識し、不必要な広域リサーチを避けるプロンプトを心がける
まずは、ファイルが3つ以上関係する少し複雑な修正を、「サブエージェントを2人立ち上げて解決して」というイメージで指示してみてください。AIが自律的に連携し、あなたの代わりにコードを組み上げていく快感を、ぜひ体験してください。
