copilot-instructions.mdの書き方｜Copilotへの指示設定
GitHub Copilotの提案がプロジェクトの実情に合わないと感じたら、.github/copilot-instructions.md を作るのが解決の近道です。結論から言うと、このファイルにプロジェクト概要やビルドコマンド、規約を書いておくだけで、毎回同じ説明を繰り返す必要がなくなり、提案の的中率が上がります。この記事では、copilot-instructions.mdの役割・適用範囲・書くべき内容を実例つきで解説します。
前提:カスタム指示を使うために必要なもの
.github/copilot-instructions.md を使うには、GitHub Copilotが有効なリポジトリと、対応するエディタ・環境が必要です。VS CodeやVisual Studio、JetBrains系IDE、Xcode、GitHub上のチャットやコーディングエージェントなど、主要な環境はほぼ対応しています。IDEによってはカスタム指示の読み込みを設定でオン・オフできるため、反映されないときはまず設定を確認してください。GitHub Copilot自体の基本機能や始め方は「GitHub Copilotの使い方完全ガイド」で解説していますので、初めての方はあわせて参考にしてください。
.github/copilot-instructions.mdとは何か
.github/copilot-instructions.md は、リポジトリ共通の指示をGitHub Copilotに与えるためのMarkdownファイルです。リポジトリのルートに .github ディレクトリを作り、その中に copilot-instructions.md というファイル名で配置するだけで機能します。特別な構文は不要で、自然言語のMarkdownとして自由に記述でき、単一の段落でも箇条書きでも構いません。
このファイルを置いておくと、Copilotがチャットやエージェント実行のたびに自動的に指示内容を読み込んで回答に反映してくれます。チャットの回答に表示される参照(References)欄に copilot-instructions.md が出てくれば、指示がきちんと読み込まれている証拠です。
適用範囲:Chat・Agent Mode・コーディングエージェント・コードレビュー
.github/copilot-instructions.md は、公式ドキュメントによれば非常に広い範囲で利用されます。VS Code・Visual Studio・JetBrains・Xcode・Copilot CLI・GitHub上のチャットに加え、エディタ内で自律的にタスクをこなす「Agent Mode」、Issueを起点にPRまで作成するコーディングエージェント、プルリクエストのコードレビュー機能まで、主要機能で共通して参照されます。
一方で、より細かくファイル種別ごとに指示を出したい場合は .github/instructions/*.instructions.md という「パス別指示ファイル」も使えます。frontmatterの applyTo にglob(例:"**/*.py")を指定すると、該当ファイルを扱うときだけ指示を追加できます。ただし、パス別指示や個人設定の対応状況は環境によって差があり、非対応の組み合わせもあります。まずはリポジトリ共通の copilot-instructions.md から整備し、必要な段階でパス別指示を足すのが現実的です。
書くべき内容と実例
copilot-instructions.mdに書くべきなのは、Copilotが毎回聞かなくても済むようにしたい「暗黙の前提」です。具体的には、プロジェクト概要、ビルド・テストコマンド、コーディング規約、そして避けてほしい実装パターンの4点を押さえておくと実用的です。以下はサンプルです。
# プロジェクト概要
このリポジトリは、社内向けタスク管理APIです。
バックエンドはTypeScript(Node.js + Express)、
DBはPostgreSQLを使用しています。
# ビルド・テストコマンド
- 依存関係のインストール: npm install
- 開発サーバー起動: npm run dev
- テスト実行: npm test
- コードの変更後は必ず npm run lint を実行し、
エラーがない状態にしてください。
# コーディング規約
- 関数コンポーネントではなくクラスは使用しない
- 非同期処理はasync/awaitで統一し、.then()は使わない
- APIレスポンスの型は必ずsrc/types配下で定義する
- コミットメッセージは日本語で、Conventional Commits形式にする
# 禁止事項
- .env ファイルの内容を出力・引用しない
- 既存のマイグレーションファイルを直接編集しない
(新しいマイグレーションを追加すること)
- 外部ライブラリを新規追加する場合は、
package.jsonの変更理由をコメントで明記するポイントは、抽象的な理想論ではなく、実際に実行できるコマンドや具体的なファイルパスを書くことです。「良いコードを書いてください」のような曖昧な指示は効果が薄く、「npm run lintを通してください」のように検証可能な指示のほうがCopilotは正確に従えます。
CLAUDE.md・AGENTS.mdとの違い
Copilot以外のAIコーディングツールにも、同じ発想の設定ファイルがあります。Anthropic製のClaude CodeのCLAUDE.md、複数ツール共通規格のAGENTS.mdなどで、いずれもプロジェクトのルートに置いてツールへ前提知識を与える点は共通です。実際、公式ドキュメントでもCLAUDE.mdやGEMINI.mdをリポジトリに置いていれば、copilot-instructions.mdの代替として読み込ませられると案内されています。ファイル名は異なっても書くべき内容(プロジェクト概要・ビルドコマンド・規約・禁止事項)は共通するため、複数ツールを併用するなら使い回しやすい構成にしておくと管理が楽です。CLAUDE.mdの詳しい書き方は「CLAUDE.mdの書き方」で解説しています。
アンチパターン:避けるべき書き方
copilot-instructions.mdは書けば書くほど良いわけではありません。よくある失敗パターンは次のとおりです。
- 長すぎる:数百行の指示を詰め込むと、重要な規約が埋もれて逆に守られにくくなります。
- 曖昧すぎる:「読みやすいコードを書く」のような抽象的な指示は、具体的な行動に落とし込めず効果がほとんどありません。
- 矛盾している:過去に追記した指示が最新の規約と食い違ったまま放置されているケースです。矛盾した指示は誤った提案の原因になるため、規約変更時は必ずファイルも更新しましょう。
- 汎用論の羅列:「変数名はわかりやすくする」のようなどのプロジェクトにも当てはまる一般論だけでは、リポジトリ固有の情報になっていません。
つまずきポイント・よくあるエラー
- ファイルを置いたのに反映されない:IDEのCopilot設定でカスタム指示の読み込みがオフになっている場合があります。設定画面で該当項目を確認してください。
- チャットとコードレビューで挙動が違う:機能ごとに対応状況が異なるため、ある環境で効いた指示が別環境では反映されないことがあります。
- パス別指示が優先されると思い込む:リポジトリ共通の指示とパス別指示は基本的に両方とも読み込まれます。役割を分けて書き、重複・矛盾を避けましょう。
- 機密情報を書いてしまう:APIキーやパスワードなど機密性の高い情報は、指示ファイルにも書かないのが原則です。
よくある質問
copilot-instructions.mdはどこに置けばいいですか?
リポジトリのルート直下にある .github ディレクトリの中に copilot-instructions.md という名前で置きます。.github ディレクトリがなければ新規に作成してください。
既存のCLAUDE.mdをそのまま使い回せますか?
公式ドキュメントでは、リポジトリに CLAUDE.md や GEMINI.md を置いていれば代替として読み込ませられると案内されています。対応状況は環境設定によって変わるため、実際にChatの参照欄に表示されるか確認すると確実です。
パス別指示ファイルはどんなときに使うべきですか?
フロントエンドとバックエンドで規約が大きく異なる、テストコードだけ別ルールにしたいなど、ファイル種別ごとに指示を分けたい場面で有効です。まずはリポジトリ全体の内容をcopilot-instructions.mdにまとめ、個別対応が必要な部分だけ.github/instructions/*.instructions.mdに切り出すと管理しやすくなります。
まとめ
.github/copilot-instructions.md は、プロジェクト概要・ビルドコマンド・規約・禁止事項をまとめておくことで、Chat・Agent Mode・コーディングエージェント・コードレビューまで幅広く効果を発揮するカスタム指示ファイルです。抽象的な理想論ではなく検証可能な具体的指示を書くこと、そして内容を長すぎず矛盾のない状態に保つことが、精度を上げるコツです。より実践的な操作方法は「GitHub Copilotの使い方完全ガイド」、タスクを自律的にこなす「Agent Mode」の解説もあわせてご覧ください。