カスタムエージェント — プレイブック

一言で

Custom Agent は、Copilot に 役割・道具・振る舞い をセットで渡す専門家プロファイル。

「同じ AI」でも、Planner / Reviewer / Tester のように人格と権限を切り替えられる。

何を固定する？

Custom Agent は プロンプトだけ ではなく、エージェントの「働き方」をまとめて固定する。

要素	何を決める？	例
Identity	何者として振る舞うか	`Planner`, `Security Reviewer`, `Test Specialist`
Description	いつ呼ぶべきか	「実装前に計画を作る時」
Tools	どの道具を使えるか	`read`, `search`, `edit`, `agent`, `github/*`
Agents	どのサブエージェントに委任できるか（`tools` に `agent` が必要）	`Research`, `Reviewer`, `*`
Model	どのモデルで動くか	設計は強いモデル、探索は速いモデル
Target	どの実行環境で使うか	`github-copilot`, `vscode`
MCP	専用の外部ツール	Jira, Figma, Playwright, internal API
Prompt	判断基準・出力形式	成功条件、禁止事項、レビュー観点

4 つのスコープ

同じ .agent.md を 4 つのレベルで配布できる。適用範囲が広いほどガバナンスが重要になる。

	🏢 Enterprise	🏛️ Organization	👥 Repository	👤 個人用
📁 場所	指定した org の `.github-private` → `/agents/`	org の `.github` または `.github-private` → `/agents/`	`.github/agents/`	`~/.copilot/agents/`
🎯 適用範囲	enterprise 内の全 repository	organization のメンバー全員	その repository / workspace	自分の全 workspace
🤝 管理者	enterprise owner / AI manager	organization owner	repository のチーム（Git 管理）	自分だけ
💡 用途	全社標準・コンプライアンス	部門標準の Planner / Reviewer	プロジェクト固有の Tester / Reviewer	個人の作業スタイル・好み

🆕 Organization / Enterprise スコープは public preview。配布元リポジトリへのアクセス権がないメンバーにも agent が届く。 🛡️ Enterprise owner は ruleset で agent ファイルを保護できる。対象を指定した organization に絞らないと、org owner による organization レベル agent の編集までブロックされる。

`.agent.md` の中身

Custom Agent は Markdown ファイル。上の YAML frontmatter が設定、下の本文がエージェントへの指示になる。設定可能な全フィールドは Custom agents configuration リファレンスを参照。

---
name: design-reviewer
description: Figma と実装を照合して UI 差分をレビューする
target: github-copilot
model: Claude Sonnet 4.5
tools:
  - read
  - search
  - github/pull-request-read
  - figma/*
mcp-servers:
  figma:
    type: local
    command: npx
    args: ["-y", "figma-mcp-server"]
---

# Role

あなたは UI 実装の design reviewer。
Figma の仕様と Pull Request の差分を比較し、見た目・余白・色・状態差分だけをレビューする。

# Rules

- コードは編集しない
- blocking / non-blocking を分けて指摘する
- 再現手順と確認すべき画面幅を必ず書く
- 推測で断定せず、Figma または diff に根拠があるものだけ指摘する

良い Custom Agent は「誰か」ではなく、どの判断を任せるか が明確。

Agent と内部 Subagent

VS Code でユーザーが選べるのは Agent、Plan、Ask。searchSubagent のような内部 helper は、別の Agent が呼び出す tool であり、選択可能な .agent.md profile ではない。

Surface	Agent / tool	何をする？
Copilot Chat / VS Code	Agent	編集と tool を使って複雑な task を実装する
Copilot Chat / VS Code	Ask	変更せずに質問へ回答し、必要な調査を行う
Copilot Chat / VS Code	Plan	調査して、複数ステップの計画を組み立てる
VS Code internal	`searchSubagent`	独立した context で並列に codebase を調査し、summary を返す

🔑 VS Code の旧 Explore 相当の動作は searchSubagent に移った。Prompt と tool は TypeScript/TSX で実装され、編集可能な Explore .agent.md は存在しない。

Copilot CLI の組み込み Subagent

Agent	得意な task
Explore	高速で read-only の codebase 調査
Task	Tests、builds、出力の多い command の実行
General-purpose	Full toolset を使う複雑な multi-step task
Rubber-duck	計画や実装を独立レビュー。`/subagents` で別の model を割り当て、作成に使った model とは異なる視点で test できる
Code-review	Diff の確度が高い review
Research	Citation 付きの GitHub と Web の徹底調査
Security-review	確度が高い脆弱性 review

🦆 Rubber-duck の強みは cross-model review。同じ model に自己評価させるのではなく、別の model に計画や実装を批判させることで、見落としや思考の偏りを発見しやすくなる。

ハーネスの中で何が起きる？

ユーザーが Custom Agent を呼ぶと、ハーネスは .agent.md を取得し、利用可能なツールを絞り込み、エージェント定義を差し込み、最後にプロンプトを追加する。最終的にモデルに渡るコンテキストは SYSTEM & TOOLS / INSTRUCTIONS / CUSTOM AGENT / PROMPT の 4 層。

💡 INSTRUCTIONS は元から常に入っている層。Custom Agent が増やすのは TOOLS の絞り込み・AGENT 定義・PROMPT の 3 つだけ。

サブエージェント

例えば調査が必要なときは、メインエージェント が サブエージェント を作ることがあります。サブエージェントは別の コンテキストウインドウ で重い読み込みをこなし、サマリだけ を メインエージェント に返す。

Custom Agent で適材適所の LLM を活用

AI モデルは、それぞれ異なるデータ・異なるアーキテクチャで学習されている。すべてに最強な単一モデルは存在しない。

📚 異なる学習データ

学習コーパスが違えば、知識の穴と強みも変わる。

⚙️ 異なるアーキテクチャ

推論力・速度・コンテキスト長。モデルごとに得意なタスクが違う。

✅ クロス検証

同じタスクを複数モデルで走らせると、1 モデルでは見逃すバグに気づける。

🎯 コスト最適化

タスクごとの最適モデル選びは、品質だけでなく予算の話にもなる。

Claude + Gemini + Codex + Microsoft を、統制・監査可能な 単一プラットフォーム で動かせるのは Copilot だけ。

ベストなモデルは？ ❌

「一番いいモデルは？」 ➡️ 間違った問い
「このタスクに一番いいモデルは？」 ➡️ 良い問い

開発タスク	ベストなモデル：コスト/性能（例）
要件定義	Claude Opus 4.8
アーキテクチャ・設計	Gemini 3.1 Pro
コード計画	Claude Opus 4.8
コード生成	Claude Sonnet 4.6
テスト作成	Claude Sonnet 4.6
コードレビュー	GPT-5.5 Codex
CI/CD・自動化	GPT-5.4 Codex
ドキュメント	Gemini 3.1 Pro
大量処理・コスト重視	MAI-Code-1-Flash

● Anthropic ● OpenAI ● Google ● Microsoft

出典（ベンチマーク）：SWE-bench Verified ↗ ・ Terminal-Bench ↗ ・ Aider Polyglot ↗ ・ LMArena ↗。モデルはあくまで一例で、タスクや好みによって変わる。