AI Hub

Claude Codeサブエージェント活用術｜並列作業と作り方解説

公開:

#サブエージェント #使い方

Claude Codeの「サブエージェント」は、独立したコンテキストウィンドウで動く補助エージェントです。ログや検索結果で本体の会話が埋まってしまう作業を任せると、要約だけが返ってきてメインの文脈がきれいなまま保たれます。本記事ではサブエージェントの仕組み、組み込みエージェントの使い方、.claude/agents/でのカスタム作成手順、並列活用の実例までをまとめます。設定全体の基本は「Claude Code設定完全ガイド」もあわせてご覧ください。

前提・動作環境

サブエージェントはClaude Code CLIのセッション内で動作し、カスタムサブエージェントの定義は.claude/agents/(プロジェクト単位)または~/.claude/agents/(全プロジェクト共通)にMarkdownファイルとして置きます。本記事の例はWindows(PowerShell/Git Bash)を前提にしていますが、macOS/Linuxでも考え方は共通です。バージョンによって細部の挙動が異なることがあるため、最新仕様は公式サイトで確認してください。

サブエージェントとは何か

Claude Codeのメイン会話は1つのコンテキストウィンドウを使い回します。大量のログを読んだり、何十ファイルもgrepしたりすると、その内容がすべて履歴に積み上がり、後の応答品質やコストに影響します。サブエージェントに切り出すと、その調査作業は専用のコンテキストウィンドウの中で完結し、メイン会話には結果の要約だけが返ってきます。

サブエージェントには次のような利点があります。

Claudeはリクエストの内容とサブエージェントのdescriptionを照らし合わせ、当てはまれば自動的に委任します。委任先のサブエージェントは、メイン会話の履歴やこれまでに読んだファイルを一切引き継がず、ゼロからその場のタスクに取り組みます。

組み込みサブエージェントと依頼の仕方

Claude Codeにはあらかじめ用意された組み込みサブエージェントがあり、自分で定義しなくてもすぐ使えます。代表的なものは次のとおりです。

これらは自動委任されるので、依頼するときは特別な構文を覚える必要はありません。たとえば次のように頼めば、Claudeが適切な組み込みエージェントを判断して使います。

認証まわりの実装を調べて、この会話には要点だけ教えてください

特定のサブエージェントを明示的に使わせたい場合は、名前を挙げて依頼するか@でメンションします。

Use the Explore agent to find where the rate limiter is implemented

カスタムサブエージェントの作り方

繰り返し同じ役割のサブエージェントを立ち上げているなら、カスタム定義を作ると効率的です。ファイルはYAMLフロントマター付きのMarkdownで、.claude/agents/(プロジェクト単位)か~/.claude/agents/(個人利用)に置きます。

---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューします。編集後に使用してください。
tools: Read, Glob, Grep
model: sonnet
---

あなたはコードレビュアーです。呼び出されたら対象コードを分析し、
品質・セキュリティ・ベストプラクティスの観点で具体的な指摘を返してください。

必須項目はnameとdescriptionだけです。descriptionはClaudeが自動委任を判断する材料になるため、どんな場面で使うかを具体的に書くのがコツです。toolsを省略するとメイン会話で使えるツールを一通り引き継ぎ、指定すればその範囲に制限できます。modelはsonnet・opus・haiku・fableなどのエイリアスかinheritを指定でき、省略時はメイン会話のモデルを引き継ぎます。

作成はClaudeに直接お願いするのが手早い方法です。

~/.claude/agents/ に、読みやすさ・パフォーマンス・ベストプラクティスの
観点でコードを改善提案するpersonalなサブエージェントを作ってください。
読み取り専用にして、モデルはSonnetを使ってください。

なお/agentsコマンドは以前は対話式の作成ウィザードでしたが、現在は「Claudeに頼むか.claude/agents/を直接編集してください」という案内を表示するだけになっています。ファイルの配置やフロントマターの仕様自体は変わっていないので、手書きでも問題なく作成できます。プラグインとして配布されているサブエージェントもあり、「プラグイン導入ガイド」で紹介する仕組みで導入すればプロジェクトをまたいで共有できます。

並列活用の実例

独立した調査を複数任せたいときは、サブエージェントを並列で走らせるのが効果的です。

認証モジュール・データベースモジュール・APIモジュールを、
それぞれ別のサブエージェントを使って並行して調べてください

各サブエージェントは互いに干渉せずそれぞれの領域を探索し、終わり次第結果をメイン会話に返します。Claudeはそれらを踏まえて調査結果を統合します。この方法は調査対象同士に依存関係がない場合に特に向いており、一つずつ順番に調べるより体感の待ち時間を大きく縮められます。ただし各サブエージェントの結果は要約とはいえメイン会話のコンテキストに戻ってくるため、同時に走らせる数が多いほど戻ってくる文脈量も増える点には注意が必要です。

使いどころと使わないほうがいい場面

サブエージェントが向くのは次のような場面です。

逆に、メイン会話で進めたほうがよい場面もあります。

また、サブエージェントは毎回まっさらなコンテキストで始まる独立エージェントですが、メイン会話の中で再利用できるプロンプトや手順を整えたいだけなら「Skillsの作り方」で紹介するSkillsのほうが適しています。両者は目的が異なるため、コンテキストを切り離して働かせたいならサブエージェント、メインの会話に知識や手順を持ち込みたいならSkills、と使い分けるとよいでしょう。

つまずきポイント/よくあるエラー

よくある質問

サブエージェントとメインのClaudeはどう違いますか?

メインの会話はセッション全体の履歴を引き継ぎますが、サブエージェントは委任された時点から独立したコンテキストで動き、終了時に結果を返してメイン会話に統合されます。過去の会話内容や読み込んだファイルは自動では引き継がれません。

カスタムサブエージェントはチームで共有できますか?

できます。.claude/agents/に置いてバージョン管理にコミットすれば、プロジェクトを使う全員が同じ定義を利用できます。個人だけで使いたい場合は~/.claude/agents/に置きます。

サブエージェントを使いすぎるとコストが増えませんか?

サブエージェントごとに新しいコンテキストとモデル呼び出しが発生するため、無闇に多用するとコストは増えます。出力が大量になる作業や、独立して並列化できる調査など、切り出す効果が大きい場面に絞って使うのがおすすめです。modelにHaikuなど軽量モデルを指定してコストを抑える方法もあります。

まとめ

サブエージェントは、メイン会話とは別のコンテキストウィンドウで動く補助エージェントで、大量の出力や独立した調査をメインの文脈から切り離すために使います。Exploreやgeneral-purposeなどの組み込みエージェントはそのまま使え、繰り返す役割は.claude/agents/*.mdにname・description・tools・modelを書いてカスタム化できます。独立した調査は並列に任せると効率的ですが、頻繁なやり取りが必要な作業や単純な修正はメイン会話のままで十分です。あわせて「Claude Code設定完全ガイド」「Skillsの作り方」「プラグイン導入ガイド」もご覧ください。