19
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

新人プログラマ応援 - みんなで新人を育てよう！
@chomado(Madoka Chiyoda)inMicrosoft

GitHub Copilot CLI の公式ハンズオンざっくり和訳 (第4章/7章) カスタムエージェント編

19
Posted at

公式チュートリアル「GitHub Copilot CLI for Beginners」ハンズオンリポジトリを進めていきます！

このチュートリアルは (2026 年 4 月現在) 7 章までありますが、
今回は、第 4 章（特化型 (Specialized) AI アシスタントの作成）をざっくり和訳しながら進めていこうと思います。

この第 4 章は、一言で言うと「Copilotを "汎用 AI" から "専門家チーム" に進化させる」方法を学びます。

例：

  • python-reviewer → コード品質専門家
  • pytest-helper → テスト専門家
  • security-reviewer → セキュリティ専門家

前回までの記事

第 0 章 環境構築編

第 1 章 操作モードの説明

第 2 章 基本用語やコンテキストについてなどの説明

第 3 章 開発ワークフローへの組み込み方

🗺️ ハンズオンの全体像

2026/04/08 現在、第 0 章から第 7 章まであります。
今回はこの第 4 章を進めていきましょう。

章 タイトル 学べる内容
0 🚀 クイックスタート インストールと動作確認
1 👋 最初の一歩 ライブデモ + 3 つの操作モード
2 🔍 コンテキストと会話 複数ファイルのプロジェクト分析
3 ⚡ 開発ワークフロー コードレビュー、デバッグ、テスト生成
4 [ 今ここ！→ ] 🤖 特化型 (Specialized) AI アシスタントの作成 ワークフロー用のカスタム AI エージェント
5 🛠️ 繰り返し作業の自動化 自動で読み込まれるスキルの作成
6 🔌 GitHub・データベース・API との接続 MCP サーバとの連携
7 🎯 すべてを組み合わせる すべてを組み合わせた実践的ワークフロー

🗺️ 全体構造（ざっくりマップ）

第 4 章は大きく 5 ブロックに分かれています：

  1. Agents とは何か（概念）
  2. Built-in Agents（組み込みのエージェント）
  3. Custom Agents（自作エージェント）
  4. Advanced（複数エージェント・設計・共有）
  5. Instruction Files（常時適用ルール）

1. エージェントとは

これまでは Copilot CLI を汎用的なアシスタントとして使ってきました。
しかし、エージェントを使うことで、「特定の役割（ペルソナ）」を持たせることができます。

例えば：

このように、あらかじめルールを持ったエージェントに処理させることで、
同じプロンプトでも、より質の高い結果が得られることを体感できます。

1-1. 現実世界での例え：専門家を雇う

家の修理を頼むとき、「何でも屋」には頼みません。
それぞれの専門家を呼びます：

問題 専門家 理由
水漏れ 配管工 配管の規格を理解し、専用の道具を持っている
配線のやり直し 電気工事士 安全基準を理解し、規格に準拠している
屋根の修理 屋根職人 材料や地域の気候条件を理解している

エージェントもこれと同じです。

汎用的なAIを使うのではなく、
特定のタスクに特化し、適切なプロセスを理解したエージェントを使うのです。

一度指示（ルール）を設定すれば、
コードレビュー、テスト、セキュリティ、ドキュメント作成など、
必要なときにその専門性を繰り返し利用できます。

(毎回「型チェックもお願いね」などと指示しなくて良い、など)

image.png

2. 組み込みエージェント（Built-in Agents）

第3章の開発ワークフローで、すでにいくつかの組み込みエージェントを使っています！

/plan や /review は、実は組み込みエージェントです。
これで、内部で何が起きているのかが分かりましたね。

2-1. 組み込みエージェント例

エージェント 呼び出し方法 役割
Plan /plan または Shift+Tab（モード切替） コーディング前にステップごとの実装計画を作成
Code-review /review ステージ済み／未ステージの変更をレビューし、具体的で実用的なフィードバックを提供
Init /init プロジェクト設定ファイル（命令・エージェント）を生成
Explore 自動 コードベースの探索・解析を依頼したときに内部的に使用
Task 自動 テスト実行、ビルド、lint、依存関係のインストールなどを実行

2-2. 組み込みエージェントの動作例

copilot

# Planエージェントを使って実装計画を作成
> /plan Add input validation for book year in the book app

# Code-reviewエージェントで変更をレビュー
> /review

# ExploreとTaskは必要に応じて自動的に使われる
> Run the test suite        # Taskエージェントが使用される

> Explore how book data is loaded    # Exploreエージェントが使用される

2-3. Task エージェントについて

Task エージェントはバックグラウンドで動作し、
処理の管理・進捗追跡・結果の報告を行います。

その出力は、分かりやすく整理されています：

結果 表示内容
✅ 成功 簡潔なサマリー（例：「247件のテストがすべて成功」「ビルド成功」）
❌ 失敗 スタックトレース、コンパイルエラー、詳細ログなどの完全な出力

2-4. 補足（重要ポイント）

/plan や /review のコマンドは、
内部的には「専門エージェントの呼び出し」だったということですね。

つまり：

  • /plan = 設計担当AI
  • /review = レビュー担当AI
  • Task = 実行担当AI

Copilot CLI はすでに「役割分担されたAIシステム」になっているということです

3. Copilot CLI にエージェントを追加する (Custom Agents)

独自のエージェントを定義して、あなたの開発ワークフローに組み込むことができます。
一度定義すれば、あとは必要なときに呼び出すだけです。

3-1. エージェントの追加方法

エージェントファイルは .agent.md という拡張子を持つ Markdown ファイルです。

構成は次の 2 つに分かれます：

  1. YAML フロントマター（メタデータ）
  2. Markdown 形式の指示内容

💡 YAMLフロントマターが初めての方へ

ファイルの先頭の --- で囲まれた設定ブロックです。
YAML は単純な key: value の形式で記述します。
それ以降は通常の Markdown として書きます。

フロントマター例
---
name: pytest-helper
description: Testing specialist for Python projects using pytest
tools: ["read", "edit", "search", "execute"]
---

3-2. 最小構成のエージェント例

コードレビュアーエージェントの my-reviewer.agent.md
---
name: my-reviewer
description: バグやセキュリティ問題に特化したコードレビュアー
---

# Code Reviewer

あなたは、バグやセキュリティ問題の検出に特化したコードレビュアーです。

コードレビュー時には、必ず以下を確認してください：

- SQLインジェクションの脆弱性
- エラーハンドリングの不足
- ハードコードされたシークレット情報

必須項目と任意項目について

description は必須です。
name、tools、model などは任意で設定できます。

何が便利なの？

「プロンプトを毎回書く」のではなく
「AI の振る舞いを定義して固定する」ことができるので便利

つまり：

  • 毎回「セキュリティも見て」と言わなくていい
  • 常に同じ観点でレビューされる

など

3-3. .agent.md ファイルの置き場所

配置場所 スコープ 用途
.github/agents/ プロジェクト単位 チームで共有するエージェント（プロジェクト固有のルール）
~/.copilot/agents/ グローバル（全プロジェクト） 個人用エージェント（どこでも使うもの）

このプロジェクトには、 .github/agents/ フォルダ内にサンプルのエージェントファイルが含まれています。

それらをそのまま使うこともできますし、自分用にカスタマイズすることも可能です。

3-4. エージェントファイルのサンプル

このコースで提供されているサンプルエージェント

ファイル 説明
hello-world.agent.md 最小構成のサンプル（まずはここから）
python-reviewer.agent.md Python コード品質レビュー用
pytest-helper.agent.md pytest テスト作成の専門エージェント

他サンプル

エージェントファイルの良質なサンプルについては、
こちらのコミュニティ製のサンプル集「awesome-copilot」リポジトリがおすすめです！

3-5. カスタムエージェントの使い方（2通り）

3-5-1. ① インタラクティブモード

インタラクティブモード内では、/agent コマンドで利用可能なエージェント一覧を表示し、
使用したいエージェントを選択できます。

選択したエージェントは、その後の会話に適用されます。

copilot
> /agent

image.png

エージェントを変更したい場合や、デフォルト状態に戻したい場合も、
再度 /agent を実行します。

3-5-2. ② プログラム実行モード（Programmatic mode）

--agent で、最初から特定のエージェントを指定してセッションを開始することもできます。

copilot --agent python-reviewer
> Review @samples/book-app-project/books.py

💡 エージェントの切り替えについて

/agent または --agent を使えば、いつでも別のエージェントに切り替え可能です。
標準の Copilot CLI に戻る場合は、/agent を実行して「Default」を選択してください。

4. エージェントをさらに深く理解する（Going Deeper with Agents）

💡 このセクションは任意です

組み込みエージェント（/plan、/review）だけでも、ほとんどのワークフローには十分対応できます。
カスタムエージェントは、特定の専門性を一貫して適用したい場合に作成しましょう。

以下の各トピックはそれぞれ独立しています。
興味のあるものから選んで読めばOKで、すべてを一度に読む必要はありません。

やりたいこと 該当セクション
エージェントがなぜ通常のプロンプトより優れているか知りたい 4-1. Specialist vs Generic
複数のエージェントを組み合わせて使いたい 4-2. Working with Multiple Agents
エージェントの整理・命名・共有方法を知りたい 4-3. Organizing & Sharing Agents
常に適用されるプロジェクト設定を作りたい 4-4. Configuring Your Project for Copilot
YAML設定やツールの詳細を確認したい 4-5. Agent File Reference

4-1. Specialist vs Generic：違いを見てみよう

ここがエージェントの真価が発揮されるポイントです。
違いを見てください。

4-1-1. エージェントなし（通常のCopilot）

copilot

> 書籍アプリで、出版年の範囲で本を検索する関数を追加して
# (原文：Add a function to search books by year range in the book app)

出力

デフォルト版
def search_by_year_range(books, start_year, end_year):
    results = []
    for book in books:
        if book['year'] >= start_year and book['year'] <= end_year:
            results.append(book)
    return results

シンプルで動くコードではあるが、足りない部分も多い

4-1-2. Python Reviewerエージェントを使った場合

copilot

> /agent
# "python-reviewer" を選択

> 書籍アプリで、出版年の範囲で本を検索する関数を追加して

出力

python-reviewerエージェント版
from typing import List, Dict, Any

def search_by_year_range(
    books: List[Dict[str, Any]],
    start_year: int,
    end_year: int
) -> List[Dict[str, Any]]:
    """
    指定した年の範囲で本を検索する。

    Args:
        books: 本の辞書リスト
        start_year: 開始年（含む）
        end_year: 終了年（含む）

    Returns:
        指定範囲内に出版された本のリスト

    Raises:
        ValueError: start_year が end_year より大きい場合
        TypeError: 年の値が整数でない場合
    """
    if not isinstance(start_year, int) or not isinstance(end_year, int):
        raise TypeError("Year values must be integers")

    if start_year > end_year:
        raise ValueError(f"Start year ({start_year}) cannot be greater than end year ({end_year})")

    return [
        book for book in books
        if isinstance(book.get('year'), int)
        and start_year <= book['year'] <= end_year
    ]

python-reviewerエージェント が自動でやってくれること

  • ✅ すべての引数と戻り値に型ヒントを付与
  • ✅ Args / Returns / Raises を含む詳細なdocstring
  • ✅ 入力検証と適切なエラーハンドリング
  • ✅ リスト内包表記によるパフォーマンス改善
  • ✅ エッジケース対応（yearが欠損・不正な場合）
  • ✅ PEP 8準拠のフォーマット
  • ✅ 防御的プログラミング（defensive programming）

4-1-3. つまり

同じプロンプトでも、出力品質が劇的に変わります。

なぜかというと：

  • Generic：何も前提がない（毎回ゼロから）
  • Agent：専門知識が常に前提として埋め込まれている

4-2. 複数エージェントの活用（Working with Multiple Agents）

エージェントの真の力は、
複数の専門家を組み合わせて使うときに発揮されます。

4-2-1. 例：シンプルな機能を作る

copilot

> 書籍アプリに「出版年の範囲で検索する機能」を追加したい

# python-reviewerで設計を考える
> /agent
# 「python-reviewer」を選択

> @samples/book-app-project/books.py
> find_by_year_range メソッドを設計して。最適なアプローチは？

# pytest-helperに切り替えてテスト設計
> /agent
# 「pytest-helper」を選択

> @samples/book-app-project/tests/test_books.py
> find_by_year_range メソッドのテストケースを設計して。
> どんなエッジケースを考慮すべき？

# 両方を統合
> メソッド実装と包括的なテストを含む実装計画を作って

4-2-2. Agent as Tools（エージェントをツールとして使う）

エージェントを設定しておくと、
Copilotはそれらをツールとして自動的に呼び出すこともできます。

例えば、フルスタック機能を依頼すると、Copilot は適切なエージェントに自動で処理を振り分けてくれます。

4-3. エージェントの整理と共有 (Organizing & Sharing Agents)

4-3-1. エージェントの命名

エージェントファイルを作成する際、名前は非常に重要です。
これは /agent や --agent の後に入力する名前であり、
チームメンバーにも一覧として表示されます。

✅ 良い名前 ❌ 避けるべき名前
frontend my-agent
backend-api agent1
security-reviewer helper
react-specialist code
python-backend assistant

命名ルール

  • 小文字＋ハイフン区切り：my-agent-name.agent.md
  • ドメインを含める：frontend, backend, devops, security
  • 必要に応じて具体的に：
    • react-typescript（✅ 具体的）
    • frontend（❌ 曖昧）

4-3-2. チームでの共有

エージェントファイルを .github/agents/ に配置すると、
Git管理され、リポジトリにpushすることで
チーム全員が自動的に利用可能になります。

また、Copilot はエージェントファイルの他にも Instructionファイル（命令ファイル） をサポートしています。

これは /agent を実行しなくても
すべてのセッションに自動適用されるルールです。

4-3-3. ファイルの配置場所

エージェントの配置場所はすでに学びましたが、
以下の判断基準で選びます：

判断フロー

  1. 試しに使う → 現在のフォルダ
  2. チームで使う → .github/agents/ (バージョン管理される)
  3. (俺|私) のプロジェクトではどこでも使う → ~/.copilot/agents/ (your personal agents)

image.png

4-3-4. 実践的な進め方

まずはシンプルに：

  1. プロジェクト内に *.agent.md を1つ作る
  2. 使いながら調整する
  3. 良くなったら正式な場所に移動する

4-3-5. Instructionファイルについて

エージェントとは別に、Copilot は
プロジェクト単位の Instruction ファイルを自動で読み込みます。（/agents 不要で常時起動）

詳細は次のセクション「Configuring Your Project for Copilot」で扱います。（AGENTS.md, .instructions.md, /init など）

4-4. Copilot 用のプロジェクト設定 (Configuring Your Project for Copilot)

エージェントは、必要に応じて呼び出す「専門家」です。
一方で、プロジェクト設定ファイルはそれとは異なります。

Copilot はこれらのファイルを毎回のセッションで自動的に読み込み、
プロジェクトの規約・技術スタック・ルールを理解します。

4-4-1. /init によるクイックセットアップ

最も簡単な方法は、Copilot に設定ファイルを生成させることです：

copilot

> /init

Copilot がプロジェクトをスキャンし、
最適な Instruction ファイルを生成します。

その後、自由に編集できます。

4-4-2. Instruction ファイルの種類

ファイル スコープ 備考
AGENTS.md プロジェクトルートまたはサブディレクトリ クロスプラットフォーム標準（Copilot以外のAIでも使用可能）
.github/copilot-instructions.md プロジェクト GitHub Copilot専用
.github/instructions/*.instructions.md プロジェクト トピックごとに分割された細かい指示
CLAUDE.md, GEMINI.md プロジェクトルート 他AIツールとの互換性用

🎯 初心者向けのおすすめ

まずは AGENTS.md を使いましょう。
他の形式は必要になってからで OK です。

4-4-3. AGENTS.md

AGENTS.md は推奨フォーマットです。

  • オープンスタンダード（複数のAIツールで使える）
  • リポジトリのルートに配置
  • Copilot が自動的に読み込む

このプロジェクトの AGENTS.md が実例として参考になります。

サンプルAGENTS.mdの和訳
# AGENTS.md

GitHub Copilot CLI を学ぶための、初心者向けコース。
これはソフトウェアではなく、教育コンテンツです。

## 構成（Structure）

| パス                             | 目的                                                               |
| ------------------------------ | ---------------------------------------------------------------- |
| `00-07/`                       | 各章：例え → 概念 → ハンズオン → 課題 → 次へ                                     |
| `samples/book-app-project/`    | **メインサンプル**：全章で使用するPython製CLI書籍管理アプリ                             |
| `samples/book-app-project-cs/` | 書籍管理アプリのC#版                                                      |
| `samples/book-app-project-js/` | 書籍管理アプリのJavaScript版                                              |
| `samples/book-app-buggy/`      | **意図的にバグを含むコード**（第3章のデバッグ用）                                      |
| `samples/agents/`              | エージェントテンプレート例（python-reviewer、pytest-helper、hello-world）         |
| `samples/skills/`              | スキルテンプレート例（code-checklist、pytest-gen、commit-message、hello-world） |
| `samples/mcp-configs/`         | MCPサーバー設定のサンプル                                                   |
| `samples/buggy-code/`          | **オプション**：セキュリティ学習用のバグ入りコード（JS / Python）                         |
| `samples/src/`                 | **オプション**：旧バージョンのコースに含まれていたJS/Reactサンプル                          |
| `appendices/`                  | 補足資料・リファレンス                                                      |

## やるべきこと（Do）

* 初心者向けに分かりやすく説明する → AI/ML用語は必ず解説する
* bashの例はそのままコピー＆ペーストで実行できるようにする
* トーンは：親しみやすく、励まし、実用的に
* 主要な例では `samples/book-app-project/` を使用する
* コード例は Python / pytest を前提とする

## やってはいけないこと（Don't）

* `samples/book-app-buggy/` や `samples/buggy-code/` のバグを修正しない → これらは意図的に含まれている
* `README.md` のコース一覧を更新せずに章を追加しない
* 読者が AI/ML 用語を理解している前提にしない

## ビルド方法（Build）

> npm install && npm run release

4-4-4. AGENTS.md に書く内容

一般的には以下を記述します：

  • プロジェクトの概要
  • コーディングスタイル
  • セキュリティ要件
  • テスト方針

/init で生成するか、サンプルを参考に自分で書きます。

4-4-5. カスタム Instruction ファイル（.instructions.md）

より細かく管理したい場合は、
トピックごとにファイルを分割します

.github/
└── instructions/
    ├── python-standards.instructions.md
    ├── security-checklist.instructions.md
    └── api-design.instructions.md

💡 補足

Instruction ファイルは言語に依存しません。
この例は Python ですが、TypeScript / Go / Rust などでも同様に使えます。

4-4-6. コミュニティの Instruction ファイル

既存のテンプレートは以下で探せます：

様々な言語、プラットフォーム、フレームワーク向けのサンプルがあります：

  • .NET
  • Angular
  • Azure
  • Python
  • Docker

など多数

4-4-7. Instruction を無効化する

プロジェクト設定を無視したい場合（デバッグ用途など）：

copilot --no-custom-instructions

4-5. Agent ファイル リファレンス

4-5-1. より完全な例 (A More Complete Example)

先ほどは最小構成のエージェントを見ましたが、
ここでは tools プロパティも含めた、より実用的な例です。

~/.copilot/agents/python-reviewer.agent.md を作成します：

python-reviewer.agent.md
---
name: python-reviewer
description: Pythonコード品質レビューの専門家
tools: ["read", "edit", "search", "execute"]
---

# Python Code Reviewer

あなたは、コード品質とベストプラクティスに特化したPythonの専門家です。

**注力領域：**
- コード品質（PEP 8、型ヒント、docstring）
- パフォーマンス最適化（リスト内包表記、ジェネレータ）
- エラーハンドリング（適切な例外処理）
- 保守性（DRY原則、明確な命名）

**コードスタイル要件：**
- Python 3.10以上の機能を使用（dataclass、型ヒント、パターンマッチ）
- PEP 8の命名規則に従う
- ファイル操作ではコンテキストマネージャを使用する
- すべての関数に型ヒントとdocstringを付ける

**コードレビュー時のチェック項目：**
- 関数シグネチャに型ヒントが欠けていないか
- 可変デフォルト引数が使われていないか
- 適切な例外処理（裸のexceptがないか）
- 入力バリデーションが十分か

4-5-2. YAML プロパティ

プロパティ 必須 説明
name 任意 表示名（未指定の場合はファイル名が使用される）
description 必須 エージェントの役割（Copilotが提案する際の判断材料）
tools 任意 使用可能なツール一覧（省略するとすべて使用可能）
target 任意 vscode または github-copilot に限定にする

4-5-3. ツールの指定（Tool Aliases）

tools に指定できる名前：

  • read：ファイルの読み取り
  • edit：ファイルの編集
  • search：ファイル検索（grep / glob）
  • execute：シェルコマンド実行（shell、Bash も可）
  • agent：他のカスタムエージェントを呼び出す

📖 公式ドキュメント : Custom agents configuration

4-5-4. More Agent Templates

💡 初心者向け注意
以下の例はテンプレートです。

  • 技術スタックは自分のプロジェクトに合わせて置き換えてください
  • 重要なのは「構造」であり、技術そのものではありません

このプロジェクトには以下のサンプルが含まれています：

コミュニティ製の良質エージェントはこちら：

5. よくあるミスとトラブルシューティング

5-1. よくあるミス（Common Mistakes）

ミス 何が起きるか 対処方法
エージェントのYAMLに description がない エージェントが読み込まれない／検出されない 必ず description: を含める
エージェントの配置場所が間違っている エージェントが見つからない ~/.copilot/agents/（個人）または .github/agents/（プロジェクト）に配置
.md で保存している（.agent.md でない） エージェントとして認識されない python-reviewer.agent.md のように命名
エージェント定義が長すぎる 30,000文字制限に引っかかる可能性 内容を絞る（詳細はskillsで管理）

5-2. エージェントが見つからない場合

以下の場所にファイルが存在するか確認：

  • ~/.copilot/agents/
  • .github/agents/

利用可能なエージェント一覧を表示：

copilot
> /agent
# 利用可能なエージェント一覧が表示される

5-3. エージェントが指示通りに動かない場合

プロンプトとエージェント定義をより具体的にしましょう。

追加すべき内容：

  • 使用しているフレームワーク／ライブラリ（バージョン含む）
  • チームのコーディング規約
  • コード例（パターン）

5-4. カスタムInstructionが読み込まれない場合

プロジェクトで /init を実行：

copilot
> /init

または、無効化されていないか確認：

# --no-custom-instructions を使っていると無効になる
copilot  # デフォルトではInstructionが読み込まれる

6. まとめ

  1. 組み込みエージェント (Built-in agents)
    /plan と /review は明示的に呼び出す
    Explore と Task は自動で動作する
  2. カスタムエージェント
    .agent.md ファイルで定義される専門家
  3. 良いエージェントの条件
    専門領域が明確
    基準（standards）がある
    出力形式が定義されている
  4. 複数エージェントの連携
    → 専門性を組み合わせて複雑な問題を解決できる
  5. Instructionファイル（.instructions.md）
    → チームのルールをコード化し、自動適用できる
  6. 一貫した出力
    → 明確に定義されたエージェントによって実現される

7. What's Next

第5章で学ぶこと（Skills System）

  • プロンプトから自動的にスキルが発動する仕組み（スラッシュコマンド不要）
  • コミュニティスキルのインストール方法
  • SKILL.md を使ったカスタムスキルの作成
  • エージェント・スキル・MCP の違い
  • それぞれを使い分けるタイミング
19
15
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
19
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?