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 ディレクトリ内

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

優先順位を以下に示す。

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

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

ディレクトリ構成例

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

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からカスタムエージェントを作成する手順を以下に示す。

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

VS Codeから作成

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

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

JetBrains IDEから作成

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

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

利用可能な環境

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

• 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の設定 - カスタム指示

  リポジトリ全体に適用される汎用ガイダンス (.github/copilot-instructions.md)

• GitHub Copilotの設定 - パス固有カスタム指示

  パス固有の指示ファイル (.github/instructions/*.instructions.md)

• GitHub Copilotの設定 - AGENTS.md

  AIコーディングエージェント向けのオープンフォーマット (AGENTS.md)