GitHub Copilot カスタムエージェント実践ガイド：agents.mdで実現するIssue駆動の自動開発ワークフロー
お疲れ様です！IT業界で働くアライグマです！
「GitHub Copilotを使っているけど、もっとプロジェクト固有のタスクを自動化したい」
「Issueを作成したら、自動でコードを生成してくれる仕組みが欲しい」
「チーム全体でAIアシスタントの挙動を統一したい」
こうした要望を持つ開発者の方は多いのではないでしょうか。
2025年10月にGitHubが発表したカスタムエージェント機能は、まさにこれらの課題を解決するための新機能です。
私自身、PjMとしてチームの開発効率化に取り組む中で、この機能を導入してみました。
結果として、定型的なIssue対応の工数が大幅に削減され、エンジニアがより創造的な作業に集中できるようになりました。
本記事では、GitHub Copilotカスタムエージェントの基本概念から、agents.mdファイルの書き方、実際のIssue駆動ワークフローの構築まで、実践的な内容を解説します。
GitHub Copilot カスタムエージェントとは何か
GitHub Copilotカスタムエージェントは、リポジトリ固有のAIアシスタントを定義できる機能です。
従来のGitHub Copilotは汎用的なコード補完が中心でしたが、カスタムエージェントを使うことで、プロジェクト特有のルールや手順に沿った自動化が可能になります。
従来のCopilotとの違い
従来のGitHub Copilotは、コードを書いている最中にリアルタイムで補完候補を提示するものでした。
一方、カスタムエージェントはIssue単位でタスクを受け取り、自律的に作業を進めるという点で大きく異なります。
具体的には、以下のような違いがあります。
- トリガー：従来はコード入力時、カスタムエージェントはIssueへのアサイン時
- スコープ：従来はファイル単位、カスタムエージェントはリポジトリ全体
- カスタマイズ性：従来は限定的、カスタムエージェントは
agents.mdで詳細に定義可能
agents.mdファイルの役割
カスタムエージェントの挙動は、.github/agents/ディレクトリに配置するagents.mdファイルで定義します。
このファイルには、エージェントが従うべきルール、参照すべきドキュメント、実行すべき手順などを自然言語で記述します。
私がPjMとして最初にこの機能を試したとき、「Markdownで書くだけでAIの挙動を制御できる」という手軽さに驚きました。
複雑な設定ファイルやプログラミングは不要で、チームの誰もが内容を理解・編集できる点が大きなメリットです。
AI駆動開発の基礎を学ぶには、AI駆動開発完全入門 ソフトウェア開発を自動化するLLMツールの操り方が参考になります。
LLMツールを活用したソフトウェア開発の全体像を把握できます。
LangGraph実践ガイド：ステートフルAIエージェント開発で実現する複雑ワークフローの設計と運用では、AIエージェントの状態管理について詳しく解説しています。
agents.mdの基本構造と書き方
agents.mdファイルは、カスタムエージェントの「取扱説明書」のようなものです。
ここでは、基本的な構造と効果的な書き方を解説します。
ファイルの配置場所
agents.mdファイルは、リポジトリのルートにある.github/agents/ディレクトリに配置します。
ディレクトリ構造は以下のようになります。
your-repository/
├── .github/
│ └── agents/
│ └── agents.md
├── src/
└── README.md基本的な記述構造
agents.mdの基本構造は、以下の要素で構成されます。
# Agent Name
## Role
このエージェントの役割を説明します。
## Instructions
エージェントが従うべき具体的な指示を記述します。
## Context
参照すべきドキュメントやコードの場所を指定します。
## Constraints
やってはいけないこと、制約事項を明記します。効果的な指示の書き方
私がチームで運用してみて分かったのは、具体的で明確な指示が重要だということです。
曖昧な表現は避け、エージェントが迷わないように書くことがポイントです。
良い例と悪い例を比較してみましょう。
- 悪い例：「コードをきれいに書いてください」
- 良い例：「ESLintのルールに従い、関数は30行以内に収めてください」
また、SOLID CODE 高品質なコードを生み出す実践的開発手法で解説されているような高品質なコードの基準をagents.mdに組み込むことで、エージェントの出力品質を向上させることができます。
AWS Kiro CLI実践ガイド：Amazon Q Developerの新機能でAI駆動開発を加速する実装パターンも、AI駆動開発の参考になります。
以下のグラフは、カスタムエージェント導入による作業時間の削減効果を示しています。
特にテスト作成やドキュメント作成など、定型的な作業で大きな効果が見られます。
Issue駆動ワークフローの構築手順
ここからは、実際にカスタムエージェントを使ったIssue駆動ワークフローを構築する手順を解説します。
ステップ1：agents.mdファイルの作成
まず、.github/agents/ディレクトリを作成し、agents.mdファイルを配置します。
mkdir -p .github/agents
touch .github/agents/agents.md次に、プロジェクトに合わせた内容を記述します。
以下は、バグ修正用エージェントの例です。
# Bug Fix Agent
## Role
このエージェントは、バグ修正のIssueを担当します。
Issueの内容を分析し、原因を特定し、修正コードを提案します。
## Instructions
1. Issueの説明を読み、再現手順を確認する
2. 関連するソースコードを特定する
3. 原因を分析し、修正方針を決定する
4. 修正コードを作成し、テストを追加する
5. プルリクエストを作成する
## Context
- テストは `tests/` ディレクトリに配置する
- コーディング規約は `CONTRIBUTING.md` を参照する
- 既存のテストが通ることを確認する
## Constraints
- 既存の機能を壊さないこと
- 1つのPRで複数のバグを修正しないこと
- セキュリティに関わる変更は人間のレビューを必須とするステップ2：Issueへのエージェントアサイン
agents.mdをリポジトリにプッシュしたら、Issueにエージェントをアサインできるようになります。
Issueの画面で、Assigneesセクションからカスタムエージェントを選択します。
私のチームでは、Issueのラベルに応じて自動でエージェントをアサインするGitHub Actionsも設定しています。
これにより、bugラベルが付いたIssueには自動でバグ修正エージェントがアサインされる仕組みです。
ステップ3：エージェントの動作確認
エージェントがアサインされると、自動的に作業が開始されます。
進捗はIssueのコメントとして報告され、最終的にプルリクエストが作成されます。
最初のうちは、エージェントの出力を注意深くレビューすることをおすすめします。
期待通りの動作をしない場合は、agents.mdの指示を調整していきます。
Python自動化実践ガイド：日常業務を10倍効率化するスクリプト設計とCI/CD連携では、自動化の基本的な考え方を解説しています。
開発プロセスの自動化を進めるには、アジャイルサムライで紹介されているアジャイル開発の考え方も参考になります。
継続的な改善サイクルを回すことで、エージェントの精度も向上していきます。
agents.mdのベストプラクティスと運用のコツ
カスタムエージェントを効果的に運用するためのベストプラクティスを紹介します。
私がPjMとしてチームで運用してきた経験から得た知見です。
明確なスコープ定義
エージェントに任せるタスクの範囲を明確に定義することが重要です。
「何でもやってくれるエージェント」を作ろうとすると、かえって精度が下がります。
私のチームでは、以下のように役割を分けています。
- Bug Fix Agent：バグ修正専用
- Documentation Agent：ドキュメント更新専用
- Test Agent：テストコード追加専用
コンテキストの適切な提供
エージェントが参照すべきドキュメントやコードの場所を明示的に指定します。
プロジェクトの構造やコーディング規約を理解させることで、出力の品質が向上します。
## Context
- アーキテクチャ概要: `docs/architecture.md`
- API仕様: `docs/api-spec.yaml`
- コーディング規約: `CONTRIBUTING.md`
- 既存のテストパターン: `tests/examples/`段階的な導入と改善
最初から完璧なagents.mdを作ろうとせず、小さく始めて徐々に改善していくアプローチが効果的です。
私のチームでは、最初は単純なドキュメント更新タスクから始め、徐々にコード生成タスクに範囲を広げていきました。
エージェントの出力をレビューするたびに、agents.mdを更新していくことで、精度が向上していきます。
この継続的な改善プロセスは、Team Geek ―Googleのギークたちはいかにしてチームを作るのかで紹介されているチーム運営の考え方とも通じるものがあります。
Playwright Agentsで自動テストを高速化する実践ガイドでは、テスト自動化の観点からエージェント活用を解説しています。
まとめ
GitHub Copilotカスタムエージェントは、開発チームの生産性を大きく向上させる可能性を持った機能です。
agents.mdファイルを適切に設計することで、プロジェクト固有のタスクを自動化し、エンジニアがより創造的な作業に集中できる環境を構築できます。
本記事で解説した内容を振り返ると、以下のポイントが重要です。
- カスタムエージェントは
.github/agents/agents.mdで定義し、Issue単位で自律的に作業を進める agents.mdには役割・指示・コンテキスト・制約を明確に記述する- 曖昧な表現を避け、具体的で明確な指示を書くことが精度向上の鍵
- 小さく始めて段階的に改善していくアプローチが効果的
- タスクの種類ごとにエージェントを分けることで、専門性を高められる
まずは、自分のプロジェクトで最も定型的なタスクを1つ選び、そのためのカスタムエージェントを作成してみてください。
小さな成功体験を積み重ねることで、チーム全体でのAI駆動開発が加速していきます。
厳しめIT女子 アラ美による解説ショート動画はこちら
PjMが厳選した【高年収】への近道
