GitHub Copilot Agentへの指示方法の調査と使い分け

🏁 はじめに

GitHub Copilot Agentに対して、様々な指示方法があります。

README.md
AGENTS.md
.github/copilot-instructions.md
.github/instructions/*.instructions.md
docs/spec-xxx.md

この記事では、Copilot Agentへの指示方法について調査した結果をまとめています。最後に、各指示方法の使い分けについても考察しています。

調査はConfigure custom instructions for GitHub Copilotの内容を参考に行いました。

個人的なカスタム指示

GitHub Copilot Chat の Personal instructions にカスタム指示を追加すると、リポジトリなどに依存せずすべてのCopilotへの問い合わせに対して、その指示に基づいたチャット応答を受け取ることができます。

個人的なカスタム指示は以下の手順で追加できます。

Copilot Chatを開きます。
左下隅にあるプロフィール写真をクリックし、「Personal instructions」を選択します。
テキストボックスに自然言語の指示を追加します。

リポジトリのカスタム指示

リポジトリ全体のカスタム指示: .github/copilot-instructions.md または .github/instructions/*.instructions.md ファイルに記述します。これらのファイルはリポジトリ全体に適用され、特定のプロジェクトやコンテキストに関する指示を提供できます。
パス固有のカスタム命令: .github/instructions/*.instructions.md に記述します。これらのファイルは特定のディレクトリやファイルパスに関連する指示を提供できます。
エージェント指示: AGENT.md ファイルに記述します。これらの指示は、特定のエージェントの動作を制御するために使用されます。

リポジトリ全体のカスタム指示

リポジトリのルートに、.github/copilot-instructions.mdという名前のファイルを作成します。

具体的な指示例

使用言語とバージョン: 「Python 3.12を使用し、型ヒントを必須とする」
命名規則: 「変数名と関数名はスネークケース、クラス名はパスカルケースとする」
ドキュメント言語: 「コメントやドキュメント、AIの回答はすべて日本語で行う」
禁止事項: 「外部ライブラリを新しく追加する場合は必ず事前に相談すること」
SDDの基本: 「実装前に必ず docs/specs/ 配下の関連ファイルを確認せよ」

パス固有のカスタム指示

特定のディレクトリに対してカスタム指示を提供したい場合、.github/instructions/ ディレクトリ内に NAME.instructions.md ファイルを作成します。

frontmatter ブロックを使用して、指示が適用されるパスを指定します。

---
applyTo: "app/api/**/*.py"
---

- フレームワーク特定: 「FastAPIを使用し、依存性の注入（DI）を積極的に活用せよ」
- エラー処理: 「例外が発生した場合は、共通の APIError クラスを継承した例外をスローせよ」
- 検証: 「入出力には必ず Pydantic モデルを使用すること」

エージェント指示

AGENTS.md ファイルを置くと、エージェントは一番近い AGENTS.md ファイルを見つけて、その指示に従います。近いものを優先するため、複数の AGENTS.md ファイルが存在する場合、意図しない指示が適用される可能性があります。

そのため、AGENTS.md はまだ使用しないほうがよいでしょう。

✅ 指示方法の使い分けの方針

調査した結果、以下のように指示方法を使い分けるのがよいと考えています。

README.md : 人に向けたプロジェクトの説明や構成の説明。AIが見ても良い。
.github/copilot-instructions.md : 全体的なコード生成ルール
.github/instructions/*.instructions.md : 各タイプやモジュールごとのコード生成ルール
docs/specs/*.md : 各機能仕様。いわゆるビジネスロジック。

🎬 おわりに

この記事では、GitHub Copilot Agentへの指示方法について調査した結果をまとめました。各指示方法の特徴と使い分けの方針を理解することで、より効果的にCopilot Agentを活用できるようになるでしょう。今後もCopilot Agentの機能や指示方法が進化する可能性があるため、最新のドキュメントを参照しながら適切な指示方法を選択していくことが重要です。この記事が、Copilot Agentを活用する際の参考になれば幸いです。