GitHub Copilot の custom agent サンプルをどう設計するか

前回の記事 では、planner / implementer / tester / reviewer / verifier のように、開発工程ごとに役割を分ける考え方を整理しました。今回はその続きとして、GitHub Copilot や VS Code の custom agent を設計するときに、各 agent に何を書き、何を書かないかをサンプル付きで整理します。

本記事の作成には生成AI（GitHub Copilot 等）を使用しています。

1. はじめに

custom agent を使い始めると、最初に迷いやすいのは「役割をどう分けるか」よりも「各 agent 定義にどこまで書くべきか」です。特にプロダクト開発では、planner に実装方針まで書きすぎたり、reviewer に修正までさせたりすると、責務が重なって振る舞いが不安定になりやすいです。

そこで本記事では、次の方針で custom agent の設計例を整理します。

• 小さく始める
• 責務を明確にする
• handoff を明示する
• tools は必要最小限にする
• 定義項目ごとに「書くこと」と「書かないこと」を分ける

前回の記事で扱った役割分担の考え方を引き継ぎつつ、今回は custom agent の定義サンプルと、各項目の意味に焦点を当てます。

2. 内容

2-1. custom agent 定義を考えるときの基本方針

custom agent の定義では、何でも書けばよいわけではありません。むしろ、1つの agent に多くの責務を持たせすぎるほど、出力のブレや手戻りが増えやすいです。

まずは 3 つの視点で整理すると考えやすいです。

1. その agent の成果物は何か
2. その agent が使ってよい手段は何か
3. 次にどの agent へ渡すのか

たとえば planner なら成果物は「作業計画や分割方針」であり、実装コードそのものではありません。implementer なら成果物は「コード変更」であり、品質判定の最終責任までは持たせません。reviewer なら成果物は「問題点と修正観点」であり、自動で広く書き換える役割とは分けたほうが扱いやすいです。

この考え方で設計すると、agent の instructions が短く保ちやすくなります。結果として、ユーザーが「なぜその応答になったか」を追いやすくなります。

2-2. 最小 3 役のサンプル定義

最初の構成としては、planner / implementer / reviewer の 3 役で十分なことが多いです。ここでは、1 つの YAML にまとめるのではなく、.github/agents 配下に agent ごとの .agent.md ファイルを置くイメージでサンプルを書きます。

.github/
  agents/
    planner.agent.md
    implementer.agent.md
    reviewer.agent.md

以下の Markdown は概念整理のためのサンプルです。実際に使える front matter の項目や tool 名は、利用している GitHub Copilot や VS Code のバージョン、機能差分によって変わることがあります。そのまま貼り付ける前提ではなく、役割分離の考え方を見るための例として読んでください。

planner.agent.md の例です。

---
name: planner
description: 要件整理、作業分割、影響範囲の確認を担当するエージェント
tools: [read, search]
user-invocable: true
---

# Planner Agent

## Role

- コードはまだ書かず、作業方針と確認事項を先に整理します。
- 変更対象、依存関係、リスクを短く列挙します。
- 実装に入る条件が揃ったら implementer へ渡します。

## Constraints

- 推測で仕様を補わない
- 未確認事項は未確認と明記する

## Output

- 変更対象の一覧
- 実装前の確認事項
- implementer へ渡す作業メモ

implementer.agent.md の例です。

---
name: implementer
description: planner の方針に沿ってコードや設定を変更するエージェント
tools: [read, edit, problems]
user-invocable: true
---

# Implementer Agent

## Role

- planner の範囲を超える設計変更は自分で拡張しません。
- 最小の変更で目的を達成します。
- 変更後は関連エラーを確認し、reviewer へ渡します。

## Constraints

- 無関係なリファクタリングをしない
- 既存の公開 API をむやみに変えない

## Handoff

- reviewer へ、変更理由と影響範囲を添えて渡します。

## Output

- 変更したファイル
- 変更理由
- 確認した内容

reviewer.agent.md の例です。

---
name: reviewer
description: 実装結果を確認し、バグ、回帰、テスト不足を指摘するエージェント
tools: [read, search, problems]
user-invocable: true
---

# Reviewer Agent

## Review Priorities

1. 重大な不具合や回帰
2. テスト不足や確認漏れ
3. 設計上の懸念

## Constraints

- 実装修正そのものは原則行わない
- 好みだけの指摘を主目的にしない

## Output

- 問題点
- 修正方針
- 必要なら追加で確認したい点

この 3 役で重要なのは、planner は実装しない、implementer は品質判定の主役になりすぎない、reviewer は広く実装修正しない、という線引きです。ここが曖昧だと、同じ観点が複数の agent に重複して書かれ、結果が不安定になります。

2-3. 拡張 5 役のサンプル

規模が少し大きくなったら、tester と verifier を追加して 5 役に広げる方法があります。前回の記事で扱った工程分離を、そのまま .github/agents 配下の追加ファイルへ落とし込むイメージです。

.github/
  agents/
    planner.agent.md
    implementer.agent.md
    tester.agent.md
    reviewer.agent.md
    verifier.agent.md

追加する 2 役の例です。

tester.agent.md の例です。

---
name: tester
description: テスト観点の整理、テスト追加、再現手順の明確化を担当するエージェント
tools: [read, edit, problems]
user-invocable: false
---

# Tester Agent

## Role

- implementer の変更に対して必要なテストだけを追加します。
- 正常系だけでなく、異常系や境界値も確認します。
- テスト結果や再現手順を verifier へ渡します。

## Constraints

- テストのために本体ロジックを広く書き換えない
- レビューコメントの役割まで持ちすぎない

## Output

- 追加したテスト
- 確認した観点
- verifier へ渡す確認メモ

verifier.agent.md の例です。

---
name: verifier
description: 要件、実装、テストがそろっているかを確認し、完了条件を整理するエージェント
tools: [read, search, problems]
user-invocable: false
---

# Verifier Agent

## Role

- 要件、実装、テストの対応関係を確認します。
- 不足があれば不足項目を返し、完了なら簡潔にまとめます。
- 自分では追加実装を始めず、確認結果の整理に徹します。

## Output

- 完了条件を満たしている点
- 不足している点
- 次に戻すべき相手

5 役構成の流れは一例として、planner → implementer → tester → reviewer → verifier のように直線で置くと、各役割の責任範囲を読み取りやすいです。この構成では、implementer が機能を作り、tester が検証コードや再現手順を補い、reviewer がコードレビュー観点を確認し、verifier が最終判定を行います。

役割分担を簡単に並べると、次のようになります。

役割	主な責務	書かないほうがよいこと
planner	要件整理、作業分割、影響範囲の明確化	実装詳細、広い修正案の確定
implementer	コード変更、最小限の検証	最終レビュー、完了判定
reviewer	問題点の指摘、回帰リスクの確認	実装作業の主担当
tester	テスト追加、再現条件の整理	本体コードの大規模改修
verifier	完了条件の確認、最終判定	追加実装の開始

必要に応じて、これらをまとめる parent agent 的な orchestrator を置く方法もあります。ただし、最初から複雑な親 agent を作るより、まずは user-invocable な 3 役または 5 役を明確に設計し、その後で handoff を束ねるほうが理解しやすいです。

2-4. 各項目は何を書くか

agent ごとの .agent.md に分ける場合は、front matter に置く項目と、本文見出しで表現する項目を分けて考えると整理しやすいです。ここでは、よく出てくる項目を「どこに書くか」「何を書きすぎないか」の観点で整理します。

項目	主に置く場所	主に書くこと	書かないほうがよいこと
name	front matter	役割がすぐ分かる短い名前	抽象的すぎる名前、複数責務を連想させる名前
description	front matter	その agent の目的と成果物	実行手順の細かい列挙
tools	front matter	その役割に本当に必要なツールだけ	念のための大量追加
user-invocable	front matter	ユーザーから直接呼ぶかどうか	運用意図がないままの有効化
instructions	本文の Role や Working Style	振る舞いの方針、優先順位	詳細すぎる業務手順書
handoff	本文の Handoff	次に渡す相手と渡す条件	全 agent への無差別な分岐
constraints	本文の Constraints	やらないこと、越えない範囲	description と重複する長文説明
output	本文の Output	期待する成果物の形	曖昧な完了条件
model	環境に応じて別管理または補足	求める応答品質やコストの考え方	役割と無関係な固定指定
argument-hint	description や prompt 側の補足	ユーザーが渡すと精度が上がる情報	実行時にしか分からない細かすぎる指定
agents	親 agent 側のファイル	配下の agent 一覧や全体構成	個別 agent の詳細 instructions の重複

それぞれもう少し補足します。

name

name は短く、役割が一目で分かるものが向いています。planner や reviewer のように一般的な名前でもよいですが、プロダクト特性に応じて api-reviewer や ui-implementer のように少し具体化するのも有効です。ただし、名前に責務を詰め込みすぎると、それだけで境界が曖昧になります。

description

description では「何を達成する agent か」を簡潔に書きます。ここで大切なのは、作業内容ではなく成果物の視点で書くことです。たとえば「コードを読む agent」よりも「変更方針を整理する agent」のほうが、役割が明確になります。

tools

tools は必要最小限が基本です。planner に編集系ツールを持たせる必要がないなら外しますし、reviewer に広い書き換え権限が不要なら与えません。ツールの絞り込みは、安全性だけでなく、役割の混線を防ぐ意味でも重要です。

model

model は、考察重視か、コスト重視か、応答速度重視かによって選び方が変わります。ただし、.agent.md の中に常に明示するとは限りません。利用環境によっては別の設定場所で管理されることもあるため、「レビュー役だけ上位モデルを検討する」といった考え方として持っておくと運用しやすいです。

instructions

agent ごとの .agent.md では、instructions を 1 つの項目名で持たず、Role や Working Style の見出しとして書く形が分かりやすいです。長く書きすぎると逆に読みづらくなるため、「何を優先するか」「何をしないか」「次にどう渡すか」を中心に 3 から 6 行程度へ絞ると扱いやすいです。

handoff

handoff は、agent を分ける設計において核になる項目です。.agent.md では Handoff という見出しで書くと分かりやすいです。たとえば planner から implementer、implementer から reviewer のように、自然な流れを定義しておくと、ユーザーも運用イメージを持ちやすいです。逆に handoff を曖昧にすると、どの役割が最終責任を持つのかがぼやけます。

constraints

constraints には、その agent がやらないことを明示します。これは instructions の補足ではなく、責務の境界線です。たとえば implementer に「無関係なリファクタリングをしない」と入れておくと、変更の広がりを抑えやすくなります。

argument-hint

argument-hint は、ユーザーがどの情報を渡せばよいかを事前に示すための考え方です。.agent.md に専用項目として持たせる場合もありますが、description や prompt 側の補足へ寄せる形でも十分です。たとえば implementer に「対象ファイル、変更目的、確認方法を含めて依頼してください」と書いておくと、やり取りの往復を減らしやすいです。

user-invocable

user-invocable は、その agent をユーザーが直接呼ぶかどうかの設計です。planner と reviewer は直接呼ぶ価値が高い一方で、verifier は orchestrator 経由だけでよい場合もあります。すべてを user-invocable にすると選択肢が増えすぎることがあります。

agents

ここでいう agents は、複数 agent のまとまりを表すための概念です。親 agent 側では全体の流れだけを書き、各子 agent の詳細 instructions を重複して持ち込みすぎないほうが、保守しやすいです。実際に使える定義項目や記述位置は、利用している GitHub Copilot や VS Code の機能とバージョンによって異なることがあります。

2-5. よくある失敗と設計上の注意

custom agent を実運用へ乗せるときは、次の失敗が起きやすいです。

1. description が広すぎる

「開発を支援する agent」のような description では、何を期待する役割か分かりません。成果物で言い切るほうが設計しやすいです。

2. instructions に全部書こうとする

instructions に細かな作法や例外処理を大量に書くと、かえって重要な原則が埋もれます。まずは短く始め、実運用でブレた点だけを追記するほうが保守しやすいです。

3. tools を盛り込みすぎる

どの agent でも編集、実行、検索を全部できる状態にすると、役割分担の意味が薄れます。必要最小限の付与にすると、想定外の動きを減らしやすいです。

4. reviewer と verifier の違いが曖昧

reviewer は問題点を見つける役割、verifier は完了条件を満たしたかを確認する役割です。この違いを定義に書かないと、どちらも似たレビューを返しやすくなります。

5. handoff がない、または多すぎる

handoff がないと、agent を分けた意味が弱くなります。一方で、どこからでも全員へ handoff できるようにすると流れが複雑になります。最初は直線的な流れから始めるほうが安全です。

6. user-invocable の設計が雑

内部向けの agent まで全部ユーザーに見せると、どれを選ぶべきか判断しづらくなります。ユーザーが直接使う agent と、内部で受け渡される agent を分けて考えると整理しやすいです。

2-6. まずはどう始めるか

最初の一歩としては、次の順で進めると試しやすいです。

1. planner / implementer / reviewer の 3 役だけ作る
2. 各 agent の description と constraints を短く書く
3. tools を最小限に絞る
4. handoff を planner → implementer → reviewer の一直線にする
5. 実際の開発タスクで試し、責務の重なりが出たら tester や verifier を追加する

この順で進めると、いきなり複雑な multi-agent 構成にせずに済みます。特に初期段階では、agent の数を増やすよりも、各 agent が何をしないかを明確にするほうが効果が出やすいです。

3. まとめ

custom agent の設計では、「役割を増やすこと」よりも「各役割に何を書くか、何を書かないか」を整理することが重要です。最小構成としては planner / implementer / reviewer の 3 役から始め、必要に応じて tester / verifier を追加すると、責務の分離を保ちやすいです。

特に意識したいのは、description を成果物で書くこと、tools を必要最小限にすること、handoff を明示すること、constraints で越えない範囲を定義することです。この 4 点が固まると、custom agent の挙動はかなり読みやすくなります。

GitHub Copilot や VS Code の custom agent は今後も更新される可能性があります。実際に導入するときは、この記事のサンプルをたたき台として使いながら、利用中の環境で使えるキー名や挙動を公式ドキュメントで確認することをおすすめします。

ちなみに、カスタムエージェントは user-invocable を true にすることで、Agent、Ask、Plan の選択一覧に追加されます。

A. 参考サイト

• GitHub Docs: GitHub Copilot のドキュメント
• Visual Studio Code Docs: AI と Copilot に関するドキュメント
• Visual Studio Code Docs: Chat and AI extensibility

B. 関連書籍