コースガイド

Introduction to Subagents — 日本語学習ガイド

Anthropic Academy コース「Introduction to Subagents」（全4レッスン）の日本語学習ガイド。NotebookLM 等で音声概要／動画概要を作るためのソース資料としても使える。

Claude Code の subagent（サブエージェント）機能を、「なぜ必要か」「どう作るか」「どう設計すれば効果的か」「いつ使う／使わないべきか」の順で学ぶ。CCA（Claude Certified Architect、Claude Code・Agent SDK・Claude API・MCP を横断する Anthropic 公式資格）を意識するなら、subagent／オーケストレーションは（非公式の exam guide によれば）主に「Agentic Architecture and Orchestration」ドメインで重点的に問われるとされる。

1. Subagentとは何か（What are subagents?）

基本定義

Subagent とは、Claude Code がタスクを委譲できる専門のアシスタントである。それぞれが自分自身の会話用コンテキストウィンドウの中で作業し、作業が終わるとサマリ（要約）だけをメインスレッドに返す。ファイルの読み込み・検索・ツール呼び出しといった途中経過はすべて subagent 側のコンテキストに隔離されたままで、メインの会話を一切散らかさない。

なぜ重要なのか

チャットでのやり取りは、すべてメインのコンテキストウィンドウに積み上がっていく。このコンテキストウィンドウは有限であり、いっぱいになると Claude は会話の前半部分を見失ってしまう。

Subagent はここで別のコンテキストウィンドウを新規に立ち上げる。この専用コンテキストウィンドウの中で、subagent は次の2つを受け取る。

設定ファイルで定義されたカスタムシステムプロンプト（subagent の役割・振る舞いを定義するもの）
親エージェント（メインの Claude）がユーザーの依頼をもとに書き起こしたタスクの説明文

Subagent はこの隔離された環境の中で自律的に作業する（ファイルを読み、検索をかけ、コードを編集する）。作業が終わると、メインの会話に返されるのはサマリのみであり、subagent 内で行われた会話全体はそこで破棄される。この仕組みにより、メインのコンテキストは常にきれいな状態に保たれる。

ただし、これにはトレードオフがある。Subagent がどのような過程・思考順序でその結論に至ったかという「途中経過の可視性」は失われる、という点である。

具体例で理解する

「返金を扱っているのはどのサービスか？」という質問を考えてみる。

Subagent を使わない場合: Claude はこの1つの質問に答えるために、15個のファイルを読み、複数回の検索を行うかもしれない。それらすべてがメインのコンテキストウィンドウを埋めていく。
Subagent を使う場合: Explore という subagent が、自分自身のコンテキストの中で調査を行い、的を絞った答えだけを持ち帰る。メインのコンテキストに残るのは、「質問」と「その要約された答え」だけである。

同じ調査でも、subagent を経由するかどうかでメインの会話履歴への負荷がまったく違うことがわかる。

組み込み（built-in）のsubagent

Claude Code にはあらかじめ subagent が組み込まれている。本編で扱う主要な3種類に加え、公式ドキュメントでは補助的な subagent として statusline-setup と claude-code-guide も組み込み済みとされており、現行ドキュメント時点では計5種類となる。

組み込み subagent	役割
General purpose（汎用）	調査（探索）と実際の行動（変更作業）の両方が必要な、複数ステップにわたるタスク向け
Explore（探索）	コードベースを高速に検索・ナビゲートするための専用 subagent
Plan（計画）	プランモードの中で、実際の計画を提示する前の調査・分析を担当する
statusline-setup	`/statusline` コマンド実行時に使用される（モデルは Sonnet）
claude-code-guide	Claude Code の使い方に関する質問に使用される（モデルは Haiku）

カスタムsubagent

これら組み込みのもの以外に、独自のカスタムシステムプロンプトとツールアクセス権を持ったカスタム subagent を自分で作ることもできる。用途の例としては、コードレビュアー、テスト作成担当、ドキュメント生成担当などが挙げられる。カスタム subagent の具体的な作り方は次のレッスンで扱う。

このレッスンの要点

Subagent は次の3つのことを行っている。

作業を焦点の絞られた小さな単位に分割する
途中経過の作業をメイン会話から隔離することで、メインのコンテキストをきれいに保つ
必要な情報だけを、簡潔なサマリとして持ち帰る

メインのコンテキストに乗るノイズが少ないほど、より長く、より効果的に作業を続けられる。これが subagent という仕組みの本質的な価値である。

2. Subagentの作り方（Creating a subagent）

カスタムsubagentとは

カスタム subagent は、コードレビュー・テスト作成・ドキュメントチェックといった特定のタスクに特化する。これは、Claude に「いつ」その subagent を使うべきか、「どのように」振る舞うべきかを伝える、YAMLフロントマター付きのMarkdownファイルとして定義される。

作成方法

v2.1.198 以降、/agents スラッシュコマンドはもはや対話型のウィザードを開かない。実行すると「Claude に依頼するか、.claude/agents/（または ~/.claude/agents/）のファイルを直接編集してください」という案内が表示されるだけである。したがって現在の最も簡単な作り方は、Claude に「こういう subagent を作って」と依頼するか、設定ファイルを自分で直接書くことである（v2.1.197 以前は /agents を実行すると「Create new agent（新しいエージェントを作成）」を選べる対話型ウィザードが開いていた）。

作成の際にはまずスコープを選ぶ。

Project-level（プロジェクトレベル）: 現在のプロジェクトのみで有効
User-level（ユーザーレベル）: このマシン上のすべてのプロジェクトで有効

続いて作成方法を選ぶ。

設定を手動で書く
（推奨）Claude に生成させる。やりたいことを説明するだけで、Claude が名前・description（説明文）・システムプロンプトを生成してくれる

ツールのカスタマイズ

作成の過程で、subagent に与えるツールをカスタマイズできる。ツールは次のカテゴリに分かれている。

Read-only（読み取り専用）
Edit（編集）
Execution（実行）
MCP
Other（その他）

原則は「その subagent に必要なツールだけを与える」ことである。たとえばコードレビュアーには Edit 系のツールは不要である（レビューとは、コードを変更するのではなく、読んで分析することだからである）。一方で、保留中の変更を特定するために Execution 系のツールを残しておく、といった判断はありうる。

モデルと色の選択

v2.1.198 以降、/agents の対話型モデルピッカーは廃止されている。現在、frontmatter の model フィールドに指定できる値は次のとおりである。

選択肢	特徴
haiku	高速・軽量
sonnet	中間的なバランス
opus	複雑な分析向け
fable	追加のモデル選択肢（詳細は公式ドキュメント参照）
フルモデルID（例: `claude-opus-4-8`）	特定のモデルバージョンを直接指定
inherit（継承）	メインの会話で使われているモデルをそのまま使う

色は、UI上でどの subagent が現在動作しているかを一目でわかるようにするための表示用の設定である。

設定ファイルの実体

作成した subagent の設定は、.claude/agents/<エージェント名>.md というパスに保存される（.claude フォルダの直下ではなく、必ず agents サブディレクトリの中に置かれる点に注意）。実物のイメージは次のとおりである。

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---
You are an expert code reviewer specializing in quality assurance, security best practices, and adherence to project standards...

各フィールドの意味は次のとおりである。

name — 一意な識別子。@agent-code-quality-reviewer のように、ハイフンでつないで参照する（スペースは入れない）
description — Claude が「いつ」その subagent を使うかを決める最重要フィールド。必ず1行で書く必要があり、改行を含めたい場合は \n を使う。会話例（サンプルのやり取り）を含めることもできる
tools — その subagent がアクセスできるツール。いつでも編集可能
model — sonnet / opus / haiku / fable / フルモデルID（例: claude-opus-4-8） / inherit のいずれか
color — UI上の表示色

システムプロンプト

フロントマター（--- で囲まれた部分）より下の本文が、その subagent のシステムプロンプトにあたる。ここには、何に注目すべきか・どう分析すべきか・所見をどう報告すべきかといった、subagent への具体的な指示を書く。質の高いシステムプロンプトを書けるかどうかが、その subagent が実際に役立つか、的外れなことをしてしまうかの分かれ目になる。

Claudeに自動で使わせる

Description に "proactively"（積極的に） という語を含めておくと、Claude はその subagent をより自発的に使うようになる。たとえば「Proactively suggest running this agent after major code changes...（大きなコード変更の後には、積極的にこのエージェントの実行を提案せよ）」のような書き方である。あわせて、具体的な会話例を description に追加しておくと、委譲（delegation）の精度がさらに上がる。

テストと調整

実際にコードを変更してみて、Claude にレビューを依頼してみる。もし期待したときに subagent が呼ばれなければ、直すべきはdescription である。より具体的な例や、発火してほしい場面（トリガーとなるシナリオ）を description に追加していく。

3. 効果的なsubagentの設計（Designing effective subagents）

設定が甘い subagent は、目的の周辺をさまよって時間ばかりかかったり、親エージェント（メインの Claude）が使いようのない出力を返してきたりする。これを防ぐための改善策は次の4つである。

良い description を書く
出力フォーマットを定義する
障害（obstacles）を報告させる
ツールアクセスを制限する

設定データがどう使われているかを理解する

メインエージェントにメッセージを送るたびに、利用可能なすべての subagent の name と description がシステムプロンプトに含まれている。これが、メインエージェントが「どの subagent を、いつ起動するか」を判断する仕組みである。

さらに description は、その subagent の作業を開始させるために親エージェントが書く入力プロンプトの内容そのものも左右する。つまり description は、subagent が「いつ」起動するかだけでなく、「何を」指示されるかも同時にコントロールしている。

入力プロンプトを形作るdescriptionの書き方

抽象的な description は、抽象的な入力プロンプトしか生まない。たとえば単に「コードをレビューする」とだけ書いてあると、親エージェントは "use git diff to find current changes"（git diff で現在の変更を確認せよ）のような、漠然とした指示しか書けない。

ここに「You must tell the agent precisely which files you want it to review（レビューしてほしいファイルを正確に伝えなければならない）」という一文を description に加えると、親エージェントは実際のファイル名を列挙した、具体的なプロンプトを書くようになる。

同じテクニックは他の場面にも応用できる。たとえば Web 検索を行う subagent であれば、「return sources that can be cited（引用可能な出典を返すこと）」のような一文を description に含めておく、といった具合である。

出力フォーマットを定義する（もっとも重要な改善）

システムプロンプトの中に出力フォーマットを定義しておくことは、数ある改善策の中でも最も重要とされる。理由は次の2つである。

各セクションが埋まった時点で「作業が完了した」という自然な終了点が生まれる
これによって subagent が延々と作業を続けてしまうことを防げる

コードレビュー用の subagent であれば、たとえば次のような出力フォーマットが例として挙げられている。

Summary（概要）
Critical Issues（重大な問題）
Major Issues（主要な問題）
Minor Issues（軽微な問題）
Recommendations（推奨事項）
Approval Status（承認ステータス）

障害の報告

作業中に見つかったワークアラウンド（依存関係の修正、必要だった特別なフラグなど）は、必ず返却されるサマリに含めなければならない。そうしなければ、メインスレッドは同じ問題をまた一から発見し直すことになり、時間とトークンを浪費してしまう。

対策として、出力テンプレートに "Obstacles Encountered"（遭遇した障害） というセクションを追加する。ここには、セットアップ上の問題、実施したワークアラウンド、特別なフラグが必要だったコマンド、問題のある依存関係やインポートなどを記録させる。

ツールアクセスの制限

Subagent には、その仕事に必要なツールだけを与える。これによって意図しない副作用を防ぎ、それぞれの subagent の役割を明確にすることができる。

リサーチ／読み取り専用系 — Glob、Grep、Read のみ。ファイルを変更できないようにする
コードレビュアー — git diff を実行するための Bash は必要だが、Edit や Write は与えない
スタイリング／コード修正系 — Edit や Write を与える（コードを変更することがその仕事そのものだから）

まとめ

効果的な subagent には、次の4つの特徴が共通している。

具体的な description — いつ起動され、どんな指示を受け取るかの両方を方向づける
構造化された出力 — subagent 自身がいつ完了したかを把握でき、かつ利用可能な情報が返ってくる
障害の報告 — 発見したワークアラウンドが失われずメインスレッドに伝わる
限定されたツールアクセス — 役割が明確になり、意図しない副作用を防ぐ

4. Subagentを効果的に使う（Using subagents effectively）

判断の分かれ目

Subagent を使うべきかどうかを決める鍵は、「その途中経過の作業が、メインスレッドにとって重要かどうか」である。

Subagentが輝く場面

探索（exploration）と実行（execution）が分離できる場面で、subagent は真価を発揮する。もし各ステップが、その前のステップで発見した内容に依存しているのであれば、それはメインスレッドの中で進めるべきである。一方、旅の過程（どうやってそこにたどり着いたか）には関心がなく、ただ結果だけが欲しいのであれば、それは委譲すべきタスクである。

Subagent が優れているのは、次のような場合である。

一部始終（play-by-play）ではなく、結果だけが欲しいとき
探索的な作業が、メインのコンテキストを散らかしてしまうとき
そのタスクが、新しい視点やカスタムのシステムプロンプトから恩恵を受けられるとき

リサーチタスク（古典的なユースケース）

見慣れないコードベースで「認証はどう動いているのか」を調査するようなタスクは、subagent の典型的な使いどころである。リサーチ用の subagent は、自分自身のコンテキストの中で数十個のファイルを読み、呼び出し関係をたどり、最終的にクリーンなサマリを持ち帰る。たとえば「JWT の検証は middleware/auth.js の42行目で行われており、route/api.js から呼び出されている」といった具合である。

コードレビュー

Claude は、あるコードが他の誰かによって書かれたものとして提示されたときの方が、より効果的にレビューを行える。ある機能を実装したのと同じスレッドに、そのままレビューまでさせようとすると、フィードバックが弱くなりがちである（そのスレッドは、自分が書いたコードを「新鮮な目」で見ることができないからである）。

レビュアー用の subagent は、履歴を持たない別のコンテキストの中でその変更を見る（git diff を実行し、変更されたファイルを読み、レビュー基準を適用する）。これにより、プロジェクト固有のレビュー基準を subagent のシステムプロンプトに落とし込み、レビューの一貫性を保つことができる。

カスタムシステムプロンプトが効く場面

Claude Code のデフォルトのシステムプロンプトは、簡潔でコードに集中した応答を重視するようにできている。これはコーディングには適しているが、あらゆる場面に適しているわけではない。カスタムのシステムプロンプトが subagent をより良くするケースとしては、次のようなものがある。

コピーライティング担当の subagent — トーン・想定読者・文体についての指示を与える（デフォルトのままだと簡潔で技術的な文章に寄りがちで、ランディングページやメール文面には向かない）
スタイリング担当の subagent — デザインシステムのファイルを参照させる。これらのファイルは自動的にコンテキストへ読み込まれるため、CSS を書き始める前に、カラー変数・スペーシング・コンポーネントのパターンを把握した状態になる

Subagentが害になる場面（アンチパターン）

次のようなケースでは、subagent はむしろ有害に働く。

「専門家」を名乗らせるだけの指示 — 「あなたは Python の専門家です」のような一文には何の価値もない。Claude はすでにその知識を持っている
逐次的なパイプライン — 例えば「バグを再現する → デバッグする → 修正する」という一連の流れ。各ステップが前のステップで発見した情報に依存する場合、これはうまく機能しない（引き継ぎの過程で情報が失われてしまう）。バグ修正というタスクは、ほぼ常にこの「前段階への依存」を伴う
テストランナー — 「テストが失敗しました」とだけ返す subagent は、診断に必要な出力の全体を隠してしまう。実際の検証でも、この test-runner パターンは、あらゆる構成の中で最も成績が悪かったという結果が示されている

判断ルール

問うべきことは1つ、「その途中経過の作業は重要か？」である。

重要でない（結果だけが欲しい）→ subagent に委譲する
重要である（過程を見ながら反応する必要がある）→ メインスレッドにとどめる

まとめると、次のように使い分ける。

使うべき場面	避けるべき場面
リサーチ／探索	「専門家」ペルソナを名乗らせるだけの指示
コードレビュー	前段階に依存する多段パイプライン
カスタムシステムプロンプトが要るタスク	完全な出力を確認したいテスト実行

このコース全体の要点（暗記用）

Subagent は独立したコンテキストウィンドウで作業し、メインスレッドにはサマリだけを返す。途中経過はメインの会話を汚さない代わりに、可視性は失われる。
組み込み subagent の主要3種類は General purpose（探索＋実行）／ Explore（高速検索）／ Plan（計画前の調査）。このほか補助的な statusline-setup・claude-code-guide を含め、現行ドキュメント時点では計5種類が組み込み済み。
カスタム subagent は Claude に依頼するか、.claude/agents/<名前>.md（または ~/.claude/agents/）を直接編集して作成する（/agents は v2.1.198 以降ウィザードを開かず案内表示のみになった）。実体は YAML フロントマター付き Markdown で、フィールドは name / description / tools / model / color。
description が「いつ使うか」と「何を指示するか」の両方を左右する。 "proactively" という語や具体的な会話例が、自動委譲の精度を上げる。
効果的な設計の4本柱: 具体的な description／出力フォーマットの定義（最重要）／障害の報告／ツールアクセスの制限。
使いどころの判断基準はただ1つ、「途中経過の作業が重要かどうか」。重要でなければ委譲、重要なら手元（メインスレッド）で進める。
アンチパターンは3つ: 「専門家」ペルソナ／前段階に依存する逐次パイプライン／全出力を隠してしまうテストランナー。 特に test runner パターンは実測で最も成績が悪かった。