GitHub Copilotの設定 - サブエージェント

概要

カスタムエージェントは、Copilotコーディングエージェントの専門化バージョンであり、独自のワークフロー、コーディング規約、ユースケースに合わせてカスタマイズできる機能である。
チーム固有の実践を定義し、組織の標準やコーディング規約に自動で従う動作が可能である。

カスタムエージェントは、以下に示す特徴を持つ。

専門化されたエージェントのプロファイル
明示的な呼び出しによる実行 (@agent-name)
ツールとMCPサーバーの細かい制御
組織レベル・エンタープライズレベルでの一元管理

カスタムエージェントを使用することにより、以下に示すメリットが得られる。

専門領域に特化したエージェントの作成
テスト専門、セキュリティ専門、ドキュメント専門等のエージェントを定義できる。
スコープの明確化
各エージェントの権限と責任を明確に定義し、予期しない動作を防止できる。
組織標準の統一
組織全体で統一されたコーディング規約とベストプラクティスを自動適用できる。
再利用可能な設定
複数のプロジェクトで同じエージェント設定を共有できる。

他の設定ファイルとの違い

GitHub Copilotは、複数の指示ファイルをサポートしている。

設定ファイルの比較

下表に、GitHub Copilot対応の設定ファイルの比較を示す。

GitHub Copilot対応の設定ファイルの比較
設定ファイル	配置場所	用途	呼び出し方法
copilot-instructions.md	.github/copilot-instructions.md	リポジトリ全体のカスタム指示	自動適用 (常時オン)
*.instructions.md	.github/instructions/*.instructions.md	パス固有のカスタム指示	自動適用 (該当パスで)
AGENTS.md	リポジトリルート (ネスト可)	コーディングエージェント向け指示	自動適用 (常時オン)
カスタムエージェント	.github/agents/*.agent.md	専門化されたエージェントのプロファイル	明示的に呼び出し (@agent-name)

推奨される使い分けを以下に示す。

copilot-instructions.md
プロジェクトの概要、技術スタック、全体的なコーディング規約
*.instructions.md
TypeScript固有のルール、フロントエンド専用の規約、APIルートの要件
AGENTS.md
ビルドコマンド、テストコマンド、プロジェクト構造、エージェントの動作範囲、境界設定
カスタムエージェント
特定の領域に特化した専門エージェント (テスト、セキュリティ、ドキュメント等)

ファイル配置場所と優先順位

カスタムエージェントファイルは、複数のレベルに配置可能である。

配置レベル

カスタムエージェントファイルを配置可能なレベルを以下に示す。

リポジトリレベル (最高優先度)
.github/agents/ ディレクトリ内

例: .github/agents/test-expert.agent.md
組織レベル
{org}/.github/agents/ または {org}/.github-private/agents/

組織全体で共有するエージェント設定
エンタープライズレベル
.github-private リポジトリの agents/

エンタープライズ全体で統一された設定
ユーザレベル
~/.copilot/agents ディレクトリ内

個人用のエージェント設定

優先順位を以下に示す。

リポジトリレベル (最優先)
組織レベル
エンタープライズレベル
ユーザーレベル (最低優先度)

同名のエージェントが複数のレベルに存在する場合、より高い優先度のファイルが使用される。

ディレクトリ構成例

ディレクトリ構成の例を以下に示す。

project/
├── .github/
│   ├── copilot-instructions.md              # リポジトリ全体の基本指示
│   │
│   ├── instructions/                        # パス固有の指示ファイル
│   │   ├── frontend.instructions.md
│   │   ├── backend.instructions.md
│   │   └── testing.instructions.md
│   │
│   └── agents/                              # カスタムエージェント定義
│       ├── readme-specialist.agent.md       # README専門
│       ├── test-expert.agent.md             # テスト専門
│       ├── security-reviewer.agent.md       # セキュリティレビュー専門
│       └── docs-writer.agent.md             # ドキュメント執筆専門
│
├── AGENTS.md                                # プロジェクト全体のエージェント指示
└── README.md

ファイル形式

カスタムエージェントファイルは、Markdown形式で記述する。

ファイル名規則

カスタムエージェントファイルの命名規則を以下に示す。

ファイル拡張子
*.agent.md または *.md
使用可能な文字
英数字、ハイフン (-)、ピリオド (.)、アンダースコア (_)
ファイル名の例
test-expert.agent.md、security-reviewer.md、readme-specialist.agent.md

ファイル名がエージェント名として使用される (YAMLフロントマターで上書き可能)。

ファイル構成

カスタムエージェントファイルの基本構成を以下に示す。

 ---
 name: agent-name
 description: エージェントの目的と機能の説明
 target: vscode
 tools:
   - read
   - edit
   - search
 infer: false
 ---
 
 あなたは〇〇専門家です。以下の職務を遂行してください:
 
 * 責任1
 * 責任2
 * 責任3
 
 ## 禁止事項
 
 * 禁止事項1
 * 禁止事項2

プロンプト部分の最大文字数は、30,000文字である。

YAMLフロントマターのプロパティ

カスタムエージェントファイルは、YAMLフロントマターで設定を定義する。

プロパティ一覧

下表に、YAMLフロントマターのプロパティを示す。

YAMLフロントマターのプロパティ
プロパティ	型	必須	説明
name	文字列	いいえ	エージェントの表示名 (省略時はファイル名を使用)
description	文字列	はい	エージェントの目的と機能の説明
target	文字列	いいえ	対象環境 (vscode または github-copilot)
tools	リスト	いいえ	アクセス可能なツール名のリスト
mcp-servers	オブジェクト	いいえ	MCPサーバーの追加設定 (組織・エンタープライズレベルのみ)
infer	ブール値	いいえ	コンテキストに基づく自動使用の制御 (デフォルト: true)
metadata	オブジェクト	いいえ	名前と値のペアで構成される注釈データ
model	文字列	いいえ	IDE環境での使用モデル指定 (VS Code 1.106以降)

主要プロパティの詳細

主要なプロパティの詳細を以下に示す。

name

エージェントの表示名を指定する。

型
文字列
必須
いいえ (省略時はファイル名を使用)
用途
エージェントを呼び出す際の表示名 (@name で呼び出し)

設定例を以下に示す。

 ---
 name: test-expert
 description: ユニットテストとテストカバレッジの最適化を支援するエージェント
 ---

description

エージェントの目的と機能の説明を記述する。

型
文字列
必須
はい
用途
エージェント選択時の説明文として表示される

記述例を以下に示す。

 ---
 description: README.mdファイルと関連ドキュメントの作成・改善に特化したエージェント
 ---

target

対象環境を指定する。

型
文字列
必須
いいえ
指定可能な値
vscode、github-copilot
用途
エージェントを特定の環境でのみ使用可能にする

設定例を以下に示す。

 ---
 target: vscode
 description: VS Code専用のテスト支援エージェント
 ---

tools

エージェントがアクセス可能なツールを指定する。

型
リスト
必須
いいえ
デフォルト
すべてのツール (組み込みおよびMCPサーバー由来) が有効

ツール設定のパターンを以下に示す。

デフォルト (全ツール有効):

 ---
 description: 全ツールにアクセス可能なエージェント
 ---

特定ツールのみ有効:

 ---
 tools:
   - read
   - edit
   - search
 description: 読み取り、編集、検索のみ可能なエージェント
 ---

全ツール無効化:

 ---
 tools: []
 description: ツールを使用しない会話専用エージェント
 ---

MCPサーバーツールの指定:

 ---
 tools:
   - read
   - search
   - playwright/navigate
   - playwright/screenshot
 description: Playwrightツールにアクセス可能なエージェント
 ---

ワイルドカードの使用:

 ---
 tools:
   - read
   - playwright/*
 description: Playwrightの全ツールにアクセス可能なエージェント
 ---

infer

コンテキストに基づく自動使用の制御を指定する。

型
ブール値
必須
いいえ
デフォルト
true
用途
true の場合、エージェントはコンテキストに応じて自動的に使用される。false の場合、明示的な呼び出しのみで動作する。

設定例を以下に示す。

 ---
 infer: false
 description: 明示的に呼び出された場合のみ動作するエージェント
 ---

model

IDE環境での使用モデルを指定する。

型
文字列
必須
いいえ
対応環境
VS Code 1.106以降
用途
エージェントが使用するAIモデルを明示的に指定する

設定例を以下に示す。

 ---
 model: gpt-4
 description: GPT-4モデルを使用するエージェント
 ---

MCP設定

MCPサーバの追加設定は、組織レベルおよびエンタープライズレベルのカスタムエージェントでのみ使用可能である。

基本設定

MCPサーバーの基本設定を以下に示す。

 mcp-servers:
   - name: server-name
     url: https://example.com/mcp-server
     env:
       KEY: $COPILOT_MCP_ENV_VAR_VALUE

設定可能なプロパティを以下に示す。

name
MCPサーバの識別子
url
MCPサーバのURL
env
環境変数の設定 (キーと値のペア)

環境変数参照形式

環境変数を参照する際の形式を以下に示す。

標準形式
$COPILOT_MCP_ENV_VAR_VALUE
Claude Code構文
${COPILOT_MCP_ENV_VAR_VALUE}
GitHub Actions形式
${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
変数参照形式
${{ var.COPILOT_MCP_ENV_VAR_VALUE }}

環境変数参照の例を以下に示す。

 mcp-servers:
   - name: jfrog-security
     url: https://mcp.jfrog.com/security
     env:
       JFROG_API_KEY: ${{ secrets.JFROG_SECURITY_API_KEY }}
       JFROG_URL: ${{ var.JFROG_BASE_URL }}

作成方法

カスタムエージェントの作成方法を以下に示す。

GitHub.comから作成

GitHub.comからカスタムエージェントを作成する手順を以下に示す。

https://github.com/copilot/agents にアクセスする。
[Create an agent]を選択する。
エージェントの設定を入力する。
保存する。

VS Codeから作成

VS Codeからカスタムエージェントを作成する手順を以下に示す。

Chat viewを開く。
[Configure Custom Agents]を選択する。
保存場所を選択する。(リポジトリレベル、組織レベル、ユーザレベル)
エージェントの設定を入力する。
保存する。

JetBrains IDEから作成

JetBrains IDEからカスタムエージェントを作成する手順を以下に示す。

Chat viewを開く。
設定アイコンを選択する。
[Configure Custom Agents]を選択する。
エージェントの設定を入力する。
保存する。

利用可能な環境

カスタムエージェントを利用可能な環境を以下に示す。

GitHub.com
エージェントタブ、チャットパネル、issue割り当て、プルリクエスト
GitHub Copilot CLI
--agentフラグで呼び出し
VS Code
バージョン1.106以降
JetBrains IDE
IntelliJ IDEA、PyCharm、WebStorm等
Eclipse
Eclipse IDE
Xcode
Xcode IDE

利用方法を以下に示す。

明示的な呼び出し
@agent-name でエージェントを指定する。
コンテキストに基づく自動使用
infer: true の場合、コンテキストに応じて自動的に使用される。

具体的な設定例

カスタムエージェントの具体的な設定例を以下に示す。

README専門エージェント

README.mdファイルと関連ドキュメントの作成・改善に特化したエージェントの設定例を以下に示す。

 ---
 name: readme-specialist
 description: README.mdファイルと関連ドキュメントの作成・改善に特化したエージェント
 tools:
   - read
   - search
   - edit
 ---
 
 このエージェントはドキュメント作成に限定されます。あなたの責任は以下です:
 
 * README.mdおよび関連ドキュメント (docs/CONTRIBUTING.md等) の作成・改善
 * ドキュメント内の相対リンク (docs/CONTRIBUTING.md など) の使用
 * GitHubの自動目次機能に対応した見出しの階層化
 
 以下の作業は禁止です:
 
 * ソースコードファイルの修正
 * API自動生成ドキュメント変更

主要な特徴を以下に示す。

ツール制限
read、search、editのみ使用可能
スコープの明確化
ドキュメント作成のみに専念
禁止事項の明記
ソースコード変更を禁止

セキュリティレビューエージェント

セキュリティ脆弱性検出と修復アドバイスを提供するエージェントの設定例を以下に示す。

 ---
 name: security-reviewer
 description: セキュリティ脆弱性検出と修復アドバイスを提供するエージェント
 tools:
   - read
   - search
 mcp-servers:
   - name: jfrog-security
     url: https://mcp.jfrog.com/security
     env:
       JFROG_API_KEY: ${{ secrets.JFROG_SECURITY_API_KEY }}
 ---
 
 あなたはセキュリティ専門家です。以下の責任を持ちます:
 
 * 脆弱性検出と修復パスの提示
 * セキュアなアップグレードパスの推奨
 * セキュリティベストプラクティスの教育

主要な特徴を以下に示す。

MCPサーバー統合
JFrog Securityサーバーと連携
環境変数参照
GitHub Secretsから認証情報を取得
ツール制限
read、searchのみ使用可能 (編集権限なし)

テスト専門家エージェント

ユニットテストとテストカバレッジの最適化を支援するエージェントの設定例を以下に示す。

 ---
 name: test-expert
 description: ユニットテストとテストカバレッジの最適化を支援するエージェント
 target: vscode
 tools:
   - read
   - edit
   - search
 infer: false
 ---
 
 あなたはテスト駆動開発 (TDD) の専門家です。以下の職務を遂行してください:
 
 * ユニットテストの作成・改善
 * テストカバレッジの分析と向上提案
 * モック・スタブの適切な使用指導

主要な特徴を以下に示す。

対象環境
VS Code専用
明示的呼び出し
infer: false により、明示的な呼び出しのみで動作
ツール制限
read、edit、searchのみ使用可能

推奨設定

カスタムエージェントの記述の推奨設定を以下に示す。

スコープの明確化

エージェントの権限を明確に定義し、特定の領域に専念させる。

良い例を以下に示す。

 あなたはREADME.mdファイルと関連ドキュメントの作成・改善に特化したエージェントです。
 
 以下の作業のみ実行してください:
 
 * README.mdの作成・更新
 * docs/ディレクトリ内のMarkdownファイルの編集
 * ドキュメントリンクの検証
 
 以下の作業は禁止です:
 
 * ソースコードファイルの変更
 * 設定ファイルの変更

悪い例を以下に示す。

 あなたは開発を支援するエージェントです。
 
 ユーザの依頼に応じて、コードの改善やドキュメントの作成を行ってください。

一つの責任

各エージェントは単一の領域に特化させる。

推奨される専門化を以下に示す。

テスト専門
ユニットテスト、統合テスト、テストカバレッジの最適化
セキュリティ専門
脆弱性検出、セキュアコーディング、OWASP Top 10対応
ドキュメント専門
README、API仕様、ガイドの作成
リファクタリング専門
コード品質の向上、パフォーマンス最適化

制限事項の明記

禁止事項と許可事項をプロンプト内に明確に記述する。

記述例を以下に示す。

 ## 許可される操作
 
 * テストファイルの作成 (tests/**/*.test.ts)
 * テストコードの修正
 * モックオブジェクトの作成
 
 ## 禁止される操作
 
 * ソースコードファイルの変更 (src/**/*.ts)
 * テストの削除
 * カバレッジ要件の緩和

役割明確化

エージェントの役割を明確に定義する。

良い例を以下に示す。

 あなたはセキュリティレビュー専門家です。
 
 あなたの職務:
 * OWASP Top 10に基づく脆弱性検出
 * セキュアコーディングのベストプラクティス提案
 * 依存関係の脆弱性スキャン結果の分析

悪い例を以下に示す。

 あなたは便利なアシスタントです。
 
 ユーザの質問に答えてください。

具体的な責任

実行すべき具体的なアクションを列挙する。

記述例を以下に示す。

 ## あなたの責任
 
 1. ユニットテストの作成
    * 各関数に対して正常系・異常系のテストを作成
    * テストカバレッジ80%以上を目標にする
 
 2. テストコードの品質向上
    * AAA (Arrange-Act-Assert) パターンに従う
    * テスト名は実行内容が明確になるように記述
 
 3. モックとスタブの適切な使用
    * 外部依存をモック化
    * テストの独立性を保証

相対リンク

ドキュメント参照時は相対リンクを推奨する。

良い例を以下に示す。

 関連ドキュメント:
 * [コーディング規約](docs/CODING_STYLE.md)
 * [テストガイド](docs/TESTING.md)
 * [貢献ガイド](docs/CONTRIBUTING.md)

悪い例を以下に示す。

 関連ドキュメント:
 * [コーディング規約](https://github.com/org/repo/blob/main/docs/CODING_STYLE.md)
 * [テストガイド](https://github.com/org/repo/blob/main/docs/TESTING.md)

避けるべきパターン

カスタムエージェントの記述で避けるべきパターンを以下に示す。

ツール制限なし

セキュリティリスク軽減のため、不要なツールは制限すべきである。

良い例を以下に示す。

 ---
 tools:
   - read
   - search
 description: 読み取りと検索のみ可能なセキュリティレビューエージェント
 ---

悪い例を以下に示す。

 ---
 description: セキュリティレビューエージェント (全ツールにアクセス可能)
 ---

曖昧なプロンプト

抽象的な指示を避け、具体的なアクションを記述すべきである。

良い例を以下に示す。

 ## あなたの職務
 
 1. README.mdファイルを作成する際は、以下のセクションを含める:
    * プロジェクト概要
    * インストール手順
    * 使用方法
    * ライセンス
 
 2. ドキュメント内のリンクは相対パスを使用する
    * 良い例: [ガイド](docs/GUIDE.md)
    * 悪い例: [ガイド](https://github.com/org/repo/blob/main/docs/GUIDE.md)

悪い例を以下に示す。

 ## あなたの職務
 
 * ドキュメントを改善してください
 * ユーザーにとって分かりやすい内容にしてください

スコープクリープ

複数の領域を一つのエージェントに詰め込むことは避けるべきである。

良い例 (単一責任):

 ---
 name: test-expert
 description: ユニットテストとテストカバレッジの最適化を支援するエージェント
 ---
 
 あなたはテスト専門家です。テストコードの作成と改善のみを行ってください。

悪い例 (複数責任):

 ---
 name: full-stack-agent
 description: テスト、セキュリティ、ドキュメント、リファクタリングを支援するエージェント
 ---
 
 あなたは万能エージェントです。あらゆる開発作業を支援してください。

過度の制限

ツール数が0に近い場合、エージェントの有用性が低下する。

良い例を以下に示す。

 ---
 tools:
   - read
   - edit
   - search
 description: ドキュメント作成に必要な最小限のツールセット
 ---

悪い例を以下に示す。

 ---
 tools: []
 description: ツールを使用しないエージェント (実質的に機能しない)
 ---

GitHub Copilotの設定 - サブエージェント

概要

他の設定ファイルとの違い

設定ファイルの比較

ファイル配置場所と優先順位

配置レベル

ディレクトリ構成例

ファイル形式

ファイル名規則

ファイル構成

YAMLフロントマターのプロパティ

プロパティ一覧

主要プロパティの詳細

name

description

target

tools

infer

model

MCP設定

基本設定

環境変数参照形式

作成方法

GitHub.comから作成

VS Codeから作成

JetBrains IDEから作成

利用可能な環境

具体的な設定例

README専門エージェント

セキュリティレビューエージェント

テスト専門家エージェント

推奨設定

スコープの明確化

一つの責任

制限事項の明記

役割明確化

具体的な責任

相対リンク

避けるべきパターン

ツール制限なし

曖昧なプロンプト

スコープクリープ

過度の制限

関連項目