もう迷わない！copilot-instructions.mdに書くべき7つのこと

はじめに

こんにちは、エンジニア4年目の嶋田です。
この記事を開いていただきありがとうございます！
最近、業務で Spring Boot と MyBatis を使った API 開発に携わり、
GitHub Copilot と copilot-instructions.md を導入してきました。

「AI にプロジェクトの文脈を渡す」と言われても、
最初は私も何を書けばいいのか、どこまで書いていいのかが分からず、
空のファイルを眺めているだけの時期がありました。
公式ドキュメントを踏まえ、業務で設計したときに学んだことをまとめていきたいと思います。

この記事の目的は、copilot-instructions.md に何を書けば Copilot が使いやすくなるかを、次の4つに整理して伝えることです。

1. 何を書くか（7つの観点）
2. 書く・書かないの線引き
3. 他のファイル（AGENTS.md など）との役割分担
4. 長さと開発ステップの決め方

「ファイルは作ったけど中身が決まらない」「何から書けばいいか迷っている」という人に、
今日から埋められる判断軸を渡したいと思って書きました。
ぜひ最後までお付き合いください！(自分のための備忘録でもあります…😅)

目次

• copilot-instructions.md とは
• 何を書くか：7つの観点
• 書く・書かないの線引き
• What と How を分ける考え方
• 長さと「段階」で迷わなくする
• まとめ
• おまけ：まず書くならこの3つ

copilot-instructions.md とは

copilot-instructions.md は、GitHub Copilot がユーザーの指示を処理する前に読み込む、リポジトリ用の指示書です。.github ディレクトリに copilot-instructions.md を置き、Markdown で自然言語の指示を書くだけで有効になります（改行や空白は無視されるので、1段落でも改行区切りでも書けます）。指示書を整えることで、Copilot をプロジェクト専用のアシスタントに近づけられると感じています。

公式では「リポジトリ カスタム指示」として、次の 3 種類が説明されています（リポジトリの指示を追加する）。

1. リポジトリ全体 … .github/copilot-instructions.md（この記事の主役）
2. パス別 … .github/instructions 内の NAME.instructions.md。先頭の frontmatter で applyTo に glob を指定し、特定のファイル・ディレクトリにだけ適用する。2025年11月に excludeAgent プロパティが追加されており、excludeAgent: "code-review" と書くとその指示をコードレビュー時だけ無効化（コーディングエージェントでは有効）、excludeAgent: "coding-agent" と書くとコーディングエージェント時だけ無効化できる。レビュー時と実装時で指示を分けたいときに便利です。
3. エージェント用 … リポジトリ内の AGENTS.md（任意の場所）、またはリポジトリルートの CLAUDE.md / GEMINI.md。AI エージェントが参照する

複数種類の指示が同時に適用されるときの優先順位は 個人用 > リポジトリ > 組織 で、いずれも Copilot に渡されます。矛盾しないように書いておくと安心です。

何を書くか：7つの観点

「何を書けばいいか」で参考にしたのが、次の 7 つです。

1. 前提条件 … 回答言語（日本語など）、大きな変更前の確認の有無
2. アプリの概要 … プロジェクトの目的と主要な機能（抽象度を上げて書く）
3. 技術スタック … 言語・フレームワーク・主要ライブラリとバージョン
4. ディレクトリ構成 … 主要なディレクトリと役割（パスやファイル名は必要最小限に）
5. アーキテクチャ・設計指針 … レイヤー名や「〇〇層はここ」といった方針
6. テスト・ビルド方針 … どのコマンドで何を確認するか
7. アンチパターン … 「こう書かないでほしい」という禁止事項

「どの層が何を担当するか」「どの命名規則に従うか」 まで書いておくだけでも、AI がファイルを探すときの指針になり、提案のブレが減りました。

書く・書かないの線引き

指示書に何を載せるかは、次のように線を引くのがおすすめです。

• 書く: アーキテクチャの「型」（Controller → Service → Repository のような流れ）、ファイル・クラスの命名規則、使用技術とバージョン、コミット前の確認ルール（例: 禁止ファイルリストの確認）
• 書かない: 実装コードの貼り付け、環境依存のパスやツール名など、リポジトリ外に出すとまずい情報

「コード例は載せず、ルールだけ書く」にすると、「ここには Entity、ここには SQL 定義」といった誘導はしつつ、指示書のメンテもしやすくなります。チェックリスト形式（「新しい API を足すときは ① 仕様確認 ② Entity ③ Mapper …」）にすると、AI がやるべき順序を外しにくく、レビューもしやすかったです。

What と How を分ける考え方

copilot-instructions.md と エージェント用の指示（AGENTS.md など）や カスタムエージェント（.agent.md）を両方使う場合、何をどちらに書くかで迷いました。公式の整理にのっとりつつ、「What（何をするか）と How（どうやるか）で分ける」と整理しています。

• copilot-instructions.md … What。リポジトリ全体の方針・規約・制約（「〇〇を使う」「△△は禁止」）
• エージェント用 … How を任せやすい。AGENTS.md やルートの CLAUDE.md / GEMINI.md はエージェントが参照する指示。また カスタム エージェントの作成で用意する .agent.md（.github/agents に配置）では、ツール・使用モデル・振る舞いを YAML frontmatter とプロンプトで定義できる。手順やコマンド、「Always / Ask First / Never」のような境界線をここに書くのに向いている

同じ内容を両方に書くと、片方だけ更新したときに矛盾するので、役割を分けておくのがおすすめです。自分たちのプロジェクトでは、copilot-instructions.md に「レイヤー構成・命名規則・禁止事項」を集約し、実行コマンドや git の細かい手順は別ドキュメントやカスタムエージェントのプロンプトに寄せました。

長さと「段階」で迷わなくする

公式では、リポジトリの指示を追加するの「Copilot コーディングエージェントに生成させる」ときのプロンプトで、2 ページ以内・タスク固有にしない（<Limitations>）という制約が案内されています。自分で copilot-instructions.md を書く場合にも、この目安にすると指示が守られやすく、長すぎてブレるのを防げます。

また、開発のステップを短いキーワードで定義しておくと、AI の動きが安定しやすくなりました。例えば「調査」「計画」「実装」「デバッグ」のようにフェーズを決め、「計画のときはコードを書かない」「実装は計画に書いた範囲だけ」といったルールを指示書に書いておく方法です。やってよいこと・いけないことを短く書くだけでも、提案の範囲が絞られて効果がありました。

まとめ

この記事では、copilot-instructions.md に何を書けば Copilot が使いやすくなるかを、7つの観点・書く/書かないの線引き・What と How の分離・長さと段階の4つに分けて紹介しました。copilot-instructions.md は「プロジェクトの取扱説明書」として、何を書くか・何を書かないかを決めておくことが大切だと感じています。アーキテクチャの型・命名規則・禁止事項・チェックリストまで書くだけで、AI の提案がプロジェクトに沿いやすくなります。

まずは「日本語で答える」「変更前に確認を取る」「禁止リストを守る」の 3 つから始めて、少しずつ足していくのが取り組みやすいと思います。

おまけ：まず書くならこの3つ

最初に何を書くか迷ったとき、自分が入れたのは次の 3 つです。

1. 前提条件
   • 「回答は必ず日本語で」「大きな変更の前に計画を提案し、ユーザーに確認を取る」
2. アーキテクチャの型
   • 「Controller → Service → Repository の順で責務を分ける」など、プロジェクトの層の名前と役割だけ
3. 禁止事項
   -「仕様書にない範囲の実装を提案しない」など

コードは一切書かず、方針と境界線だけにすると、Copilot の振る舞いをかなりコントロールできました。
まずはここから試してみるのがおすすめです。

---

参考（公式ドキュメント）

• GitHub Copilot に対するリポジトリ カスタム指示の追加
• カスタム エージェントの作成