はじめに
昨今のソフトウェア開発において、GitHub Copilotは多くの開発者にとって強力なパートナーとなっています。しかし、そのポテンシャルを最大限に引き出すためには、Copilotにプロジェクトの「背景」や「文脈」を正しく伝えることが不可欠です。
本稿では、そのための鍵となるカスタム指示ファイルの効果的な書き方について、GitHub公式ブログの記事「5 tips for writing better custom instructions for Copilot」を基に解説します。
参考記事
- タイトル： 5 tips for writing better custom instructions for Copilot
- 著者： Christopher Harrison
- 発行元： The GitHub Blog
- 発行日： 2025年9月3日
- URL： https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/
要点
- プロジェクトの概要を記述し、Copilotに開発の全体像を伝える。
- 使用している技術スタック（フレームワーク、言語、データベース等）を明確に列挙する。
- コーディング規約や設計原則など、プロジェクト固有のルールを明記する。
- プロジェクトのディレクトリ構造と各フォルダの役割を説明し、Copilotのファイル理解を助ける。
- 開発を補助するスクリプトやリソースの存在を教え、Copilotがそれらを活用できるようにする。
詳細解説
まず、GitHub Copilotとは新しくチームに加わったメンバーのようなものと捉える必要があります。優秀ではありますが、プロジェクトの暗黙のルールや歴史的経緯を最初から知っているわけではありません。そこで重要になるのが、プロジェクトのルートディレクトリに配置できる 「.github/copilot-instructions.md」 というファイルです。このファイルに指示を書き込むことで、Copilotはチャットやコード生成のたびにその内容を読み込み、より文脈に沿った的確な提案をしてくれるようになります。
以下に、質の高い指示ファイルを作成するための5つの重要なポイントを紹介します。
1. プロジェクトの概要を伝える
まず最初に、開発しているアプリケーションが「何であるか」をCopilotに教えましょう。どのようなアプリケーションで、誰のためのもので、主な機能は何か、といった基本的な概要を簡潔に記述します。長文である必要はなく、数行の「エレベーターピッチ」で十分です。
【記述例：ペットの里親探しを支援するWebサイト】
# Contoso Companions
これは、ペットの里親探し支援機関をサポートするためのウェブサイトです。
各機関はアプリケーションに登録し、施設の場所、里親を募集しているペットの管理、イベントの広報などを行います。
里親希望者は、地域で利用可能なペットを検索したり、機関を見つけたり、里親申請を提出したりすることができます。2. 技術スタックを特定する
次に、プロジェクトで使用している技術を具体的にリストアップします。バックエンドやフロントエンドのフレームワーク、API、データベース、テストツールなど、利用しているものを明記することで、Copilotは生成するコードの言語や構文を正確に選択できます。
【記述例】
## 使用技術スタック
### バックエンド
- APIにはFlaskを使用
- データはPostgresに保存し、ORMとしてSQLAlchemyを利用
- 開発、ステージング、本番用にそれぞれ別のデータベースが存在
- E2Eテストでは、新しいデータベースが作成・投入され、テスト完了後に削除される
### フロントエンド
- サイトのコアとルーティングはAstroが管理
- インタラクティブな部分にはSvelteを使用
- すべてのフロントエンドコードにTypeScriptを使用
### テスト
- PythonのユニットテストにはUnittest
- TypeScriptのユニットテストにはVitest
- E2EテストにはPlaywright3. コーディングガイドラインを明記する
チーム内で定められているコーディング規約や設計上のルールをCopilotに共有しましょう。「JavaScriptではセミコロンを必須にする」「Pythonでは型ヒントを必ず使用する」といったスタイルガイドから、テストに関する要件まで、守るべきルールを記述します。これにより、生成されるコードの品質と一貫性が向上します。
【記述例】
## プロジェクトとコードのガイドライン
- 型ヒントをサポートする言語では常に使用する
- JavaScript/TypeScriptではセミコロンを使用する
- ユニットテストは必須であり、プルリクエスト前に合格する必要がある
- ユニットテストはコア機能に焦点を当てる
- エンドツーエンド（E2E）テストは必須である
- E2Eテストはコア機能に焦点を当てる
- E2Eテストではアクセシビリティを検証する
- 常に良好なセキュリティプラクティスに従う
- RESTful APIの設計原則に従う
- 利用可能な場合はスクリプトを使用してアクションを実行する4. プロジェクトの構造を説明する
プロジェクトのディレクトリ構造を説明することも非常に有効です。どのフォルダに何が入っているのかを明記することで、Copilotはファイル間の関連性を素早く理解し、「この機能のモデルは models/ フォルダにあるはずだ」といった推測が働きやすくなります。
【記述例】
## プロジェクト構造
- server/ : Flaskバックエンドコード
- models/ : SQLAlchemyのORMモデル
- routes/ : リソースごとに整理されたAPIエンドポイント
- tests/ : APIのユニットテスト
- utils/ : データベース呼び出しを含むユーティリティ関数とヘルパー
- client/ : Astro/Svelteフロントエンドコード
- src/components/ : 再利用可能なSvelteコンポーネント
- src/layouts/ : Astroのレイアウトテンプレート
- src/pages/ : Astroのページとルート
- src/styles/ : CSSスタイルシート
- scripts/ : 開発、デプロイ、テスト用のスクリプト
- docs/ : 常に同期を保つべきプロジェクトドキュメント5. 利用可能なリソースを指し示す
プロジェクトに開発を補助するためのスクリプトやツールがある場合、その存在をCopilotに教えましょう。例えば、ワンコマンドで開発環境をセットアップするスクリプトや、テスト全体を実行するスクリプトなどです。Copilotはこれらのツールを認識し、チャットでの対話の中で「test-project.sh を実行してテストを行ってください」といった、より実践的な指示を出せるようになります。
【記述例
## プロジェクト構造
- server/ : Flaskバックエンドコード
- models/ : SQLAlchemyのORMモデル
- routes/ : リソースごとに整理されたAPIエンドポイント
- tests/ : APIのユニットテスト
- utils/ : データベース呼び出しを含むユーティリティ関数とヘルパー
- client/ : Astro/Svelteフロントエンドコード
- src/components/ : 再利用可能なSvelteコンポーネント
- src/layouts/ : Astroのレイアウトテンプレート
- src/pages/ : Astroのページとルート
- src/styles/ : CSSスタイルシート
- scripts/ : 開発、デプロイ、テスト用のスクリプト
- docs/ : 常に同期を保つべきプロジェクトドキュメント【ボーナス】Copilotに指示ファイルを作成させる
「そもそも指示ファイルを何から書けばいいかわからない」という場合、Copilot自身に指示ファイルを作成させるという方法があります。Copilotにリポジトリ全体を解析させ、プロジェクト概要や技術スタックをまとめた指示ファイルの草案を生成させることができます。生成されたファイルを叩き台として、自分たちのプロジェクトに合わせて修正していくことも効率的です。
公式ブログでは、そのためのプロンプト例も紹介されています。これらをCopilotに与えることで、質の高い指示ファイルの作成を始めることができます。
まとめ
本稿では、GitHub Copilotの提案精度を高めるためのカスタム指示ファイル (copilot-instructions.md) の書き方について、5つの重要なポイントとボーナスチップをご紹介しました。
- プロジェクトの概要
- 技術スタック
- コーディングガイドライン
- プロジェクトの構造
- 利用可能なリソース
これらの情報をCopilotに提供することで、Copilotは単なるコード補完ツールから、プロジェクトの文脈を深く理解した真の「相棒」へと進化します。最初から完璧な指示ファイルを目指す必要はありません。まずは簡単なものから作成し、プロジェクトの成長と共に内容を更新していくことをお勧めします。
