ハブネコのAIラボ

Claude Code

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

公開: / 更新: ・読了目安8分

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

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

先に結論: サブエージェントに調査や修正を任せると独立したコンテキストで処理が完結し、メイン会話には要約だけが返ります。Explore・Plan・general-purposeは組み込み済みで、独自の役割は.claude/agents/にMarkdownを置いて追加できます。

Claude Codeの「サブエージェント」は、独立したコンテキストウィンドウで動く補助エージェントです。ログや検索結果で本体の会話が埋まってしまう作業を任せると、要約だけが返ってきてメインの文脈がきれいなまま保たれます。

本記事ではサブエージェントの仕組み、組み込みエージェントの使い方、.claude/agents/でのカスタム作成手順、並列活用の実例までをまとめます。

設定全体の基本は「Claude Code設定完全ガイド」もあわせてご覧ください。

この記事の要点

  • サブエージェントは独立したコンテキストウィンドウで動き、メイン会話には結果の要約だけが返ります。
  • 組み込みサブエージェントにはExplore(読み取り専用)・Plan・general-purposeがあります。
  • カスタムサブエージェントは.claude/agents/または~/.claude/agents/にYAMLフロントマター付きMarkdownで作成します。
  • 必須項目はnameとdescriptionのみで、toolsを指定すれば使えるツールを制限できます。
  • modelにはsonnet/opus/haiku/fableなどのエイリアスやinheritを指定できます。

前提・動作環境

サブエージェントはClaude Code CLIのセッション内で動作し、カスタムサブエージェントの定義は.claude/agents/(プロジェクト単位)または~/.claude/agents/(全プロジェクト共通)にMarkdownファイルとして置きます。

本記事の例はWindows(PowerShell/Git Bash)を前提にしていますが、macOS/Linuxでも考え方は共通です。バージョンによって細部の挙動が異なることがあるため、最新仕様は公式サイトで確認してください。

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

Claude Codeのメイン会話は1つのコンテキストウィンドウを使い回します。大量のログを読んだり、何十ファイルもgrepしたりすると、その内容がすべて履歴に積み上がり、後の応答品質やコストに影響します。

サブエージェントに切り出すと、その調査作業は専用のコンテキストウィンドウの中で完結し、メイン会話には結果の要約だけが返ってきます。

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

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

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

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

組み込みサブエージェント3種の比較図解: Exploreは読み取り専用の高速検索、Planはプランモード専用の調査、general-purposeは調査と修正の両方を行う

これらは自動委任されるので、依頼するときは特別な構文を覚える必要はありません。たとえば次のように頼めば、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、と使い分けるとよいでしょう。

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

バグイヌバグイヌ

サブエージェントにファイル編集をお願いしたのに、なぜかEditツールが使えないと言われてしまいました…!

ハブネコハブネコ

toolsを指定すると、そこに書かれていないツールは使えなくなります。必要なツールを列挙し忘れていないか確認してください。

よくある質問

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

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

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

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

個人だけで使いたい場合は~/.claude/agents/に置きます。

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

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

modelにHaikuなど軽量モデルを指定してコストを抑える方法もあります。

ハブネコ

ハブネコのひとこと

サブエージェントに任せると会話がすっきり保たれるのは実感していますが、並列で走らせすぎると要約の合計量が増えて逆にかさばることもあるので、独立した調査に絞って使うようにしています。

まとめ

サブエージェントは、メイン会話とは別のコンテキストウィンドウで動く補助エージェントで、大量の出力や独立した調査をメインの文脈から切り離すために使います。

Exploreやgeneral-purposeなどの組み込みエージェントはそのまま使え、繰り返す役割は.claude/agents/*.mdにname・description・tools・modelを書いてカスタム化できます。

独立した調査は並列に任せると効率的ですが、頻繁なやり取りが必要な作業や単純な修正はメイン会話のままで十分です。

同じ考え方をCLIの外で自作アプリに組み込みたい場合は、「Claude Agent SDK」でエージェントやサブエージェントの設計を応用できます。

実際に並行して記事を書かせた実例は「Claude Codeでブログを収益化する」で紹介しています。完了報告を受け取ったあとの検証手順は「サブエージェントの「完了しました」を信じない」で解説しています。

あわせて「Claude Code設定完全ガイド」「Skillsの作り方」「プラグイン導入ガイド」もご覧ください。