MCP on hagizo.io

【AI開発】GitHub Copilot Custom Agentsの作り方

Wed, 22 Apr 2026 01:43:00 +0900

GitHub Copilotを「自分用の開発エージェント」として使うなら、custom agentsはかなり重要な機能です。毎回プロンプトで細かい前提を説明するのではなく、役割、制約、利用できるツール、判断基準をMarkdownファイルとして定義しておくことで、Copilotをタスク特化のチームメイトとして扱いやすくなります。

Custom Agentsとは何か

GitHub Docsでは、custom agentsはワークフロー、コーディング規約、ユースケースに合わせて調整できるCopilot agentの特殊版として説明されています。About custom agents つまり、Copilot本体に「このタスクではセキュリティレビュアとして振る舞う」「このタスクではREADME作成者として振る舞う」といった専門性を持たせる仕組みです。

custom agentは、agent profileと呼ばれるMarkdownファイルで定義します。About custom agents このagent profileには、YAML frontmatterで名前、説明、利用ツール、MCPサーバなどを書き、本文にエージェントの振る舞いを自然言語で記述します。Custom agents configuration

通常のcustom instructionsが「リポジトリ全体の常時ルール」だとすると、custom agentsは「特定の役割を持つ担当者」です。たとえば、docs-writer、test-specialist、security-auditor、ci-debugger のように分けておくと、1つの万能エージェントにすべてを背負わせずに済みます。

どこに配置するか

リポジトリ単位で使うcustom agentは、.github/agents/ に配置します。Creating custom agents ファイル拡張子は .agent.md で、たとえば .github/agents/security-auditor.agent.md のように作ります。Creating custom agents for Copilot CLI

個人用に複数リポジトリで使いたい場合は、Copilot CLIでは ~/.copilot/agents/ に配置できます。Creating custom agents for Copilot CLI 同じ名前のエージェントがプロジェクト側とユーザー側にある場合、CLIではホームディレクトリ側のcustom agentが優先されます。Creating custom agents for Copilot CLI

OrganizationやEnterpriseで共通利用したい場合は、.github-private リポジトリの /agents/ に配置できます。About custom agents 個人の作業ルールならユーザー側、プロジェクト固有の規約ならリポジトリ側、組織標準ならOrganization側、という切り分けがよさそうです。

最小のagent profile

最小構成は、description と本文のプロンプトです。description は必須フィールドで、custom agentの目的と能力を説明します。Custom agents configuration

---
name: docs-writer
description: README、ADR、リリースノート、開発者向けドキュメントを作成・改善するドキュメント専門エージェント
tools: ["read", "edit", "search"]
---

あなたはドキュメント作成の専門家です。

あなたの責務:
- README、ADR、リリースノート、開発者向けドキュメントを改善する
- 簡潔で読みやすいMarkdownを書く
- 既存の用語、文体、プロジェクトの慣習を尊重する
- 明示的に依頼されない限り、本番コードは変更しない

編集前に行うこと:
- 既存ドキュメントの文体と構成を確認する
- 読者が誰かを明確にする
- 依頼が曖昧な場合は、先にアウトラインを提案する

編集後に行うこと:
- 何を変更したかを要約する
- 前提にしたことや不足している情報を列挙する

tools を省略すると、利用可能なすべてのツールが有効になります。Custom agents configuration 安全に始めるなら、read、search、edit のように必要なツールだけを明示するのがおすすめです。Custom agents configuration

toolsで権限を絞る

custom agentの実用性は、プロンプトだけでなくtoolsの制御で決まります。GitHub Docsでは、tools に read、edit、search、execute、agent などのエイリアスを指定できると説明されています。Custom agents configuration

たとえば、レビュー専用エージェントなら編集権限を持たせないほうが安全です。

---
name: read-only-reviewer
description: ファイルを編集せず、コードやドキュメントを読み取り専用でレビューするエージェント
tools: ["read", "search"]
---

あなたは読み取り専用のレビュー担当です。

あなたの責務:
- 依頼されたファイルをレビューする
- リスク、不整合、テスト不足、説明不足を見つける
- 具体的な修正案を提示する
- ファイルは編集しない

出力形式:
- 概要
- 指摘事項
- 修正案
- 確信度

このように tools: ["read", "search"] にしておけば、レビュー担当が勝手にファイル編集するリスクを下げられます。逆に、CI修正担当なら execute を含めることでテストやlintを実行できるようにします。

MCPをagent専用にする

custom agentには mcp-servers を設定できます。Custom agents configuration ただし、mcp-servers プロパティはGitHub.com上のCopilot cloud agent向けで、VS CodeなどのIDE custom agentsでは使われないとされています。Custom agents configuration

MCPツールは、server-name/tool-name のようにサーバ名付きで指定できます。Custom agents configuration たとえばPlaywright系の検証エージェントなら、Playwrightのツールだけを許可する設計が考えられます。

---
name: ui-regression-tester
description: Playwrightを使って画面挙動やUI回帰を検証するテスト専門エージェント
tools: ["read", "search", "edit", "execute", "playwright/*"]
---

あなたはUI回帰テストの専門家です。

あなたの責務:
- 既存のUIテストパターンを確認する
- 変更された挙動に対して、焦点を絞ったPlaywrightテストを追加する
- 利用可能な場合は、関連するテストコマンドを実行する
- 失敗した場合は、再現手順と原因候補を整理する

制約:
- 関係のないUIコードはリファクタリングしない
- 小さく、目的が明確なテストを優先する
- テスト環境が利用できない場合は、不足しているセットアップを明確に説明する

ツールを絞ると、エージェントの役割と権限境界が明確になります。これは前回整理した「安全性ガード」レイヤを、Copilot custom agentの設定として実装するイメージです。

targetとmodelを使い分ける

target を使うと、custom agentの対象環境を vscode または github-copilot に限定できます。Custom agents configuration 省略した場合は両方の環境が対象になります。Custom agents configuration

model を指定すると、そのcustom agentが実行されるときのモデルを指定できます。Custom agents configuration ただし、モデル指定は環境や利用可能なモデルに依存するので、最初は省略してデフォルトモデルを使い、必要になってから調整するほうが運用しやすいです。

---
name: implementation-planner
description: コードを変更する前に、実装計画と技術仕様を作成する計画専門エージェント
target: github-copilot
tools: ["read", "search", "edit"]
---

あなたは実装計画の専門家です。

あなたの仕事は、実装前に計画を作ることです。

必ず含める内容:
- ゴール
- 対象範囲
- 対象外とすること
- 影響を受けるファイルまたはモジュール
- ステップごとの実装計画
- テスト計画
- リスクとロールバック方針

ユーザーが明示的に実装を依頼しない限り、コードは変更しないでください。

計画専用エージェントは、実装前のレビューやIssue整理と相性がよいです。ユーザーが明示的に実装を依頼しない限り、コードは変更しないでください のように明示しておくと、ResearchやPlanの段階で勝手に変更が進むのを防ぎやすくなります。

自動選択させるか、手動選択にするか

Copilot CLIでは、/agent でcustom agentを選択できます。Creating custom agents for Copilot CLI また、プロンプト内で特定のagent名を指定したり、copilot --agent security-auditor --prompt "..." のようにコマンドライン引数で指定したりできます。Creating custom agents for Copilot CLI

自動で使わせたくない場合は、disable-model-invocation: true を設定すると、Copilot cloud agentがタスク文脈から自動利用することを無効にできます。Custom agents configuration 逆に、ユーザーが手動選択できないagentにしたい場合は、user-invocable: false を使えます。Custom agents configuration

---
name: dangerous-change-reviewer
description: 本番環境やインフラに影響する危険な変更を、読み取り専用で確認するレビュー専門エージェント
tools: ["read", "search"]
disable-model-invocation: true
---

あなたは本番影響のある変更を確認するレビュー担当です。

このエージェントは、明示的に選択された場合だけ使用してください。

確認すること:
- 本番環境への影響
- ロールバック方針
- シークレットの露出
- 権限変更
- データ削除またはデータ移行のリスク
- 人間の承認が必要な箇所

ファイルは絶対に編集しないでください。

本番、権限、削除、課金に関係する領域では、自動起動よりも手動選択のほうが安全です。

CLIで作る流れ

Copilot CLIでは、interactive modeで /agent を入力し、Create new agent を選ぶことでcustom agentを作成できます。Creating custom agents for Copilot CLI 作成場所はProjectの .github/agents/ か、Userの ~/.copilot/agents/ から選べます。Creating custom agents for Copilot CLI

CLIでは、Copilotにagent profileの初期案を生成させる方法と、自分で手動作成する方法があります。Creating custom agents for Copilot CLI 手動作成では、名前、説明、振る舞い、制約、利用ツールを順番に定義します。Creating custom agents for Copilot CLI

作成後はCLIの再起動が必要です。Creating custom agents for Copilot CLI 使うときは /agent で選択するか、プロンプトで security-auditorエージェントを使って、この差分をレビューして のように明示します。Creating custom agents for Copilot CLI

作るときの注意点

custom agentは、万能化しすぎないほうがよいです。GitHub Docsでも、custom agentsは特定のワークフロー、規約、ユースケースに合わせるものとして説明されています。About custom agents 役割が広すぎると、通常のCopilot Chatと差がなくなります。

また、description はかなり重要です。custom agentの目的と能力を説明する必須項目であり、Copilotがいつそのagentを使うべきか判断する手がかりになります。Custom agents configuration

最後に、toolsは最小権限で始めるのがおすすめです。tools を省略するとすべての利用可能ツールが有効になるため、レビュー専用、計画専用、ドキュメント専用のagentでは、必要なツールだけに絞ったほうが安全です。Custom agents configuration

まとめ

Copilot custom agentsは、特別なAI基盤を作る機能ではなく、Copilotに「役割」「判断基準」「使えるツール」「禁止事項」を渡すためのファイルベースの仕組みです。まずは .github/agents/docs-writer.agent.md のような小さなagentから始め、効果が見えたら test-specialist、ci-debugger、security-auditor のように分割していくのが現実的です。

重要なのは、エージェントを増やすことではなく、責務と権限境界を明確にすることです。custom agentsをうまく使うと、Copilotは単なる補完ツールではなく、リポジトリの文脈とチームの作法を理解した専門家チームに近づきます。

【AI開発】GitHub Copilotで自分用エージェントを作る考え方

Wed, 22 Apr 2026 01:32:00 +0900

前回は、エージェントAIの設計パターンを「ゴールと計画」「推論と自己改善」「協調」「安全性ガード」の4レイヤで整理しました。今回はその考え方を、GitHub Copilotで実際に使える形へ落とし込みます。ポイントは、Copilotを単なる補完ツールではなく、指示、ツール、権限、検証手順を与えた「開発ワークフロー用エージェント」として設計することです。

Copilotで作れるエージェントの種類

まず、Copilotには大きく2つの使い方があります。VS CodeなどのIDEで使うagent modeと、GitHub上で動くCopilot cloud agentです。GitHub Docsでは、cloud agentはリポジトリを調査し、実装計画を作り、ブランチ上で変更し、必要に応じてPull Requestを作れると説明されています。About GitHub Copilot cloud agent

一方、VS Codeのagent modeはローカル開発環境の中で動く自律的なペアプログラマです。VS Codeのブログでは、agent modeはコードベースを分析し、ファイル編集を提案し、ターミナルコマンドを実行し、コンパイルやlintエラーを見て修正ループを回せると説明されています。VS Code Agent mode

ざっくり分けると、ローカルで一緒に試行錯誤するならIDEのagent mode、IssueやPR単位で非同期に任せるならcloud agentが向いています。

1. ゴール定義はプロンプトとinstructionsで作る

エージェント設計の最初の層は、曖昧な依頼を実行可能なタスクへ変換することです。Copilotでは、ここをプロンプトとcustom instructionsで作ります。

リポジトリ全体の前提は .github/copilot-instructions.md に書けます。GitHub Docsでは、リポジトリ全体のcustom instructionsとしてこのファイルを作り、プロジェクト構造、ビルド方法、テスト方法、コーディング規約などをMarkdownで記述できると説明されています。Adding repository custom instructions

たとえばDevOps系リポジトリなら、次のような情報を入れておきます。

# Repository instructions

- 変更前に対象サービス、環境、影響範囲を確認する
- CI/CD関連の変更では `.github/workflows/` と `scripts/` を必ず確認する
- 破壊的操作や本番反映は実行せず、計画と差分だけ提示する
- 変更後は `make test` と `make lint` を実行する

これは、前回の記事でいうPassive Goal CreatorとGuardrailsを、Copilot向けの常時コンテキストとして実装しているイメージです。

2. パス別instructionsで役割を分ける

リポジトリ全体の指示だけだと、フロントエンド、バックエンド、インフラ、ドキュメントでルールが混ざります。そこで .github/instructions/*.instructions.md を使います。GitHub Docsでは、applyTo frontmatterで対象パスを指定するpath-specific custom instructionsを作れると説明されています。Adding repository custom instructions

たとえばHugoブログなら、記事用のinstructionsを次のように分けられます。

---
applyTo: "content/posts/**/*.md"
---

# Blog post rules

- frontmatterには title, slug, draft, date, tags, categories, description を含める
- 本文では h1 を使わず、h2/h3 で構成する
- 外部情報を使った場合はMarkdownリンクで出典を残す
- draft は明示がなければ false にする

これにより、Copilotは「記事編集時のエージェント」と「コード編集時のエージェント」で振る舞いを変えやすくなります。

3. custom agentsで専門エージェント化する

さらに踏み込むなら、custom agentsを使います。GitHubのcustomization cheat sheetでは、custom agentsは独自のinstructions、tool restrictions、contextを持つ専門ペルソナで、.github/agents/AGENT-NAME.md などに置けると整理されています。Copilot customization cheat sheet

たとえば、次のようなエージェントを用意できます。

docs-writer: README、ADR、ブログ記事、リリースノートを書く
test-generator: 既存コードを読んでユニットテストを追加する
ci-debugger: GitHub Actionsの失敗ログを読み、再現手順と修正案を出す
security-reviewer: 依存関係、権限、シークレット混入を確認する

これは、前回の4レイヤでいう「協調」レイヤです。最初から巨大な万能エージェントを作るより、役割ごとに分けるほうがレビューしやすくなります。

4. MCPでツールを増やす

Copilotを本当のエージェントらしくするには、外部ツールへのアクセスが重要です。GitHub Docsでは、MCPを使うとCopilot agent modeが外部データソース、API、ツールへアクセスでき、調査、計画、実装、検証のループを回しやすくなると説明されています。Enhancing GitHub Copilot agent mode with MCP

開発者向けには、まず次のようなMCPサーバから始めるのが現実的です。

GitHub MCP: Issue、PR、ブランチ、Actionsの情報を見る
Playwright MCP: UIを操作してE2Eやアクセシビリティを確認する
Figma MCP: デザイン仕様を読み、実装との差分を確認する
独自MCP: 社内API、ログ、メトリクス、デプロイ情報を読む

MCPを足すときは、いきなり全部つなげないほうが安全です。公式ドキュメントでも、目的に合うサーバを選び、シンプルに始め、接続確認をしてからagent modeのタスクに使うことが推奨されています。Enhancing GitHub Copilot agent mode with MCP

5. 変更前にフェーズを分ける

Copilotにいきなり「全部直して」と頼むと、どの設計判断が正しかったのか追いづらくなります。おすすめは、Research、Plan、Implement、Validateの4フェーズに分けることです。

1. Research: まず関連ファイル、Issue、CIログを調べて、原因候補を列挙して。まだ変更しない。
2. Plan: 修正方針を2案出し、リスク、影響範囲、検証方法を比較して。
3. Implement: 採用した方針で最小差分を実装して。関係ない整形はしない。
4. Validate: テスト、lint、手動確認項目を実行し、結果をまとめて。

これはPlan & Execute、Prompt Chaining、Evaluator-OptimizerをCopilot上で手動フェーズ化したものです。特に本番系やCI/CD系の変更では、「まだ変更しない」「PRを作る前に計画だけ出す」「破壊的操作はしない」と明示するだけで事故を減らせます。

最小構成のおすすめ

まず作るなら、次の3点で十分です。

1つ目は .github/copilot-instructions.md です。リポジトリ概要、セットアップ、テスト、禁止事項、レビュー観点を書きます。

2つ目は .github/instructions/ です。frontend.instructions.md、backend.instructions.md、docs.instructions.md のように、パスごとのルールを分けます。

3つ目はMCPを1つだけ足すことです。GitHub連携かPlaywright連携のように、普段の開発で効果が見えやすいものから始めます。

この構成なら、単一エージェントでも「ゴール定義」「推論と実行」「安全性ガード」までかなり表現できます。必要になったタイミングで、custom agentsやagent skillsを追加し、docs-writer、ci-debugger、security-reviewerのような専門エージェントへ分割すればよいです。

Copilotでエージェントを作るとは、特別なAI基盤を最初から作ることではありません。自分の開発プロセスを、instructions、prompt、agent、MCP、承認フローとして明文化することです。設計パターンを意識してCopilotに渡す文脈を整えるほど、単なる補完ツールから、頼れる開発パートナーに近づいていきます。