※イメージ画像です（AIにより生成）
結論から言うと、copilot-instructions.mdとは、GitHub Copilotにプロジェクト独自のルール（使用している技術・命名規則・コーディング方針など）を丁寧に教えるための指示書のことです。このファイルを用意しておくことで、Copilotが提案するコードやレビュー内容を、プロジェクトの方針に沿ったものに近づけられます。
この記事でわかること
- copilot-instructions.mdの基本的な役割
- 書くべき内容
- 書き方のコツと注意点
- サンプルの構成イメージ
1. copilot-instructions.mdの基本的な役割
copilot-instructions.mdは、プロジェクトの「.github」フォルダに配置しておくだけで、GitHub Copilotが自動的に認識してくれる指示ファイルです。これを用意しておくことで、毎回同じ説明をCopilotに繰り返す手間を省き、プロジェクト全体で一貫した提案を受けやすくなります。個人の指示・リポジトリの指示・組織の指示など、複数のレベルで設定できる仕組みも用意されており、優先順位は一般的に「個人用 ＞ リポジトリ ＞ 組織」の順とされています。
2. 書くべき内容
- 使用している技術スタック: 使用しているプログラミング言語やフレームワーク、ライブラリのバージョンなど
- 命名規則: 変数名・関数名・ファイル名の付け方のルール
- コーディングスタイル: インデントの幅、コメントの書き方、エラーハンドリングの方針など
- テスト方針: どのようなテストを、どのフレームワークを使って書くべきか
- 避けるべきパターン: プロジェクトで使わない書き方や、非推奨のライブラリ、過去に問題があった実装方法など
これらをあらかじめ伝えておくことで、Copilotの提案がプロジェクトの実情に合ったものになりやすくなります。すべての項目を最初から完璧に埋める必要はなく、重要度の高いものから少しずつ整えていく進め方でも十分効果を発揮します。
3. 書き方のコツと注意点
- 簡潔に、明確に書く: 長文や複雑なルールを詰め込みすぎると、Copilotが正しく理解できないことがあります。要点を絞って書くことが大切です
- 否定形の指示は避ける: 「〇〇をしないでください」という書き方よりも、「〇〇をしてください」という肯定的な表現のほうが、意図が伝わりやすいとされています
- 具体例を示す: 抽象的な説明だけでなく、簡単なコード例を添えることで、より正確に意図を伝えられます
- 定期的に見直す: プロジェクトの技術スタックやルールが変わった際は、instructions.mdの内容も忘れずに更新しましょう。放置すると実態と乖離してしまいます
4. サンプルの構成イメージ
copilot-instructions.mdは、次のような見出し構成で書かれることが多いです。
# プロジェクト概要
このプロジェクトは〇〇を目的としたWebアプリケーションです。
# 使用技術
- 言語: TypeScript
- フレームワーク: React
# コーディング規約
- 変数名はキャメルケースを使用してください
- コンポーネントは1ファイル1つを基本としてください
# テスト方針
- 新しい関数には単体テストを追加してください
このように、プロジェクトの背景・技術・ルール・テスト方針といった項目に分けて整理すると、読みやすく、Copilotにも伝わりやすい指示書になります。
5. 効果を実感しやすい書き方の工夫
- プロジェクト固有の用語を説明する: 社内特有の呼び方や略語がある場合、簡単な説明を加えておくと、Copilotがより文脈を理解しやすくなり、的外れな提案を減らせます
- 良い例・悪い例を対比させる: 「このような書き方を推奨します」「このような書き方は避けてください」という対比形式で示すと、AIにも人間にも意図が伝わりやすくなります
- 優先度の高いルールから書く: すべてのルールを同じ重みで書くのではなく、特に守ってほしい項目を先頭に置くことで、重要度が伝わりやすくなります。全体を短くまとめる意識も忘れないようにしましょう
- チーム全体でレビューする: 一人だけで作成するのではなく、チームメンバーにも内容を確認してもらうことで、認識のズレを未然に防げます
6. よくある失敗パターン
- 情報を詰め込みすぎる: あれもこれもと書き込むうちに、かえって要点がぼやけてしまうケースがあります。まずは最低限守ってほしいルールに絞り、必要に応じて後から加筆していきましょう
- 抽象的な表現に終始する: 「読みやすいコードを書いてください」だけでは、具体的にどう書けばよいかが伝わりにくいため、できるだけ具体的な基準や数値を示すことが大切です
- 作成したまま更新しない: プロジェクトの技術やルールは時間とともに変化します。作成して終わりにせず、定期的な見直しを習慣化しましょう。半年に一度など、見直しのタイミングを決めておくのもよい方法です
- チームに周知しないまま運用する: instructions.mdの存在自体をチームメンバーが知らないと、内容を更新する機会も失われがちです。ドキュメントの一部として、オンボーディング資料などにも組み込んでおくことが望ましいでしょう
まとめ
- copilot-instructions.mdは、プロジェクト独自のルールをGitHub Copilotに伝える指示ファイル
- 技術スタック・命名規則・コーディングスタイル・テスト方針などを書くのが基本
- 簡潔・明確に、肯定的な表現で書くことが重要
- 見出しごとに整理された構成にすると、読みやすく伝わりやすい
よくある質問（FAQ）
Q. instructions.mdはどこに配置すればいいですか？
プロジェクトの「.github」フォルダの中に配置するのが基本的なルールです。ファイル名や配置場所は、公式ドキュメントの最新情報にあわせて確認してください。
Q. 個人用の指示とリポジトリの指示、両方設定した場合はどうなりますか？
一般的に個人用の指示が優先される仕組みになっています。ただし、詳細な優先順位のルールは変更されることがあるため、公式ドキュメントで確認することをおすすめします。
Q. 指示が長すぎると、どんな問題が起きますか？
情報量が多すぎると、Copilotが要点を正しく汲み取れず、期待通りの提案が得られにくくなることがあります。要点を絞って書くことが推奨されています。
Q. チームで内容を共有するにはどうすればいいですか？
instructions.mdはリポジトリの一部としてバージョン管理されるため、通常のコードと同じようにチームメンバーと共有・レビューできます。
Q. 既存のコーディング規約ドキュメントをそのまま使ってもいいですか？
参考にはなりますが、そのままの分量だと長すぎる場合があります。Copilot向けに重要なポイントを抜き出し、簡潔にまとめ直すことをおすすめします。
Q. instructions.mdを作成すると、必ず効果を実感できますか？
プロジェクトの特性や、どの程度具体的に指示を書けるかによって、効果の実感度合いは変わります。まずは小さく始めて、実際の提案内容を見ながら少しずつ内容を調整していくのが現実的なアプローチです。
Q. 複数のプロジェクトで同じ内容を使い回してもいいですか？
基本的な考え方やコーディングスタイルは使い回せる場合がありますが、プロジェクトごとに使用技術や規約が異なることが多いため、そのままコピーするのではなく、プロジェクトの実情にあわせて調整することをおすすめします。
Q. AIに対する指示と、人間向けのドキュメントは分けて作るべきですか？
内容が重複する部分もありますが、Copilot向けの指示は簡潔さが重視されるため、人間向けの詳細なドキュメントとは別に、要点を絞った形で用意するのが望ましいとされています。
Q. instructions.mdの内容は、チームの新メンバーにも役立ちますか？
はい、プロジェクトのルールや技術スタックが簡潔にまとめられているため、新しく参加したメンバーがプロジェクトの概要を素早く把握する助けにもなります。
7. 導入から運用までの流れ
instructions.mdを実際に運用していく際は、次のような流れで進めるとよいでしょう。
- まずは最低限の項目（使用技術・命名規則）だけを書いて運用を始める
- 実際にCopilotの提案を確認しながら、意図と違う部分があれば指示を追加・修正する
- チームメンバーからのフィードバックを反映し、内容を継続的に改善する
- プロジェクトの技術やルールが変わったタイミングで、忘れずに更新する
最初から完璧な指示書を作ろうとせず、実際の運用を通じて少しずつ育てていくという考え方が、結果的に使いやすいinstructions.mdにつながります。
8. 個人開発とチーム開発での書き方の違い
- 個人開発の場合: 自分自身の好みのコーディングスタイルや、よく使うライブラリの情報を中心にまとめるとよいでしょう。自由度が高く、気軽に調整しながら育てていけます
- チーム開発の場合: メンバー間で認識のズレが起きないよう、できるだけ具体的で誤解の少ない表現を心がける必要があります。作成後はレビューを経て、チーム全体の合意のもとで運用することが望ましいです
どちらの場合も、一度書いたら終わりにするのではなく、実際にCopilotを使いながら継続的に見直していく姿勢が大切です。特にチーム開発では、新しいメンバーが加わったタイミングで内容を見直す機会を作ると、常に実情に合った指示書を維持しやすくなります。
※本記事の内容は執筆時点の一般的な情報です。最新の仕様・優先順位ルールは公式ドキュメントでご確認ください。
