初めてサブエージェントを使ったとき、私は使い方を間違えた。変数の名前を変えるためにサブエージェントを起動した。変数1つのために。電球を替えるために業者を呼ぶようなもので — 遅く、高くつき、どこかおかしい。だから Claude Code でサブエージェントを設定する方法を見せる前に、使うべきでないときについてはっきり言っておきたい。
サブエージェントとは、メインセッションがタスクを委託できる独立した Claude インスタンスだ。専用のコンテキストウィンドウ — 白紙のキャンバス — を持ち、仕事を完了してサマリーを返す。キーワードは独立。サブエージェントの作業はメイン会話を汚さない。10個のファイルを探索して読み込んでも、メインセッションには結論だけが届く。
これがサブエージェントのすべての意義であり、だからこそ多くの初心者が誤用する。
サブエージェントが本当に役立つとき
タスクがメインコンテキストに不要な情報を大量に流し込みそうなとき、サブエージェントが役立つ。
大きなコードベースで「authをどこで処理しているか？」を探す場面を考えてみよう。サブエージェントなしでは、Claude はメイン会話に15個のファイルを読み込み、それらがセッション中ずっとコンテキストに残り、毎回のやり取りでトークンを消費し続ける。サブエージェントを使えば、その探索は使い捨てのウィンドウで行われる。返ってくるのは「authは src/auth/ にあり、こういう流れです」という3文だけ — 15ファイルではなく。
つまり、サブエージェントが真価を発揮するのは、作業が探索的（大量の読み取り、小さな結論）または並列的（複数の独立したことを同時に）なときだ。検索、調査、大きなテストスイートを走らせて失敗をまとめる、チェックリストに基づいたdiffのレビュー — これらはどれも完璧な使用例だ。
今私が使っているテストはこれだ。自分に問いかける：このタスクは多く読んで少ししか生産しないか？ イエスならサブエージェント。タスクがすでにやり方の見えている直接的な編集なら、インラインでやる。変数のリネームは何も読まず、正確な変更1つを生む。サブエージェント不要。
使うべきでないとき
理解できている単一ファイルの編集にサブエージェントを使ってはいけない。各ステップが前のステップを見ることに依存する順次作業にも使わない。そして、洗練して聞こえるからという理由だけで使ってもいけない。サブエージェントには必ずオーバーヘッドがある — 起動し、独自のコンテキストを構築し、報告して戻る。小さな仕事では、そのオーバーヘッドが節約分より多くかかる。
新しい Claude モデルも、自発的にサブエージェントを生成することについてかなり慎重で、それは通常正しい。委任が欲しければ、明示的に求めるか設定する必要があることが多い。それが設定方法という問いにつながる。
カスタムサブエージェントの設定
Claude Code では、名前付きサブエージェントをファイルとして定義できる。プロジェクトの .claude/agents/ にMarkdownファイルを置くだけだ（グローバルにはホームコンフィグに）。私がコードレビューに使っている実際のファイルを紹介する：
---
name: reviewer
description: Reviews a diff for bugs and missing edge cases. Use after writing code, before committing.
tools: Read, Grep, Bash
---
You are a focused code reviewer. Given a diff or a set of changed files:
1. Read the changed code and the files it touches.
2. Look for actual bugs — off-by-one, null handling, wrong async behavior.
3. Check for missing edge cases and untested paths.
4. Report findings as a short list, each with a severity (high/medium/low).
Don't rewrite the code. Don't nitpick style. Report what you find and stop.
指摘しておきたいことがいくつかある。description の行は飾りではない — Claude がこのエージェントにいつ委任するかを決める根拠だ。ツールの説明を書くように書く：何をするかだけでなく、いつ使うかを書く。「コードを書いた後、コミットする前に使う」は Claude に具体的なトリガーを与える。
tools の行はサブエージェントが触れるものを絞り込む。私のレビュワーは Read、Grep、Bash を持つ — 検査とテスト実行には十分で、編集はできない。これは意図的だ。レビュワーはコードを変更すべきでない。ツールリストを絞ることでサブエージェントを仕事に集中させ、心配事を一つ減らせる。
本文はサブエージェントのシステムプロンプト — その全人格と役割だ。具体的で範囲が限定されていることに注目してほしい。「見つけたことを報告して止まれ」は重要で、そうでないと熱心なサブエージェントが修正を始め、頼んでいない変更が生まれる。
使い方
ファイルが存在すれば、セッション内でこう呼び出せる：
reviewer サブエージェントを使って最後のコミットをチェックして。
Claude がそれを起動し、サブエージェントが自分のコンテキストで読み取りと報告を行い、15ファイルがメイン会話に流れ込むことなく、きれいな所見リストが返ってくる。探索だけならカスタムファイル不要で、組み込みの汎用サブエージェントが「Xを調べてきて」系のアドホックタスクをうまく処理してくれる。
考え方の転換
これが最終的に私にとってサブエージェントをわかりやすくしたことだ。「より強力な Claude」として考えるのをやめる。彼らは賢くなるわけではない。彼らは、厄介な作業をどこか別の場所に送ることで、メインコンテキストをきれいに保つための方法だ。
そう見えれば、「いつ使うか」の問いは自ずと答えが出る。散らかった、読み取り主体の、使い捨ての作業？委任する。すでに想像できる正確な作業？ただやる。テストを走らせて所見リストを渡すレビュワー — 素晴らしい。電球を替えるための業者 — そこまでではない。
今週、サブエージェントを1つ書こう。上のレビュワーを作ろう。次のコミットで動かしてみよう。そうすれば違いが感じられ、次にいつ使えばいいか正確にわかるようになる。