はじめに

GitHub CopilotのカスタムエージェントにはHandoff（ハンドオフ）と呼ばれる機能があります。Handoffを活用すると、複数のエージェント間でコンテキストを引き継ぎながら、開発タスクを順序立てて進めることができます。

たとえば「計画を立てる」「コードを実装する」「レビューする」といった一連の作業を、エージェントを切り替えながらシームレスに実行できます。各ステップで開発者がレビューと承認を行うため、AIに完全に任せるのではなく、人間が制御を維持しながら効率化を図れます。

本記事では、GitHub Copilotカスタムエージェントのハンドオフ機能について、実践的なユースケースと設計パターンを詳しく解説します。

前提条件

Handoff機能を利用するには、以下の環境が必要です。

項目 要件
VS Code バージョン1.106以降
GitHub Copilot拡張機能 最新版
GitHub Copilotサブスクリプション Individual、Business、Enterprise、または無料プラン

カスタムエージェントの基本的な作成方法については、GitHub Copilot Custom Agent完全ガイドを参照してください。

Handoff機能とは

Handoffは、カスタムエージェント間で順序立てたワークフローを構築するための機能です。チャット応答が完了すると、定義したハンドオフボタンが表示され、ワンクリックで次のエージェントに移行できます。

Handoffが解決する課題

従来のCopilot Chat利用では、以下のような課題がありました。

  • 計画フェーズから実装フェーズに移る際、毎回手動でエージェントを切り替える必要がある
  • 前のフェーズで生成したコンテキストを次のエージェントに明示的に伝える必要がある
  • 複数ステップのワークフローで一貫性を保つのが難しい
  • チームメンバー間でワークフローにばらつきが生じる

Handoff機能を使用すると、これらの課題を解消し、一貫した開発フローを実現できます。

Handoffの動作原理

Handoffは以下の流れで動作します。

  1. エージェントAがタスクを完了する
  2. チャット応答の下にハンドオフボタンが表示される
  3. ユーザーがボタンをクリックする
  4. エージェントBに切り替わり、事前定義されたプロンプトが入力欄に表示される
  5. send: trueの場合はプロンプトが自動送信される

この仕組みにより、開発者は各ステップの結果を確認しながら、スムーズに次のフェーズに進めます。

Handoffの設定方法

カスタムエージェントファイル（.agent.md）のYAMLフロントマターでhandoffsプロパティを定義します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
name: Planner
description: 実装計画を生成します
tools: ['search', 'codebase', 'usages']
handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: 上記の計画に基づいて実装を開始してください。
    send: false
---

handoffsプロパティの構成

プロパティ 説明 必須
label ハンドオフボタンに表示されるテキスト 必須
agent 切り替え先のエージェント識別子 必須
prompt 次のエージェントに送信するプロンプト 必須
send プロンプトを自動送信するか（デフォルト: false） 任意

複数のハンドオフ先を定義

1つのエージェントから複数の異なるエージェントへのハンドオフを定義することも可能です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
name: Planner
description: 実装計画を生成します
tools: ['search', 'codebase', 'usages']
handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: 上記の計画に基づいて実装してください。
    send: false
  - label: テストから開始
    agent: tdd-red
    prompt: 上記の計画に基づいて、まず失敗するテストを作成してください。
    send: false
  - label: 計画をレビュー
    agent: reviewer
    prompt: 上記の計画をレビューしてください。
    send: false
---

この設定により、計画完了後に「実装を開始」「テストから開始」「計画をレビュー」の3つのボタンが表示されます。状況に応じて適切なワークフローを選択できます。

実践ユースケース1：計画から実装へのワークフロー

最も基本的かつ効果的なユースケースが、計画フェーズから実装フェーズへの連携です。

ワークフローの概要

[Planner] → [Implementer] → [Reviewer]
   ↓            ↓              ↓
 計画生成    コード実装     品質確認

planner.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

---
name: Planner
description: 新機能の実装計画を策定します
tools: ['search', 'codebase', 'usages', 'fetch', 'githubRepo']
model: Claude Sonnet 4
handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: 上記の計画に従って実装を開始してください。計画の各ステップを順番に実行し、進捗を報告してください。
    send: false
---

# 計画エージェント

あなたは戦略的なソフトウェアアーキテクトです。実装前の計画策定に特化しています。

## 責務

- コードの編集は一切行わない
- 既存コードベースを分析し、最適な実装アプローチを提案する
- 実装手順を詳細なステップに分解する

## 出力形式

以下のセクションを含むMarkdownドキュメントを生成してください。

### 概要
変更の目的と期待される成果を簡潔に記述

### 影響範囲
変更が影響するファイルとコンポーネントのリスト

### 実装ステップ
番号付きリストで具体的な実装手順を記述

### 考慮事項
パフォーマンス、セキュリティ、後方互換性に関する注意点

### テスト戦略
実装後に必要なテストの概要

implementer.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

---
name: Implementer
description: 計画に基づいてコードを実装します
tools: ['editFiles', 'runCommand', 'search', 'codebase', 'problems']
model: Claude Sonnet 4
handoffs:
  - label: レビューを依頼
    agent: reviewer
    prompt: 上記の実装をレビューしてください。コード品質、パフォーマンス、セキュリティの観点でフィードバックをお願いします。
    send: false
  - label: テストを作成
    agent: tester
    prompt: 上記の実装に対するテストを作成してください。
    send: false
---

# 実装エージェント

あなたは経験豊富なソフトウェアエンジニアです。計画に基づいて高品質なコードを実装します。

## 責務

- 計画で指定されたステップに従って実装する
- 既存のコードスタイルとパターンに従う
- 実装後にコンパイル/リントエラーがないことを確認する

## 実装ルール

- 1つのステップを完了するごとに進捗を報告する
- 不明点がある場合は実装前に確認する
- 既存のテストが壊れないよう注意する

reviewer.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

---
name: Reviewer
description: コードレビューを行います
tools: ['search', 'codebase', 'problems', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: 修正を適用
    agent: implementer
    prompt: 上記のレビューコメントに基づいて修正を行ってください。
    send: false
---

# レビューエージェント

あなたは厳格なコードレビュアーです。品質とベストプラクティスの観点でコードを評価します。

## レビュー観点

### コード品質
- 可読性と保守性
- 適切な命名規則
- コメントの妥当性

### パフォーマンス
- 不要なループや処理
- メモリリークの可能性
- N+1問題

### セキュリティ
- 入力検証
- 認証・認可
- 機密情報の取り扱い

## 出力形式

問題点ごとに以下の形式で報告してください。

- 重要度：Critical / Major / Minor / Suggestion
- 対象ファイル・行番号
- 問題の説明
- 推奨される修正方法

期待される結果

このワークフローを使用すると、以下の流れで開発が進みます。

  1. Plannerエージェントに「ユーザー認証機能を追加したい」と依頼
  2. 詳細な実装計画がMarkdown形式で出力される
  3. 「実装を開始」ボタンをクリック
  4. Implementerエージェントが計画に従ってコードを実装
  5. 「レビューを依頼」ボタンをクリック
  6. Reviewerエージェントがコードを評価しフィードバック
  7. 必要に応じて「修正を適用」で再度Implementerに戻る

実践ユースケース2：TDDワークフロー

テスト駆動開発（TDD）のRed-Green-Refactorサイクルをハンドオフで実現します。

ワークフローの概要

[TDD-Red] → [TDD-Green] → [TDD-Refactor] → [TDD-Red]
    ↓           ↓              ↓              ↓
 失敗テスト   最小実装      リファクタ    次のテスト

tdd-red.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

---
name: TDD-Red
description: 失敗するテストを作成します（TDD Red Phase）
tools: ['editFiles', 'runCommand', 'search', 'codebase']
model: Claude Sonnet 4
handoffs:
  - label: テストを通す
    agent: tdd-green
    prompt: 上記の失敗テストを通すための最小限のコードを実装してください。
    send: false
---

# TDD Red Phase エージェント

テスト駆動開発のRedフェーズを担当します。まず失敗するテストを作成します。

## 原則

- 実装コードより先にテストを書く
- 1つのテストで1つの振る舞いのみを検証する
- テストは必ず失敗することを確認する

## テスト命名規則

\`\`\`
Should_期待する結果_When_条件
\`\`\`

例: `Should_ReturnError_When_EmailIsInvalid`

## 実行手順

1. 要件を確認し、テストすべき振る舞いを特定
2. テストコードを作成
3. テストを実行し、失敗することを確認
4. 失敗理由が「実装が存在しない」ことを確認

tdd-green.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

---
name: TDD-Green
description: テストを通す最小限のコードを実装します（TDD Green Phase）
tools: ['editFiles', 'runCommand', 'search', 'problems']
model: Claude Sonnet 4
handoffs:
  - label: リファクタリング
    agent: tdd-refactor
    prompt: テストが通ることを維持しながら、コードをリファクタリングしてください。
    send: false
---

# TDD Green Phase エージェント

テスト駆動開発のGreenフェーズを担当します。テストを通す最小限のコードを実装します。

## 原則

- テストを通すために必要な最小限のコードのみを書く
- 完璧な設計は後回しにする
- すべてのテストが通ることを確認する

## 禁止事項

- テストに関係ない機能を追加しない
- 過度な最適化を行わない
- 新しいテストを追加しない

## 実行手順

1. 失敗しているテストを確認
2. テストを通す最小限のコードを実装
3. テストを実行し、成功することを確認

tdd-refactor.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

---
name: TDD-Refactor
description: テストを維持しながらコードを改善します（TDD Refactor Phase）
tools: ['editFiles', 'runCommand', 'search', 'usages', 'problems']
model: Claude Sonnet 4
handoffs:
  - label: 次のテストへ
    agent: tdd-red
    prompt: 次の機能要件に対する失敗テストを作成してください。
    send: false
  - label: 完了
    agent: reviewer
    prompt: TDDサイクルで作成したコードとテストをレビューしてください。
    send: false
---

# TDD Refactor Phase エージェント

テスト駆動開発のRefactorフェーズを担当します。テストを維持しながらコードを改善します。

## 原則

- テストが常に通ることを確認しながら変更する
- 振る舞いを変更しない
- 小さなステップでリファクタリングする

## リファクタリング観点

- 重複コードの抽出
- 意味のある命名への変更
- 複雑な条件分岐の簡素化
- 責務の分離

## 実行手順

1. 現在のテストがすべて通ることを確認
2. 1つのリファクタリングを実施
3. テストを実行し、成功することを確認
4. 必要に応じて2-3を繰り返す

期待される結果

このワークフローを使用すると、以下のサイクルで開発が進みます。

  1. TDD-Redエージェントに「ユーザー登録機能のバリデーション」を依頼
  2. メールアドレス検証の失敗テストが作成される
  3. 「テストを通す」ボタンで最小実装が行われる
  4. 「リファクタリング」ボタンでコードが改善される
  5. 「次のテストへ」で次の要件のテストを作成

実践ユースケース3：セキュリティレビューワークフロー

セキュリティ観点でのコードレビューと修正を連携させるワークフローです。

security-scanner.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

---
name: SecurityScanner
description: セキュリティ脆弱性をスキャンします
tools: ['search', 'codebase', 'problems', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: 脆弱性を修正
    agent: security-fixer
    prompt: 上記で検出された脆弱性を修正してください。優先度の高いものから順に対応してください。
    send: false
  - label: 詳細分析
    agent: security-analyst
    prompt: 上記の脆弱性について、攻撃シナリオと影響範囲の詳細分析を行ってください。
    send: false
---

# セキュリティスキャナーエージェント

コードのセキュリティ脆弱性を検出します。

## スキャン対象

### インジェクション系
- SQLインジェクション
- コマンドインジェクション
- XSS（クロスサイトスクリプティング）
- パストラバーサル

### 認証・認可
- ハードコードされた認証情報
- 不適切なセッション管理
- 権限チェックの欠落

### データ保護
- 機密情報の平文保存
- 安全でない暗号化
- ログへの機密情報出力

## 出力形式

| 重要度 | 脆弱性タイプ | ファイル | 行番号 | 説明 | CVSSスコア目安 |
|--------|-------------|---------|--------|------|---------------|

security-fixer.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

---
name: SecurityFixer
description: セキュリティ脆弱性を修正します
tools: ['editFiles', 'search', 'codebase', 'problems']
model: Claude Sonnet 4
handoffs:
  - label: 修正を検証
    agent: security-scanner
    prompt: 修正後のコードを再スキャンし、脆弱性が解消されたことを確認してください。
    send: false
---

# セキュリティ修正エージェント

検出されたセキュリティ脆弱性を修正します。

## 修正方針

- 優先度の高い脆弱性から順に対応
- 既存機能を壊さない
- セキュリティベストプラクティスに従う

## 修正パターン

### SQLインジェクション対策
パラメータ化クエリまたはORMを使用

### XSS対策
出力時のエスケープ処理を追加

### 認証情報のハードコード
環境変数または設定ファイルへ移動

期待される結果

  1. SecurityScannerがコードベース全体をスキャン
  2. 検出された脆弱性がリスト形式で出力される
  3. 「脆弱性を修正」で自動修正が行われる
  4. 「修正を検証」で再スキャンし、修正確認

実践ユースケース4：ドキュメント生成ワークフロー

コードからドキュメントを生成し、レビュー・改善を行うワークフローです。

doc-analyzer.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

---
name: DocAnalyzer
description: コードを分析してドキュメント構造を提案します
tools: ['search', 'codebase', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: ドキュメント生成
    agent: doc-writer
    prompt: 上記の分析に基づいてドキュメントを生成してください。
    send: false
---

# ドキュメント分析エージェント

コードベースを分析し、必要なドキュメントの構造を提案します。

## 分析対象

- 公開API・エンドポイント
- エクスポートされたクラス・関数
- 設定オプション
- データモデル

## 出力形式

ドキュメント化が必要な項目と推奨される構造を提案します。

doc-writer.agent.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
name: DocWriter
description: 技術ドキュメントを生成します
tools: ['editFiles', 'search', 'codebase', 'fetch']
model: Claude Sonnet 4
handoffs:
  - label: ドキュメントをレビュー
    agent: doc-reviewer
    prompt: 生成されたドキュメントの正確性と完全性をレビューしてください。
    send: false
---

# ドキュメント生成エージェント

分析結果に基づいて技術ドキュメントを生成します。

## 出力形式

- Markdown形式
- コード例を含める
- Mermaid記法で図を作成

Handoff設計のベストプラクティス

1. 明確な責務分離

各エージェントの責務を明確に定義し、重複を避けます。

1
2
3
4
5

# 良い例：責務が明確
handoffs:
  - label: 実装を開始
    agent: implementer  # 実装のみを担当
    prompt: 上記の計画を実装してください。

2. 適切なsend設定

send: trueは慎重に使用します。自動送信は便利ですが、ユーザーがプロンプトを確認・編集する機会を奪います。

1
2
3
4
5
6

# 推奨：ユーザー確認を挟む
handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: 上記の計画を実装してください。
    send: false  # ユーザーがプロンプトを確認できる

3. 双方向のハンドオフ

レビューから実装に戻るなど、双方向のワークフローを設計します。

1
2
3
4
5

# reviewer.agent.md
handoffs:
  - label: 修正を適用
    agent: implementer
    prompt: 上記のフィードバックに基づいて修正してください。

4. コンテキストの引き継ぎ

プロンプトには前のステップの成果物を参照する指示を含めます。

1
2
3
4
5
6
7
8

handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: |
      上記の計画に基づいて実装を開始してください。
      特に以下の点に注意してください：
      - 計画で指定された実装順序に従う
      - 影響範囲に記載されたファイルを変更対象とする

トラブルシューティング

ハンドオフボタンが表示されない

以下の点を確認してください。

  • YAMLフロントマターの構文エラーがないか
  • handoffsプロパティが正しくインデントされているか
  • agentで指定したエージェントが存在するか

次のエージェントに切り替わらない

  • 指定したエージェント名が正確か確認
  • エージェントファイルが.github/agents/に配置されているか確認
  • VS Codeを再読み込みしてみる

プロンプトが正しく引き継がれない

  • promptプロパティの値が文字列として正しく定義されているか確認
  • 複数行のプロンプトは|を使用してYAMLブロック記法で記述
1
2
3
4
5
6

handoffs:
  - label: 実装を開始
    agent: implementer
    prompt: |
      上記の計画に基づいて実装してください。
      計画の各ステップを順番に実行してください。

まとめ

GitHub Copilotカスタムエージェントのハンドオフ機能を活用することで、以下のような開発ワークフローの自動化が実現できます。

  • 計画から実装、レビューまでのシームレスな連携
  • TDDのRed-Green-Refactorサイクルの自動化
  • セキュリティレビューと修正の反復プロセス
  • ドキュメント生成とレビューのワークフロー

ハンドオフは各ステップで開発者のレビューと承認を挟むため、AIに完全に任せるのではなく、人間が制御を維持しながら効率化を図れる点が大きな利点です。

まずはシンプルな2エージェント間のハンドオフから始め、徐々に複雑なワークフローを構築していくことをおすすめします。

参考リンク