ClaudeCodeのサブエージェント実践7手順

ClaudeCodeを使っていると、調査ログやテスト結果で会話が重くなり、「さっきの前提が抜けた」「レビューの観点が毎回ぶれる」と感じることがあります。そんなときに効くのがサブエージェントです。役割を分けて、調査、レビュー、テスト、修正案作成を別担当に任せると、メインの会話を汚さずに作業を進められます。

サブエージェントで何が変わるのか

通常のClaudeCodeは、ひとつの会話の中でファイルを読み、方針を考え、コードを書き、テスト結果も受け取ります。小さな修正なら問題ありませんが、プロジェクト全体を調べる作業では、読み込んだ情報が増えすぎて会話が散らかります。
サブエージェントは、この散らかりやすい作業を別の文脈で処理します。たとえば「テスト失敗の原因だけ調べる担当」「セキュリティ観点で見る担当」「READMEを直す担当」を分けると、各担当は自分の作業に集中し、メインの会話には結果だけが返ります。
初心者にとって一番大きいメリットは、失敗しても原因を切り分けやすいことです。全部を一人のAIに任せると、どこで判断がずれたのか見えにくくなります。役割を分けると、「レビュー担当の指示が弱い」「テスト担当に編集権限を渡しすぎた」といった修正点がすぐ見えます。

最初に作るならコードレビュー担当が安全

いきなり実装担当を作るより、最初は読み取り専用のコードレビュー担当が向いています。理由は単純で、ファイルを書き換えないため、失敗してもプロジェクトを壊しにくいからです。
ClaudeCodeで/agentsを実行し、新しいエージェント作成を選びます。保存先をProjectにすると、そのプロジェクトの.claude/agents/に保存されます。チームで使うレビュー担当ならProject、個人の全プロジェクトで使うならPersonalを選びます。
説明文には、ただ「レビューする」ではなく、「コード変更後に、可読性、バグの可能性、セキュリティ、テスト不足を確認し、重大度ごとに指摘する」と書くと動きが安定します。ClaudeCodeはこの説明文を見て、どの作業を任せるか判断します。ここが曖昧だと、呼ばれたり呼ばれなかったりします。

説明文は自動起動のスイッチになる

サブエージェントのdescriptionは、名前より重要です。ClaudeCodeは「この依頼は誰に任せるべきか」をdescriptionで判断します。
たとえばレビュー担当なら、「コードを変更した直後に必ず使用する」「差分を読み、危険度順に指摘する」と書くと、レビュー場面で選ばれやすくなります。逆に「便利な開発支援をする」のように広すぎる説明だと、他の担当との境界がぼやけます。

ツールは最小限から始める

レビュー担当に編集権限は不要です。Read、Grep、Globのような読み取り系だけで始めると安全です。Bashを許可する場合も、差分確認やテスト確認に用途を絞ります。
初心者がやりがちな失敗は、「便利そうだから全部許可する」ことです。ツールを増やすほど、意図しないファイル変更や重いコマンド実行の可能性が上がります。最初は狭く作り、必要になったら増やす順番が安全です。

作成から利用までの基本手順

次の流れなら、初めてでも迷いにくく、あとから修正もしやすくなります。

一度で完璧に作ろうとしなくて大丈夫です。最初のテストでは、わざと小さな変更を作り、「重大な問題」「中程度の問題」「軽微な改善」に分けて返すように頼むと、レビュー品質を判断しやすくなります。

手動ファイルで作るときの注意点

手動で作る場合は、.claude/agents/の中にMarkdownファイルを置きます。ファイルの先頭にはYAMLフロントマターを書き、その下に担当者への指示を書きます。
ここで多いミスが、先頭行の前に余計な空白を入れることです。フロントマターが正しく読まれないと、作ったはずのサブエージェントが一覧に出ません。作ったのに呼べない場合は、ファイル先頭、name、description、保存場所を確認します。
ファイル名とnameは、なるべく短く具体的にします。code-reviewer、test-investigator、docs-maintainerのように役割が見える名前にすると、呼び出すときに迷いません。

自動で任せるか、名前で呼ぶか

サブエージェントの使い方には、自然に任せる方法と、名前を指定する方法があります。
自動で任せたい場合は、「この変更をレビューして」「テスト失敗の原因を調べて」のように普通に依頼します。descriptionが合っていれば、ClaudeCodeが適切な担当を選びます。
確実に使いたい場合は、エージェント名を指定します。重要なレビュー、リリース前確認、セキュリティチェックでは明示的に呼ぶほうが安全です。自動起動は便利ですが、必ず狙い通りに動くわけではありません。

並列実行が向いている場面

並列実行は、互いに依存しない調査で力を発揮します。たとえば、フロントエンド担当、バックエンド担当、テスト担当を同時に走らせると、待ち時間を減らせます。
ただし、同じファイルを複数の担当が同時に編集する作業には向きません。競合が起きると、どの変更を採用すべきか判断が難しくなります。並列にするのは調査やレビュー、順番にするのは実装や修正、という分け方が現実的です。
バックグラウンド実行を使うと、テストや広範囲の調査を進めながら、メインの会話で別の相談ができます。短いテストやログ解析には便利ですが、長時間の重い処理では進捗確認の言葉を途中で入れると安心です。

モデルとコストの考え方

すべてのサブエージェントに高性能モデルを使う必要はありません。軽い探索、形式チェック、定型レビューは低コストのモデルで十分なことが多いです。複雑な設計判断、仕様の衝突、セキュリティ判断は高性能モデルに任せると安心です。
実務では、メインの会話で方針を考え、サブエージェントに調査やレビューを任せる形が扱いやすいです。考える役と動く役を分けると、会話の見通しがよくなり、トークン消費も読みやすくなります。
作業量が増えてきたら、/costで消費量を確認します。急にコストが増える場合は、サブエージェントが広すぎる範囲を読んでいるか、不要なツールを使っている可能性があります。

権限と安全対策で事故を防ぐ

サブエージェントは便利ですが、権限設計を間違えると危険です。レビュー担当に編集権限を渡す必要はありません。デバッグ担当に編集を許可する場合でも、対象ディレクトリや作業内容を明確にします。
大きな変更の前には、必ずgitで現在の状態を保存します。変更前の状態が残っていれば、サブエージェントの提案が期待と違っても戻せます。
実験的な修正や複数案の比較では、worktree分離が役立ちます。メインの作業ツリーから切り離した場所で試せるため、失敗しても本体に直接影響しにくくなります。読み取り専用レビューには不要ですが、リファクタリング案を試す場面では有効です。

ClaudeCodeのサブエージェントの使い方に関する疑問解決

Skillsとの違いは何か？

Skillsは、ClaudeCodeに手順や知識を追加する仕組みです。サブエージェントは、ClaudeCodeの中に別の担当者を作る仕組みです。
判断基準は、作業の文脈を分けたいかどうかです。メインの会話に試行錯誤を残したくないならサブエージェント、同じ会話内で使う手順を増やしたいならSkillsが向いています。

CLAUDE.mdとの違いは何か？

CLAUDE.mdはプロジェクト全体の共通ルールです。サブエージェントは特定の役割に合わせた個別ルールです。
たとえば、全体の命名規則はCLAUDE.mdに置きます。レビュー担当だけが見る重大度基準や出力形式は、サブエージェント側に置きます。共通ルールと役割別ルールを混ぜないことで、あとから修正しやすくなります。

メモリは使うべきか？

同じプロジェクトで何度も使う担当なら、メモリは役立ちます。過去に見つけた設計判断、よくあるバグ、レビューで重視する観点を残せるため、次回以降の精度が上がります。
ただし、顧客情報、秘密鍵、個人情報は保存しないほうが安全です。チームで共有するメモリには、誰が見ても問題ない設計知識だけを残します。

初心者が最初につまずく落とし穴

作ったはずの担当者が一覧に出てこない

ClaudeCodeの画面で

を実行し、「作成したはずのコードレビュー担当を選ぼう」としたのに、一覧に名前が表示されない。初心者が最初にかなり高い確率でぶつかるのがこれです。
原因はだいたい2つです。1つ目は、保存場所を間違えていること。2つ目は、手動で作ったMarkdownファイル（文章を書くためのファイル）の先頭に余計な空白や文字が入っていて、ClaudeCodeが「これはサブエージェント設定だ」と読めていないことです。
こうすれば一発で確認できます。

ぶっちゃけ、最初は手動作成より

から作るほうが安全です。画面の質問に答えていけば設定ファイルを作ってくれるので、1回目はそれで十分です。

レビュー担当に頼んだのに普通のClaudeCodeが答えてしまう

「コードレビュー担当を作ったから、これで毎回勝手にレビューしてくれるはず」と思って、変更後に「見て」とだけ入力する。すると、サブエージェントではなく、いつものClaudeCodeが普通に返事をしてしまう。このパターンもかなり多いです。
原因は、依頼文が曖昧すぎることです。ClaudeCodeは

（担当者の仕事説明）を読んで判断しますが、「見て」だけでは、レビューなのか、説明なのか、修正なのか判断できません。
解決策は、最初の10回だけ明示的に呼ぶことです。

初心者のうちは、自動起動に期待しすぎないほうがいいです。まずは名前を指定して呼ぶ。これだけで成功率がかなり上がります。

何を任せればいいかわからなくなる

で作成画面まで進んだのに、「どんな担当者を作りますか？」と聞かれた瞬間に手が止まる。レビューもテストもドキュメントもやらせたくなって、結局「開発を助ける万能担当」と書いてしまう。これは初心者あるあるです。
原因は、サブエージェントを「強いAIをもう1体増やす機能」だと思ってしまうことです。実際は、狭い仕事を安定して繰り返すための担当者です。コンビニで、レジ、品出し、清掃を1人に全部任せるより、担当を分けたほうがミスが減るのと同じです。
最初は次の1つだけ作れば十分です。

最初から3体作らなくて大丈夫です。1体を7日間使って、「毎回同じ観点で見てくれる」と感じてから増やすほうが、結果的に早いです。

「知っている」と「できる」の差を埋める実践ロードマップ

1日目まず1個だけ担当者を作る

やることは、コードレビュー担当を1個作るだけです。ClaudeCodeをプロジェクトのフォルダで開き、

を実行します。新規作成を選び、保存先はProjectにします。説明には「コード変更後に、バグの可能性、読みやすさ、テスト不足を確認するレビュー担当」と入力します。
所要時間は15分です。完了の判断基準は、

の一覧に作った担当者名が表示されることです。ここでコードの修正までやろうとしなくて大丈夫です。1日目は「存在を確認できたら勝ち」です。

2日目小さな差分をレビューさせる

2日目は、わざと小さな変更を1つ作ります。たとえばREADMEの1行を直す、コメントを1行足す、変数名を1つ変える程度で十分です。そのあとClaudeCodeに「code-reviewerを使って、直近の変更差分をレビューしてください」と入力します。
所要時間は20分です。完了の判断基準は、レビュー結果が3つ以内の指摘で返ってくることです。大量に返ってきたら、担当者への指示が広すぎます。その場で「指摘は最大3件にしてください」と追加します。

3日目出力形式を固定する

3日目は、毎回同じ形で返してもらう設定にします。サブエージェントの指示文に「出力は、問題点、理由、修正案、優先度の順に書く」と追記します。これは、毎回レビュー結果の読み方で迷わないためです。
所要時間は15分です。完了の判断基準は、レビュー結果が毎回同じ順番で表示されることです。形式が安定すると、仕事で使うときのストレスが一気に減ります。

4日目編集権限を渡さない運用に慣れる

4日目は、あえて修正を任せません。レビュー担当には「変更はしないで、指摘だけしてください」と依頼します。サブエージェントの場面で、読み取りだけをさせると、ファイルが勝手に変わる不安が減ります。
所要時間は10分です。完了の判断基準は、レビュー後にファイル差分を見ても、サブエージェントによる変更が発生していないことです。初心者はまず「壊さない使い方」を体に覚えさせるのが大事です。

5日目テスト失敗の調査だけ任せる

5日目は、テストがあるプロジェクトで、テスト結果の読み取りを任せます。ClaudeCodeの場面で「テスト失敗の原因だけを調べて、修正はしないでください」と入力します。テスト（動作確認の自動チェック）のログは長くなりがちなので、サブエージェントに任せる価値が出やすいです。
所要時間は25分です。完了の判断基準は、「どのテストが失敗したか」「原因候補は何か」「次に見るファイルはどれか」が返ることです。修正コードまで出してきたら、「調査だけ」と再指定します。

6日目自動起動ではなく明示呼び出しで3回使う

6日目は、明示的に名前を指定して3回使います。レビュー、テスト調査、ドキュメント確認のように、違う場面で同じ担当を使ってみます。名前を指定して呼ぶ癖をつけると、意図しない動作が減ります。
所要時間は30分です。完了の判断基準は、3回中3回、目的の担当者が動いたとわかる返答になることです。1回でも普通のClaudeCodeが答えたように見えたら、依頼文の先頭に担当者名を入れ直します。

7日目使い続けるか削るか判断する

7日目は、作った担当者が本当に役に立ったか確認します。過去6日間のレビュー結果を見て、「同じ指摘が安定して出たか」「読む時間が減ったか」「ファイルを壊さなかったか」を確認します。
所要時間は20分です。完了の判断基準は、「残す」「直す」「消す」のどれかを決めることです。残すならdescriptionを少し具体化します。直すなら出力形式を短くします。消すなら、まだその担当は早かったというだけです。失敗ではありません。

現実でよくある「あるある失敗」と専門家の対処法

失敗1万能エージェントを作って結局使わなくなる

初心者は最初に「開発全般を助ける担当」「品質を上げる担当」「何でも相談できる担当」を作りがちです。作った直後は便利そうに見えますが、実際の場面で、何を頼めばいいのかわからなくなります。
根本原因は、役割が広すぎることです。サブエージェントは専門店です。ラーメンも寿司もカレーも出す店より、レビューだけやる店のほうが味が安定します。
専門家ならこう対処します。まず名前を

のように狭くします。次に、仕事を「変更後の差分レビューだけ」に限定します。最後に、出力を「問題点、理由、修正案」の3つに固定します。
予防策は、作成前に「この担当者は何をしないのか」を1つ決めることです。レビュー担当なら「修正しない」。調査担当なら「結論だけ返して、編集しない」。この禁止事項があると、役割がブレません。

失敗2編集権限を渡しすぎて差分が怖くなる

「便利そうだから全部のツールを許可しておこう」と設定し、レビューだけ頼んだつもりなのに、ファイルの書き換え案まで進んでしまう。あとで差分を見たら、想定外のファイルまで変わっていて焦る。これもかなりリアルな失敗です。
根本原因は、権限（できる操作の範囲）を仕事に合わせていないことです。読み取りだけでいい担当に編集道具を渡すのは、資料チェック係に会社の金庫の鍵まで渡すようなものです。
専門家なら、最初にツールを絞ります。レビュー担当はRead、Grep、Globのような読み取り中心にします。修正担当を作る場合も、いきなり本番ファイルを触らせず、先に「修正方針だけ出す」段階を挟みます。
予防策は、実行前に「この担当者はファイルを書き換える必要があるか？」と1回だけ確認することです。答えがNoなら編集系ツールは不要です。迷ったら渡さない。これが一番安全です。

失敗3結果が長すぎて読む気がなくなる

サブエージェントにレビューを頼んだら、20個以上の指摘が返ってきて、結局どれから直せばいいかわからない。初心者は真面目なので全部読もうとしますが、5分で疲れます。
根本原因は、出力の上限を決めていないことです。AIは親切にたくさん返そうとします。でも実務では、全部の指摘より「最初に直すべき3つ」のほうが価値があります。
専門家なら、依頼文に「最大3件」「重大度順」「今すぐ直すものだけ」と入れます。たとえば、レビューの場面で「code-reviewerを使って、直近の変更差分を確認し、今すぐ直すべき問題を最大3件だけ返してください」と入力します。すると、読む量が減り、次の行動が決まりやすくなります。
予防策は、出力形式に制限を入れることです。「最大3件」「1件につき150文字以内」「最後に次の一手を1行で書く」のように数字で縛ります。数字を入れると、結果の読みやすさがかなり安定します。

ぶっちゃけこうした方がいい！

ぶっちゃけ、初心者は最初からサブエージェントを使いこなそうとしなくていいです。最初の目標は、「すごい自動化」ではなく、怖くない範囲で1回成功することです。
一番コスパがいい近道は、コードレビュー担当を1個だけ作って、7日間それだけ使うことです。テスト担当、設計担当、ドキュメント担当を増やすのはその後で大丈夫です。最初から増やすと、どの担当が役に立ったのか判断できません。
ぶっちゃけ、自動起動も最初は期待しなくていいです。名前を指定して呼んでください。「code-reviewerを使って」と書けば、迷いが減ります。慣れてからdescriptionを調整して、自動で動くように寄せれば十分です。
ぶっちゃけ、編集権限も最初はいりません。最初の1週間は読み取り専用でいいです。レビューしてもらい、自分で直す。この流れのほうが、何が変わったか理解できます。AIにいきなり直させると、動いたけど理由がわからない状態になりやすいです。
ぶっちゃけ、きれいな設計より「毎回同じ形で返ってくること」のほうが大事です。問題点、理由、修正案。この3つだけで十分です。レビュー結果が毎回この順番で返るだけで、仕事に使える感覚が出てきます。
最初の完成形は、かなり地味でいいです。コード変更後の場面で、レビュー担当を名前で呼ぶ。返ってきた3件を見る。1件だけ直す。もう一度レビューする。この30分の流れができれば、もう「知っているだけ」の状態は抜けています。
サブエージェントは、最初から魔法の開発チームにしようとすると失敗します。まずは、隣に座って差分だけ見てくれる先輩を1人作る。その先輩が毎回そこそこ役に立つようになったら、テストを見る人、ドキュメントを見る人を増やす。この順番が一番ラクで、一番長続きします。

よくある質問

作ったサブエージェントが表示されないのはなぜ？

保存場所、ファイル先頭、name、descriptionを確認します。特に、YAMLフロントマターの前に空白や不要な文字があると読み込まれません。/agentsで再確認し、手動作成した場合はセッションを開き直すと認識されることがあります。

自動で呼ばれないときはどうする？

descriptionを具体的に直します。「いつ使うか」「何を調べるか」「どんな形式で返すか」を入れると選ばれやすくなります。それでも重要な場面では、名前を指定して呼びます。自動起動だけに頼るより、明示呼び出しを併用するほうが安定します。

最初に何個作ればいい？

最初は一個で十分です。おすすめはコードレビュー担当です。次に、テスト失敗調査担当、ドキュメント整備担当の順で増やすと、役割の違いを体感しやすくなります。最初から万能担当を作ると、通常のClaudeCodeと変わらなくなります。

チームで共有しても大丈夫？

Projectに保存したサブエージェントは、リポジトリに含めればチームで共有できます。ただし、APIキー、社内トークン、顧客名などは書かないでください。必要な値は環境変数で扱い、エージェント定義には操作ルールだけを書きます。

編集できる担当を作っても安全？

安全にできますが、最初から広い権限を渡さないことが条件です。まず読み取りで原因を調べさせ、修正方針が納得できたら編集を許可します。大きな修正では、事前にgitで保存し、差分を確認してから採用します。

まとめ

ClaudeCodeのサブエージェントは、難しい機能に見えて、考え方はシンプルです。ひとつのAIに全部を任せるのではなく、作業ごとに担当を分けるだけです。
最初の一歩は、読み取り専用のコードレビュー担当を作ることです。descriptionに使う場面を具体的に書き、ツールを最小限にし、小さな差分で試します。うまく動いたら、テスト調査、ドキュメント整備、セキュリティ確認へ広げます。
サブエージェントを使いこなすコツは、万能化しないことです。一担当一役割、ツールは最小限、重要作業は明示呼び出し。この三つを守るだけで、ClaudeCodeはただのチャット相手ではなく、実務で使える小さな開発チームに変わります。