Introduction to subagents ｜ Lesson 03「効果的なサブエージェントの設計（Designing effective subagents）」
出典: Anthropic Academy / YouTube動画ID WPxWKT_OaU4 ／ 2026-07-04
日本語ナレッジ（要点整理）
- 効果的なサブエージェントの4要素：①よい
description を書く ②出力フォーマットを定義する ③障害（obstacles）を報告させる ④ツールアクセスを制限する。設定が悪いサブエージェントは、あてもなく彷徨い、走りすぎ、メインエージェントが使えない出力を出す。
- 設定データがどう使われるか（超重要）：メインコンテキストのエージェントにメッセージを送ると、利用可能な全サブエージェントの
name と description がシステムプロンプトに含まれる。メインエージェントはこれを見て、どのサブエージェントをいつ起動するか判断する。自動起動のコントロールを改善したければ、name と description を調整する。
description の第2の役割：メインエージェントがサブエージェントを起動する際、タスク開始用の入力プロンプトを書くが、その際 description をガイドにする。つまり description は「いつ走るか」だけでなく「サブエージェントに何を指示するか」も形づくる。- 入力プロンプトを形づくる description の書き方（例：コードレビュー）：
- 汎用的な description → メインエージェントは「use get diff to find the current changes」のような曖昧な入力プロンプトを書く。どのファイルが重要かをサブエージェント自身が推測する羽目になる。
- description に「You must tell the agent precisely which files you want it to review.」を加える → メインエージェントは実際のファイル名を列挙した、はるかに具体的な入力プロンプトを書くようになる。
- 同じ手法は他タイプにも効く。例：Web検索サブエージェントの description に「return sources that can be cited」を加えると、委任時にその指示が含まれる。
- 最重要の改善＝出力フォーマットの定義：システムプロンプトに出力フォーマットを定義するのが単一で最も重要な改善。効果は2つ：
1. 自然な停止点を作る——各セクションを埋め終われば「完了」と分かる。
2. 走りすぎを防ぐ——出力の定義がないと、サブエージェントは「どこまで調べれば十分か」を決めきれず、必要以上に長く走りがち。
- コードレビューの構造化出力フォーマット例：
1. Summary：何をレビューし、全体評価はどうか
2. Critical Issues：即修正必須のセキュリティ脆弱性・データ整合性リスク・ロジックエラー
3. Major Issues：品質問題・アーキテクチャ不整合・重大なパフォーマンス懸念
4. Minor Issues：スタイルの不統一・ドキュメント欠落・軽微な最適化
5. Recommendations：改善提案・リファクタリング機会・適用すべきベストプラクティス
6. Approval Status：マージ/デプロイ可能か、変更要かの明確な表明
- 障害（Obstacles）の報告：サブエージェントが作業中に見つけた回避策（依存関係の解決、特定フラグが必要なコマンド等）は、返す要約に含めないと、メインスレッドが同じ解決策を再発見する羽目になり、時間とトークンを浪費する。浮かび上がらせたい情報：セットアップ問題・環境のクセ／作業中に見つけた回避策／特別なフラグや設定が必要だったコマンド／問題を起こした依存関係やインポート。出力フォーマットに "Obstacles Encountered" セクションを明示的に追加すると確実に拾える。
- ツールアクセスの制限：サブエージェントが実際に必要とするツールだけを与える。効果は2つ：意図しない副作用を防ぐ／複数運用時に各サブエージェントの役割が明確になる。
- Research / read-only——
Glob, Grep, Read だけでよい。ファイルを誤って変更できない。
- Code reviewer——
git diff を走らせるため Bash は必要だが、Edit / Write は不要。
- Styling / code modification——ここで初めて
Edit / Write を与える（仕事が実際にコードを変えることだから）。
- まとめ（4特性）：Specific descriptions（起動タイミングと受け取る指示の両方を操縦）／Structured output（完了判定と使える情報の担保）／Obstacle reporting（再発見の防止）／Limited tool access（研究は read-only、レビュアーは bash、コード変更するものだけ edit/write）。それぞれは単純だが、合わさると「なんとなく手伝おうとする存在」が「時間内に終わり、明確に報告する、焦点の定まった予測可能なワーカー」に変わる。
日本語（本文の自然な全訳）
サブエージェントの作り方が分かったところで、次はそれらを実際に効果的にするパターンを見ていきましょう。設定がまずいサブエージェントは、あてもなく彷徨い、長く走りすぎ、メインエージェントが使えない出力を生み出します。その解決策は4つに集約されます：よい description を書くこと、出力フォーマットを定義すること、障害を報告させること、そしてツールアクセスを制限することです。
サブエージェントの設定データがどう使われるか
メインのコンテキストウィンドウエージェントにメッセージを送ると、利用可能なすべてのサブエージェントの name と description がシステムプロンプトに含まれます。これがメインエージェントが「どのサブエージェントを、いつ起動するか」を判断する仕組みです。サブエージェントがいつ自動的に起動されるかをもっとうまくコントロールしたいなら、調整すべきは name と description です。
description にはもう1つの役割があります。メインエージェントがサブエージェントを起動する時、タスクを始動させるための入力プロンプトを書きます。その入力プロンプトを書く際のガイドとして description を使います。つまり description は、サブエージェントがいつ走るかをコントロールするだけでなく——サブエージェントが何をするよう指示されるかも形づくるのです。
入力プロンプトを形づくる description を書く
コードレビューのサブエージェントを考えてみましょう。汎用的な description だと、メインエージェントは「use get diff to find the current changes（get diff を使って現在の変更を見つけて）」のような入力プロンプトを書くかもしれません。これは曖昧です。どのファイルが重要かをサブエージェント自身が判断しなければなりません。
description を「You must tell the agent precisely which files you want it to review.（レビューしてほしいファイルを正確にエージェントに伝えなければならない）」のような内容に更新すると、メインエージェントは今度は実際にレビューすべきファイルを列挙した、はるかに具体的な入力プロンプトを書くようになります。
この同じ手法は、異なるタイプのサブエージェントでも通用します。たとえば、Web検索サブエージェントの description に「return sources that can be cited（引用可能な出典を返す）」を加えると、メインエージェントはタスクを委任する時にその指示を含めるようになります。
出力フォーマットを定義する
サブエージェントに対してできる最も重要な改善は、そのシステムプロンプトに出力フォーマットを定義することです。これは2つの働きをします：
- 自然な停止点を作る——サブエージェントは、フォーマットの各セクションを埋め終わった時に「完了した」と分かる。
- サブエージェントが長く走りすぎるのを防ぐ——定義された出力がないと、サブエージェントは「どれだけ調査すれば十分か」を決めきれず、必要以上にずっと長く走る傾向がある。
以下は、コードレビューサブエージェント向けの構造化された出力フォーマットの例です：
Provide your review in a structured format:
1. Summary: Brief overview of what you reviewed and overall assessment
2. Critical Issues: Any security vulnerabilities, data integrity risks,
or logic errors that must be fixed immediately
3. Major Issues: Quality problems, architecture misalignment, or
significant performance concerns
4. Minor Issues: Style inconsistencies, documentation gaps, or
minor optimizations
5. Recommendations: Suggestions for improvement, refactoring
opportunities, or best practices to apply
6. Approval Status: Clear statement of whether the code is ready
to merge/deploy or requires changes
このフォーマットは、サブエージェントに取り組むべき明確なチェックリストを与えます。すべてのセクションが埋まったら、サブエージェントは止まってよいと分かります。
障害を報告する
サブエージェントが作業中に回避策を発見した時——依存関係の問題を解決したり、あるコマンドに特定のフラグが必要だと分かったり——それらの詳細は、返す要約の中に現れる必要があります。もしそうしなければ、メインスレッドは同じ解決策を自分で再発見しなければならず、時間とトークンを浪費します。
浮かび上がらせたいのは、次のような種類のものです：
- セットアップの問題や環境のクセ
- タスク中に発見した回避策
- 特別なフラグや設定が必要だったコマンド
- 問題を引き起こした依存関係やインポート
この情報を得る方法は、出力フォーマットの中でそれを明示的に要求することです。出力テンプレートに「Obstacles Encountered（遭遇した障害）」セクションを追加すると、この情報が確実に表面化します。
7. Obstacles Encountered: Report any obstacles encountered during the
review process. This can be: setup issues, workarounds discovered or
environment quirks. Report commands that needed a special flag or
configuration. Report dependencies or imports that caused problems.
ツールアクセスを制限する
すべてのサブエージェントがすべてのツールへのアクセスを必要とするわけではありません。サブエージェントが実際に何をする必要があるかを考え、その仕事に必要なツールだけを与えましょう。これは2つの働きをします：意図しない副作用を防ぎ、複数のサブエージェントがある時に各々の役割をより明確にします。
一般的なサブエージェントのタイプごとに、ツールアクセスをどう考えるかは次の通りです：
- Research / read-only サブエージェント——
Glob、Grep、Read だけが必要。ファイルを誤って変更することはできない。
- Code reviewer——
git diff を走らせて何が変わったかを見るために Bash アクセスが必要だが、それでも Edit や Write は不要。
- Styling / code modification エージェント——ここで
Edit と Write のアクセスを与える。サブエージェントの仕事が実際にコードを変更することだから。
すべてを組み合わせる
効果的なサブエージェントは4つの特性を共有します：
- Specific descriptions（具体的な description）——
description は、サブエージェントがいつ起動されるか、そしてどんな指示を受け取るかをコントロールする。両方を操縦するように書く。
- Structured output（構造化された出力）——システムプロンプトに出力フォーマットを定義し、サブエージェントが「いつ完了したか」を分かり、メインスレッドが使える情報を返すようにする。
- Obstacle reporting（障害の報告）——回避策・クセ・問題のためのセクションを出力フォーマットに含め、メインスレッドが再発見せずに済むようにする。
- Limited tool access（限定されたツールアクセス）——サブエージェントに実際に必要なツールだけを与える。研究には read-only、レビュアーには bash、コードを変更すべきエージェントにだけ edit/write。
これらのパターンはそれぞれ単純ですが、合わさることで、サブエージェントを「漠然と役立とうとする何か」から「時間通りに終わり、明確に報告する、焦点の定まった予測可能なワーカー」へと変えます。
英語逐語（動画字幕 or 本文原文）
動画字幕（YouTube: WPxWKT_OaU4・重複除去済み）
Now that you know how to create sub agents, let's look at patterns that lead to effective sub agents. First, let's get a better idea of how some of the data in the sub agent config file is used.
Whenever you send a message to the main context window agent, the name and description of each sub agent is included in the system prompt. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name description.
Next, remember that when a sub agent is launched, the main agent writes an input prompt. When writing this input prompt, it uses the description as guidance. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name and description.
Let's consider our review sub agent again. Right now, when the main agent runs the sub agent, the sub agent is given an input prompt telling it to use get diff to find the current changes. If we wanted the main agent to more reliably tell the sub agent exactly which files to review, we would update the description. "You must tell the agent precisely which files you want it to review." Now, if we ask Claude to run the code reviewer agent, we'll see a different input.
You can also influence what the main thread tells a sub agent through the description. So, adding "return sources that can be cited" to a web search sub agent's description causes the main thread to include that instruction when delegating the task.
The most important improvement that you can make is defining an output format in the system prompt. This creates natural stopping points for the sub agent. Without a defined output format, sub agents struggle to decide when enough research has been done and they tend to run much much longer than sub agents that are given an output format.
When a sub agent discovers a workaround to some issue like solving a dependency issue or finding that a certain command needs particular flags, these details should appear in the summary. Otherwise, the main thread has to rediscover the same solutions. Obstacles encountered, any setup issues, workarounds discovered, or environment quirks, commands that needed special flags or configuration, dependencies or imports that cause problems. Explicitly asking for obstacle reporting in the output format surfaces this information.
A read-only sub agent using just glob, grep, read cannot accidentally modify files. This constraint clarifies the sub agent's role and prevents unintended side effects. So, think about what sub agents actually needs to do. If it's just researching, it only needs to read files, so keep it read-only. That way it can't accidentally modify anything while exploring. A reviewer needs to run get diff to see what changed, so give it bash access, but it still doesn't need to edit files. Only give edit and write to sub agents that should actually change your code like a styling agent applying CSS updates. This also helps clarify what each sub agent is for when you have several of them.
So, effective sub agents use structured output, report obstacles, have specific descriptions, and limit tool access.
本文原文（テキストレッスン）
Designing effective subagents
Now that you know how to create subagents, let's look at the patterns that make them actually effective. A subagent that's poorly configured will wander, run too long, or produce output the main agent can't use. The fixes come down to four things: writing good descriptions, defining an output format, reporting obstacles, and limiting tool access.
How Subagent Config Data Gets Used
When you send a message to the main context window agent, the name and description of every available subagent are included in the system prompt. This is how the main agent decides which subagent to launch and when. If you want better control over when a subagent gets triggered automatically, the name and description are what you should tweak.
The description also plays a second role. When the main agent launches a subagent, it writes an input prompt to kick off the task. It uses the description as guidance for writing that prompt. So the description doesn't just control when a subagent runs -- it shapes what the subagent is told to do.
Writing Descriptions That Shape Input Prompts
Consider a code review subagent. With a generic description, the main agent might write an input prompt like "use get diff to find the current changes." That's vague. The subagent has to figure out which files matter on its own.
If you update the description to include something like "You must tell the agent precisely which files you want it to review," the main agent will now write a much more specific input prompt that lists the actual files to review.
This same technique works across different types of subagents. For example, adding "return sources that can be cited" to a web search subagent's description causes the main agent to include that instruction when delegating the task.
Defining an Output Format
The single most important improvement you can make to a subagent is defining an output format in its system prompt. This does two things:
It creates natural stopping points -- the subagent knows it's done when it has filled in each section of the format.
It prevents the subagent from running too long. Without a defined output, subagents struggle to decide when enough research has been done and tend to run much longer than necessary.
Here's an example of a structured output format for a code review subagent:
Provide your review in a structured format:
1. Summary: Brief overview of what you reviewed and overall assessment
2. Critical Issues: Any security vulnerabilities, data integrity risks,
or logic errors that must be fixed immediately
3. Major Issues: Quality problems, architecture misalignment, or
significant performance concerns
4. Minor Issues: Style inconsistencies, documentation gaps, or
minor optimizations
5. Recommendations: Suggestions for improvement, refactoring
opportunities, or best practices to apply
6. Approval Status: Clear statement of whether the code is ready
to merge/deploy or requires changes
This format gives the subagent a clear checklist to work through. Once every section is filled in, the subagent knows it can stop.
Reporting Obstacles
When a subagent discovers a workaround during its work -- like solving a dependency issue or finding that a certain command needs particular flags -- those details need to appear in the summary it returns. If they don't, the main thread has to rediscover the same solutions on its own, which wastes time and tokens.
The kinds of things you want surfaced include:
Setup issues or environment quirks
Workarounds discovered during the task
Commands that needed special flags or configuration
Dependencies or imports that caused problems
The way to get this information is to explicitly ask for it in the output format. Adding an "Obstacles Encountered" section to your output template surfaces this information reliably.
7. Obstacles Encountered: Report any obstacles encountered during the
review process. This can be: setup issues, workarounds discovered or
environment quirks. Report commands that needed a special flag or
configuration. Report dependencies or imports that caused problems.
Limiting Tool Access
Not every subagent needs access to every tool. Think about what a subagent actually needs to do, and only give it the tools required for that job. This does two things: it prevents unintended side effects, and it makes each subagent's role clearer when you have several of them.
Here's how to think about tool access for common subagent types:
Research / read-only subagent -- Only needs Glob, Grep, and Read. Cannot accidentally modify files.
Code reviewer -- Needs Bash access to run git diff and see what changed, but still doesn't need Edit or Write.
Styling / code modification agent -- This is where you give Edit and Write access, because the subagent's job is to actually change your code.
Putting It All Together
Effective subagents share four characteristics:
Specific descriptions -- The description controls when the subagent is launched and what instructions it receives. Write it to steer both.
Structured output -- Define an output format in the system prompt so the subagent knows when it's done and returns information the main thread can use.
Obstacle reporting -- Include a section in the output format for workarounds, quirks, and problems so the main thread doesn't have to rediscover them.
Limited tool access -- Only give a subagent the tools it actually needs. Read-only for research, bash for reviewers, edit/write only for agents that should change code.
Each of these patterns is simple on its own, but together they turn a subagent from something that vaguely tries to help into a focused, predictable worker that finishes on time and reports back clearly.