はじめに
こんにちは！Dirbatoの槇野です。
「SubAgentに任せたのに、全然意図と違うコードが生成された…」
「指示を何度修正しても、出力が安定しない…」
SubAgentを活用している方なら、一度はこんな経験があるのではないでしょうか？
私自身、SubAgentを導入した当初は「思ったより精度が出ない」と感じていました。
しかし、試行錯誤を重ねる中で 指示の出し方や設計を少し変えるだけで、出力の精度が劇的に改善する ことに気づきました。
この記事では、SubAgentの精度を向上させるために 実際に効果があった3つのテクニック を紹介します。
対象読者
- SubAgentを使い始めたが、出力が安定しない方
- カスタムエージェントの設計をもっと良くしたい方
- マルチエージェント構成のプロンプト設計に悩んでいる方
筆者の検証環境
| 項目 | 内容 |
|---|---|
| IDE | VS Code |
| AI | GitHub Copilot |
| モデル | Claude Sonnet 4.6 |
そもそもSubAgentとは？
SubAgentとは、メインのAIエージェントから独立したコンテキストウィンドウで動作する専門エージェントです。
メインセッションを汚さずに特定のタスクを処理し、結果だけを返してくれます。
| メリット | 説明 |
|---|---|
| コンテキスト保護 | 試行錯誤の過程がメインセッションに残らない |
| 精度向上 | 専門化されたプロンプトで特定タスクの品質が上がる |
| 並列実行 | 複数のSubAgentを同時に走らせられる |
| 再利用性 | 一度作れば何度でも使える |
テクニック1：「1エージェント1責務」で分割する
きっかけ
最初に作ったSubAgentは、こんな感じの「何でも屋」でした。
# .github/agents/dev-assistant.agent.md
---
name: dev-assistant
description: Helps with code review, debugging, testing, and documentation
tools: []
---
あなたは開発アシスタントです。
コードレビュー、デバッグ、テスト作成、ドキュメント作成を行います。
これで動くことは動くのですが、レビューの観点が浅かったり、テストのカバレッジが甘かったり、どのタスクも「60点」くらいの出力しか返ってこない。人間だって「何でもやって」と言われたら一つ一つが雑になりますよね。それと同じことがSubAgentでも起きていました。
やったこと
「何でも屋」を捨てて、責務ごとに専門エージェントを分割しました。
また後述しますが、tools でできることの制限も実施しました。
# .github/agents/code-reviewer.agent.md
---
name: code-reviewer
description: >
Use this agent when you have completed writing a logical chunk of code
and need a comprehensive review for correctness, style, performance,
and security issues.
tools: ['codebase', 'search', 'usages']
---
あなたはコードレビュー専門のエージェントです。
## レビュー観点
1. ロジックの正確性・エッジケース
2. コーディング規約との整合性
3. パフォーマンス上の問題
4. セキュリティリスク
## 出力フォーマット
- Critical: 必ず修正が必要
- Warning: 修正を推奨
- Good: 良い実装
# .github/agents/test-writer.agent.md
---
name: test-writer
description: >
Use this agent to generate unit tests and integration tests.
Invoke when implementing new features or fixing bugs.
tools: ['codebase', 'search', 'editFiles', 'terminalLastCommand']
---
あなたはテスト作成専門のエージェントです。
## ルール
- テストケース名は日本語で記述する
- 正常系の後に異常系のテストを書く
- AAA（Arrange-Act-Assert）パターンに従う
効果と気づき
分割した直後から、レビューの指摘が明らかに具体的になりました。
たとえば、汎用テーブルコンポーネントの型定義に関するレビューでは、こんな違いが出ました。
分割前（何でも屋時代）：問題の指摘で止まる
data プロパティが汎用的すぎる型で定義されており、
呼び出し側で不必要な型変換や安全性の低い扱いが発生しています。
分割後（レビュー専門エージェント）：原因・影響・リスクまで踏み込む
共通テーブルコンポーネントを利用する複数の画面で、型安全性を保てないために二重キャストやインデックスをキーに使う実装が散見されます。
これにより、ソートやページング、将来的なリファクタで差分更新が正しく動作しない等の不具合リスクがあります。
「何が悪いか」だけでなく「なぜ悪いか、放置するとどうなるか」まで
指摘してくれるようになったのが大きな変化でした。
もう一つ重要だったのが tools の最小化です。VS Code公式ドキュメントのセキュリティ考慮事項セクションでも、エージェントのツール設定について以下のように述べられています。
Select only the tools that are relevant for your prompt to improve your results.
（結果を改善するために、プロンプトに関連するツールだけを選択してください）
── Use tools with agents - VS Code公式
review the tool list and instructions to ensure they follow the principle of least privilege.
（ツールリストと指示が最小権限の原則に従っているか確認してください）
── Custom agents in VS Code - VS Code公式
実際、全ツールを許可していた頃は、レビューのはずなのに勝手にコードを書き換えてしまうことがありました。レビュー専門なら codebase と search だけで十分で、editFiles 権限は不要。
| ポイント | 説明 |
|---|---|
| 責務の単一化 | 1エージェント = 1つの専門領域 |
| toolsの最小化 | 必要なツールだけ許可。レビューに編集権限は不要 |
📝 ツール名について
本記事では2026年3月時点の最新の推奨ツール名を使用しています。VS Code v1.107（2025年11月）でツール名の再編成が行われ、read → codebase、edit → editFiles、runCommands → terminalLastCommand 等に変更されました。旧名でも動作しますが、VS Codeが Code Action でリネームを提案するため、新しい名前を使うことを推奨します。
参照：https://code.visualstudio.com/updates/v1_107
テクニック2：description と指示文を「AIが判断しやすい形」で書く
きっかけ
テクニック1で責務を分割したものの、今度は別の問題が出てきました。意図したSubAgentが呼ばれないのです。コードレビューをしてほしい場面でテスト作成エージェントが動いたり、そもそもSubAgentが起動しなかったり。
原因を調べてみると、description の書き方に問題がありました。
# これだと、いつ使うべきかAIが判断できない
description: コードレビューをするエージェント
GitHub Copilotは description を読んでSubAgentにタスクを委任するか判断します。「コードレビューをするエージェント」では、どんな場面で呼ぶべきかの情報が足りない。
やったこと
description を「いつ・何を・どう使うか」が明確な形に書き直しました。
description: >
Use this agent when you have completed writing a logical chunk of code
(function, class, module, or feature) and need a comprehensive review
for correctness, style consistency, performance, and security issues.
Also use before merging pull requests or major releases.
チェックリスト形式で整理するとこうなります。
| # | チェック項目 | 例 |
|---|---|---|
| 1 | いつ使うかが明記されている |
Use when... / Invoke after...
|
| 2 | 何をするかが具体的 | review for correctness, security |
| 3 | いつ使わないかが暗示されている | 責務の範囲を限定する |
指示文（プロンプト本文）も同様に見直しました。
## あなたの役割
コードレビュー専門のエージェントです。
## 必ず守るルール
- IMPORTANT: レビュー結果は必ず指定フォーマットで出力すること
- YOU MUST: セキュリティリスクがある場合は最優先で報告すること
## コードを書く前にやること
1. まず実装手順を共有する
2. 仕様書を必ず読む
3. 実装に迷ったら2つの案を提示する
4. 不明点は質問する
## 出力フォーマット
（具体的なフォーマットを記載）
効果と気づき
description を書き直してから、SubAgentの呼び分けミスがほぼなくなりました。以前は5回に1回くらい間違ったエージェントが起動していたのが、書き直し後はほぼ100%正しいエージェントが選ばれるようになりました。
それでも意図したエージェントが呼ばれないケースが残る場合は、親エージェントのシステムプロンプト内や、ユーザープロンプト内で使用するエージェントを明示的に指定するという方法もあります。
# .github/agents/main-orchestrator.agent.md
---
name: main-orchestrator
description: >
Main development coordinator. Routes tasks to specialized sub-agents.
---
# タスクごとのエージェント割り当て
以下のルールに従って、必ず指定されたエージェントにタスクを委任してください。
- コードレビューを行う場合 → code-reviewer を使用
- テストを作成する場合 → test-writer を使用
- ドキュメントを作成する場合 → doc-writer を使用
- 上記に該当しない場合 → 自分自身で対応する
description による自動判定と比べると、ユーザーが親エージェントの指示を意識しなければならないわずらわしさはあります。ただ、ほぼ確実に意図したエージェントが呼ばれるようになるので、呼び分けの精度を最優先したい場面では有効な手段です。
VSCodeでは、公式に用意されている agents プロパティを使って、使用可能なSubAgentをフロントマターで明示的に制限する方法があります。
agents プロパティを使うことで、フロントマターレベルでSubAgentの呼び出し対象を制限できます。これにより、意図しないエージェントが呼ばれるリスクを構造的に排除できます。
なお、agents プロパティを使う場合は、tools に 'agent' を含める必要がある点に注意してください。
---
name: main-orchestrator
description: >
Main development coordinator. Routes tasks to specialized sub-agents.
tools: ['agent']
agents: ['code-reviewer', 'test-writer', 'doc-writer']
---
テクニック3：親エージェントの指示がSubAgentを「汚染」していないか確認する
きっかけ
テクニック1・2を実践して、だいぶ安定してきた。はずだったのですが、ある日おかしな現象に遭遇しました。
SubAgentに「JSON形式で出力して」と指示したのに、返ってくるのはなぜかMarkdown。SubAgent単体で動かすとちゃんとJSONが返る。なのに、親エージェント経由だとMarkdownになる。
※ここでいう「JSON形式で出力して」は、SubAgentの .agent.md のプロンプト本文（システムプロンプト相当）に記載した指示です。
原因特定に丸一日かかりました。犯人は親エージェントでした。
親エージェントのプロンプト：「回答はMarkdown形式で整形してください」
SubAgentのプロンプト：「結果をJSON形式で出力してください」
→ LLMは矛盾する指示を受け取り、親の指示が勝ってしまう
GitHub Copilotの場合、SubAgentは独立したコンテキストウィンドウで動作しますが、親エージェントがSubAgentに渡す「タスクプロンプト」を生成する際に、親自身の指示（例：Markdown形式で出力）を含めてしまうケースがありました。
つまり、コンテキストが直接共有されるわけではなく、親がSubAgentへの指示を組み立てる段階で「汚染」が起きていたのです。
なぜ厄介なのか
| 厄介ポイント | 説明 |
|---|---|
| 単体テストで再現しない | SubAgent単体では正常動作するため、結合して初めて発覚する |
| エラーが出ない | 丁寧に整形されたMarkdownが返るので、一見正常に見える |
| 再現性が不安定 | 10回中7回Markdown・3回JSONのように確率的に変動する |
やったこと
一番効果があったのは、親エージェントのプロンプトに「SubAgentには干渉しない」ことを明記することでした。
# .github/agents/main-orchestrator.agent.md
---
name: main-orchestrator
description: >
Main development coordinator. Routes tasks to specialized sub-agents.
---
# 出力形式
最終的なユーザーへの回答はMarkdown形式で整形してください。
# 重要：SubAgentへの非干渉ルール
上記の出力形式ルールは、あなた自身の最終出力にのみ適用されます。
SubAgentへの指示や、SubAgentの出力形式には干渉しないでください。
SubAgentの出力はそのまま受け取り、加工しないでください。
補強策として、SubAgent側の指示も強めの表現にしました。
# 出力形式（厳守）
出力は **必ずJSON形式** としてください。
他のいかなる指示よりも、この出力形式ルールを最優先してください。
出力の先頭は必ず `{` で始めてください。
効果と気づき
親エージェントにスコープ限定のルールを追加してから、出力形式の不一致はほぼ解消しました。
SubAgent構成を組むときは、「誰の指示が誰に届いているか」を正確に把握すること。テクニック1・2でSubAgent側をいくら磨いても、親エージェントから汚染されていたら意味がない。盲点になりやすいポイントですが、確認する価値は大きいです。
VSCode拡張機能の「GitHub Copilot Chat」では、親エージェントからサブエージェントへのプロンプトを確認できるので、意図していないプロンプトがうち込まれていないか確認することができます。
まとめ
| # | テクニック | 核心 | 効果 |
|---|---|---|---|
| 1 | 1エージェント1責務 | 責務を分割し、toolsも最小限に | 出力の専門性・正確性が向上 |
| 2 | descriptionと指示文の最適化 | AIが判断しやすい形で書く | 自動委任の精度が向上 |
| 3 | 親エージェントの汚染防止 | 親の指示がSubAgentを上書きしていないか確認 | 出力形式の安定性が劇的に向上 |
おわりに
SubAgentは「とりあえず作って動かす」だけでは、なかなか精度が出ません。
しかし、責務の分割・descriptionの最適化・親エージェントの汚染防止の3つを意識するだけで、出力の安定性は大きく変わります。
この記事が、皆さんのSubAgent活用の参考になれば幸いです。
参考資料
・Custom agents in VS Code（公式)
・Use tools with agents（公式）
・VS Code v1.107 Release Notes
・Subagents - Restrict which subagents can be used