Claude Code は、ターミナルで動くコーディング用 AI です。便利なのは 1 対 1 の対話だけではありません。メインのセッションが「サブエージェント（sub-agent）」という小さな別の AI を呼び出し、複数の作業を分担・並行させられます。大きなタスクを速く、しかも散らからずに進めるための仕組みを、初めての人にも分かるように整理します。
FIG.1 メインが指示を配り、各エージェントが別々の文脈で作業し、結果だけが戻る
01サブエージェントとは何か
サブエージェントは、特定の役割を持った Claude の分身です。メインのセッション（オーケストレーター＝指揮役）が呼び出すと、その分身は自分専用の文脈（コンテキスト）・専用の指示文・使える道具の範囲を持って動き、終わったら結果だけをメインに返します。
ポイントは 2 つです。1 つは文脈の分離。長い調べ物や試行錯誤を分身の中で完結させるので、メインの会話が余計な情報で散らかりません。もう 1 つは役割の専門化。「レビュー専門」「テスト専門」のように指示を絞ると、その作業だけに集中して質が安定します。さらに複数を同時に走らせれば、独立した作業を並行処理できます。
サブエージェントの本質は、文脈を分けて散らからせず、役割を絞って質を保つこと。並列はその副産物。
02どこで定義するか
サブエージェントは、YAML の見出し（フロントマター）＋指示文を書いた Markdown ファイルとして用意します。置き場所は 2 か所あり、用途で使い分けます。
| プロジェクト用（.claude/agents/） | ユーザー用（~/.claude/agents/） |
|---|---|
| そのリポジトリ専用。Git に commit してチームで共有・改善できる | 個人用。どのリポジトリでも自分について回る |
| 例：このプロジェクトの規約に沿ったレビュアー | 例：自分がいつも使うテスト書き |
同じ名前があればプロジェクト用が優先されます。まずは.claude/agents/にチーム共有のものを置く、という運用が分かりやすいでしょう。
03定義ファイルの書き方
フロントマターのnameとdescriptionがとくに重要です。nameがそのエージェントの識別子、descriptionは「どんなときに呼ぶか」を表す引き金になります（メインはこの説明文を読んで自動委譲を判断します）。任意でtools（使わせる道具を限定）とmodel（使うモデル）も指定できます。
# .claude/agents/code-reviewer.md --- name: code-reviewer description: コード変更をレビューする専門エージェント。コードを書いた直後に使う。 tools: Read, Grep, Glob model: sonnet --- あなたはシニアのコードレビュアーです。次の観点で見てください: - セキュリティ（認証・入力検証・秘密情報の混入） - 正しさ（エラー処理・境界ケース） - 可読性・パフォーマンス（N+1 など） 出力: - 見つけた問題（重大度つき） - 該当箇所の具体的な参照 - 修正案
toolsを省くとメインが使える道具をすべて引き継ぎます。レビュー専門なら書き込み系を渡さず読み取りだけに絞ると、誤って変更してしまう事故を防げます。modelにはsonnet／opus／haikuのほか、メインと同じモデルを使うinheritも指定できます。単純で量の多い作業は速くて安い Haiku に回す、といった調整が効きます。
# .claude/agents/test-writer.md --- name: test-writer description: テストを書く専門エージェント。1 ソースファイルに 1 テストファイル。 model: haiku --- あなたはテストエンジニアです。次を書いてください: - 正常系 - 境界ケース - 異常系
04呼び出し方：明示と自動
呼び出し方は 2 通りです。どちらも内部では、メインがサブエージェントを起動する仕組み（Agent ツール。以前は Task ツールと呼ばれていた名残で、古い呼び名も今のところ動きます）を使っています。
明示的に頼む
プロンプトでエージェント名を指して依頼します。例：「code-reviewer サブエージェントで、このディレクトリの最近の変更をレビューして」。一覧や管理は/agentsコマンドから行えます。
自動で委譲される
名前を出さなくても、メインが作業内容と各エージェントのdescriptionを照らし合わせ「これは test-writer の仕事だ」と判断すれば自動的に任せます。だから description は、ラベルではなく呼ばれる条件のつもりで書きます。
初心者のうちは明示呼び出しから始めるのが安心です。誰がどの作業をするかが見えるので、結果の確認や指示の修正がしやすくなります。
05並行で動かす
互いに依存しない作業をまとめて頼むと、メインは複数のサブエージェントを同時に立ち上げ、それぞれが別の文脈で進めて結果を一度に返します。たとえば次のような依頼です。
> 以下を並行でお願いします。互いに依存はありません。 > - tests/ 配下に不足しているテストを追加 > - docs/ を現状のコードに合わせて更新 > - CHANGELOG.md に変更点を追記
FIG.2 独立タスクは並列が速い。後段が前段の結果を使うなら順次にする
並列が効くのは、各エンドポイントを手分けして API ドキュメントを作る、言語ファイルごとに翻訳する、セキュリティを複数の観点から同時に点検するといった、作業同士が干渉しない場面です。逆に「A の出力を B が使う」なら、無理に並列にせず順番に進めた方が確実です。
06向いている場面・避けたい場面
向いている
大量ファイルへの同じ種類の変更、調査と実装の文脈分離、レビュアー／実装者／テスト書きのような役割分担。
微妙
一行で終わる小さな依頼。起動の手間（オーバーヘッド）の方が大きく、かえって遅くなる。
避けたい
強い依存があるのに並列化、複数の分身が同じファイルを同時編集。後者は競合の温床。
「とりあえず並列」は逆効果になりがちです。作業が本当に独立しているかを最初に見極めるのが、サブエージェントを使いこなすコツです。
07料金とプランの考え方
サブエージェントも内部で Claude を呼ぶため、動かした分だけトークンを消費します。並列にすると時間は短くなりますが、合計トークン量は減りません（むしろ増えがち）。ここは取り違えやすいので注意してください。
消費の上限は契約プランで変わります。個人の有料プランには Pro と、その上の Max（5 倍相当と 20 倍相当の 2 段階）があり、Max は Claude Code をより高い上限で使えます。具体的な価格・利用上限・週次のリセット条件は頻繁に見直されるため、最新の数値は必ず公式の料金ページで確認してください。重い並列作業を日常的に回すなら、上限に達しないかを事前に把握しておくと安心です。
Safety First
自動委譲ほど「承認」と「最小権限」を効かせる
サブエージェントは自分で判断して動くぶん、放っておくと意図しない変更まで進めてしまうことがあります。安全に使うための基本は次の 3 つです。
FIG.3 重要操作は「提案 → 人の承認 → 反映」の関門を通す
承認ポイントを置く——「各エージェントの出力は私の OK を待ってから commit して」と明示する。道具を絞る——フロントマターのtoolsで、その役割に要らない権限（とくに書き込みや実行）を渡さない。結果を鵜呑みにしない——AI は事実をもっともらしく取り違える（ハルシネーション）ことがあるので、生成物は一次情報やテストで検証する。自動委譲が便利になるほど、この 3 点の重みは増します。
08チームで使う・育てる
サブエージェントの定義ファイルをGit に commitすれば、チーム全員が同じ役割の分身を使えます。レビューやテストの観点が人によってブレなくなり、出力の品質がそろうのが利点です。プロジェクトの規約が変わったら定義文も更新し、古くなった指示を放置しないようにします。サブエージェントは「一度作って終わり」ではなく、運用しながら少しずつ良くしていく資産として扱うのが向いています。
09まとめ
Claude Code のサブエージェントは、文脈を分けて散らからせず、役割を絞って質を保ち、独立作業を並列で速くするための仕組みです。まずは.claude/agents/にレビュアーを 1 つ定義し、明示的に呼んでみるところから始めましょう。慣れてきたら、依存のない作業を並列に任せ、重要操作には承認と最小権限を効かせる——この順で広げていくと、安全に効果を引き出せます。これで「開発する」の foundations 2 章（LLM 開発の基礎＋AI コーディングツール）が揃いました。次は practice 章「プロンプト設計」「アプリ開発」へ進みます。
