copilot-instructions.md は GitHub Copilot の永続的な指示レイヤーだ。.github/copilot-instructions.md に置くだけで、そのリポジトリでのすべての Copilot 補完・チャット応答・PR レビューが自動的にルールに従う——毎回プロンプトに貼り付ける作業は不要になる。
.github/copilot-instructions.md とは何か
GitHub Copilot のデフォルト動作は汎用的だ。数百万のリポジトリから学習した一般的なパターンでコードを生成する。copilot-instructions.md はそのデフォルトをプロジェクト固有のルールで上書きする。
ファイルの配置場所は一か所だけ：.github/copilot-instructions.md。設定変更もプラグインのインストールも不要で、ファイルが存在すれば Copilot が自動的に検出する。形式は普通の Markdown——YAML フロントマターも特殊な構文も必要ない。ファイルの内容全体が自然言語の指示として読み込まれる。
どんなルールを書くべきか。プロジェクト内のすべての AI インタラクションで一貫させたいことなら何でも書ける：
- 言語バージョン（
Python 3.12+ の型ヒントを使用すること） - コードスタイルの判断（
継承よりコンポジションを優先する） - テスト規約（
すべての関数に対応するユニットテストを書くこと） - 命名パターン（
CSS クラス名はケバブケース、JavaScript 変数はキャメルケース） - 禁止パターン（
TypeScript で any を使わないこと） - セキュリティ要件（
データベースクエリに渡す前にすべてのユーザー入力をサニタイズすること）
ファイルはリポジトリにコミットするため、バージョン管理される・PR でレビューされる・ブランチを pull したすべてのチームメンバーに自動的に共有される。個人設定の手順は不要だ。
Copilot が実際にファイルをどう使うか（効くこと・効かないこと）
copilot-instructions.md がどの機能に適用されてどの機能には適用されないかを把握しておかないと、読まれない指示を書いてしまう。
| 機能 | copilot-instructions.md を読む？ | 備考 |
|---|---|---|
| インライン補完（VS Code / JetBrains / Visual Studio） | はい | すべての補完に永続的なコンテキストとして適用 |
| Copilot Chat（IDE 内） | はい | すべてのチャット会話の先頭に追加 |
| Copilot Chat（GitHub.com） | はい | リポジトリスコープのチャットセッションに適用 |
| プルリクエストレビュー（Copilot PR Summary） | はい | プロジェクト標準に照らしたレビューコメントに使用 |
| GitHub Copilot CLI | いいえ | 2026 年時点で CLI はファイルを読まない |
| Copilot Workspace（プレビュー） | 部分的 | 機能によって異なり、今後変更の可能性あり |
最大の注意点は CLI だ。gh copilot suggest や gh copilot explain をターミナルワークフローで使うチームには copilot-instructions.md のルールが適用されない。CLI ユースケースはシェルエイリアスや AGENTS.md で別途対応する必要がある。
IDE の補完については、Copilot はファイルをバックグラウンドのコンテキストとして適用する。指示はサジェストに影響を与えるが、指示に反したコードの生成を完全にブロックするわけではない——Copilot は自分のアウトプットをルールに照らして検証しない。「強いバイアス」として機能するもので、ポリシー強制器ではないと理解しておくこと。
Copilot が copilot-instructions.md で苦手とすること：
- ファイルパス単位の条件分岐（
src/store/ 以下のファイルでのみ Redux を使うこと）——Copilot は指示をグローバルに適用し、ファイルパスでスコープを絞れない - ツール実行命令（
コミット前に npm test を実行すること）——これは CI の責任領域であり、指示ファイルの領域ではない - 長い意思決定ツリー——2 文以上かかる指示は無視されるか部分的にしか適用されない場合がある
copilot-instructions.md vs AGENTS.md vs CLAUDE.md
3 つのファイル、3 つのスコープ。複数の AI コーディングツールを使うチームでは、この違いを把握しないと指示の重複や抜けが生じる。
| 項目 | copilot-instructions.md | AGENTS.md | CLAUDE.md |
|---|---|---|---|
| 対象ツール | GitHub Copilot 専用 | クロスツール標準 | Claude Code 専用 |
| 配置場所 | .github/ | プロジェクトルート | プロジェクトルート |
| 自動検出するツール | GitHub Copilot | Copilot / Cursor / Claude Code / OpenAI Codex | Claude Code |
| マージ / 階層 | 単一ファイル・フラット | 階層型（ルート + サブディレクトリ） | 階層型（ルート + サブディレクトリ） |
| チーム共有 | はい（git commit） | はい（git commit） | はい（git commit） |
| ファイルパスでのスコープ指定 | 不可 | 可（サブディレクトリファイル） | 可（サブディレクトリファイル） |
copilot-instructions.md のみを使う場合： Copilot 一択のチーム。Cursor も Claude Code も使わない。ファイルを集中して書ける。
copilot-instructions.md と AGENTS.md を両方使う場合： Copilot ユーザーと Cursor / Claude Code ユーザーが混在するチーム。共有のプロジェクトルールは AGENTS.md に書き、Copilot 固有の追加事項を copilot-instructions.md に書く。
3 つすべてを使う場合： Copilot を主要な補完ツールとしつつ、Claude Code でリファクタリング・テスト生成・マイグレーションなどのエージェントタスクも行う大規模コードベース。3 ファイルが共存しても競合は起きない。
1 つだけ選ぶなら AGENTS.md が最も投資対効果が高い。他の 2 ファイルより多くのツールに届く。
実践テンプレート 10 選
1. TypeScript / React プロジェクト
# Copilot Instructions
## 言語・ランタイム
- TypeScript 5.x strict モード。`any` や `unknown` を使う場合はコメントで理由を明記すること。
- React 18+ の関数コンポーネントとフックのみ。クラスコンポーネントは使わない。
- デフォルトは `const`。再代入が必要な場合のみ `let` を使う。
## インポート
- 絶対インポートのみ。パスエイリアス `@/` は `src/` にマッピングする。
- インポートの順序：React → 外部ライブラリ → 内部モジュール → スタイル。グループ間は空行 1 行。
## コンポーネント
- 1 ファイル 1 コンポーネント。ファイル名はコンポーネント名（PascalCase）と一致させる。
- Props インターフェースはコンポーネント関数の直上にインラインで宣言する。
- 2 レベルを超える Props のバケツリレーは禁止——コンテキストか状態管理を使う。
## テスト
- すべてのコンポーネントは同じ場所に `*.test.tsx` ファイルを持つ。
- React Testing Library を使う。Enzyme は不可。
- 実装の詳細ではなくユーザーの行動をテストする。2. Python Django プロジェクト
# Copilot Instructions
## Python バージョン
- Python 3.12+。すべての関数シグネチャに型ヒントを使うこと。
- ファイルシステム操作には `os.path` ではなく `pathlib.Path` を使う。
## Django パターン
- CRUD 処理はクラスベースビュー。単発のエンドポイントは関数ベースビュー。
- すべてのモデルには `__str__` メソッドと `ordering` を含む `Meta` クラスが必要。
- 本番コードで `Model.objects.all()` をフィルターなしで呼ばない。
- N+1 クエリを防ぐため `select_related` と `prefetch_related` を活用する。
## API
- すべての API エンドポイントに Django REST Framework を使う。
- シリアライザのバリデーションは明示的に行う——デフォルトフィールドバリデーションへの依存は禁止。
- エラーメッセージは RFC 7807 Problem Details 形式で返す。
## セキュリティ
- ユーザー入力を生の SQL クエリに補間しない。ORM またはパラメータ化クエリを使う。
- すべてのファイルアップロードはMIMEタイプを検証してから保存する。3. Go マイクロサービス
# Copilot Instructions
## Go バージョン・スタイル
- Go 1.22+。標準の `gofmt` / `goimports` フォーマットに従う。
- エラー処理：常にエラーをチェックする。本番コードで `_` でエラーを捨てない。
- 回復不能な初期化エラー以外はパニックではなくエラーを返す。
## パッケージ構造
- ディレクトリ 1 パッケージ。パッケージ名はディレクトリ名と一致させる。
- `util`・`common`・`helpers` というパッケージ名は避ける——ドメイン固有の名前を使う。
- 内部パッケージは `internal/` 以下、公開パッケージは `pkg/` 以下に置く。
## 並行処理
- goroutine の所有権はゴルーチン起動の直上のコメントに記載する。
- 調整にはチャネルを使い、共有状態の保護にはミューテックスを使う。
- I/O を行う関数の第 1 引数には常に context を渡す。
## テスト
- すべてのエクスポート関数にはテーブル駆動テストを書く。
- 統合テストは `*_integration_test.go` ファイルに `//go:build integration` ビルドタグを付けて分離する。4. セキュリティ重視のチーム
# Copilot Instructions
## セキュリティの絶対ルール
- 認証情報・API キー・トークン・シークレットをハードコードしない。環境変数またはシークレットマネージャーを使う。
- ユーザー入力はビジネスロジック内ではなく境界でサニタイズ・バリデーションする。
- データベース操作はすべてパラメータ化クエリを使う。SQL への文字列補間はクリティカル違反。
- すべての Cookie に `HttpOnly` と `Secure` フラグを設定する。
- 認証・認可の失敗・入力バリデーションエラーはセキュリティイベントとしてログに記録する。ただしパスワード・トークン・クレジットカード番号全体はログに残さない。
## 依存関係
- 依存関係のバージョンは完全に固定する。本番依存関係にバージョン範囲指定を使わない。
- 新しい依存関係は main へのマージ前にセキュリティレビューを受けること。5. コードレビュースタイルガイド
# Copilot Instructions
## プルリクエストのレビュー時
- 最も重要な問題を最初に提示する。軽微なコメントの後にブロッカーを埋めない。
- ブロッカー（マージ前に必ず修正）と提案（あると良い）を区別する。
- 何を変えるかだけでなく、なぜ変える必要があるかを説明する。
- 個人の好みではなく、このファイルや AGENTS.md のプロジェクト規約を根拠にする。
## コメントのトーン
- 直接的かつ敬意を持って。「あなたは〜すべき」は避け、「この関数は〜できる」「〜を検討してください」と書く。
- 自明でない提案にはレビューコメントにコード例を含める。6. モノレポ（マルチパッケージ）
# Copilot Instructions
## モノレポ構造
このリポジトリは Turborepo モノレポです。パッケージは `packages/` 以下、アプリケーションは `apps/` 以下に配置します。
## クロスパッケージルール
- `packages/` 内から `apps/` をインポートしない。パッケージはアプリケーションに依存しない。
- 共有型は `packages/types` に、共有ユーティリティは `packages/utils` に置く。
- 新しいパッケージ依存関係を追加するときはルートの `package.json` ワークスペースを先に更新する。
## 変更スコープ
- `packages/` への変更は複数のアプリに影響する可能性があるため、PR の説明にクロスアプリへの影響を記載する。
- PR をレビュー準備完了にする前に `turbo build` と `turbo test` を実行する。7. テスト重視のプロジェクト
# Copilot Instructions
## テスト要件
- 新しい関数やメソッドには必ず 1 つ以上のユニットテストが必要。
- バグ修正には、そのバグを検出できたであろうリグレッションテストが必要。
- テストファイルの命名：ユニットテストは `*.test.ts`、統合テストは `*.spec.ts`。
## テスト品質
- Arrange-Act-Assert パターン。テスト 1 つにつき検証する概念は 1 つ。
- テストは決定論的であること——sleep・random・モックなしの外部ネットワーク呼び出しは禁止。
- テスト名の形式：`describe('[関数名]') > it('[条件] のとき [期待される動作]')`.
## カバレッジ
- 行カバレッジ目標：80%。分岐カバレッジ目標：70%。
- カバレッジレポートはすべての CI 実行で生成する。目標を下回るリグレッションはマージをブロックする。8. ドキュメントファーストのチーム
# Copilot Instructions
## ドキュメント要件
- エクスポートされるすべての関数・クラス・インターフェースにはドキュメントコメントが必要。
- ドキュメントコメントには目的・引数と型・戻り値・自明でない関数には使用例を含める。
- コードを言い換えるだけのコメントは禁止。コメントは「なぜ」を、コードは「何を」を説明する。
## README 更新
- インストール・設定・公開 API に影響する変更には README の更新を含める。
- ドキュメント内のコード例はテスト済みであること——doctest または同等のものを使う。
## 変更ログ
- ユーザーに見える変更はすべてリリース前に CHANGELOG.md の `[Unreleased]` セクションに記載する。9. レガシーコードのメンテナンス
# Copilot Instructions
## レガシーコードとの付き合い方
このコードベースには 2018 年以前に書かれた箇所がある。明示的なリファクタリング指示がない限り、モダンな代替手法を導入するより既存パターンとの一貫性を優先する。
## 変更の規律
- フットプリントを最小限に：バグ修正や機能実装に必要な箇所のみ変更する。
- 現在の変更の直接の経路にないコードをリファクタリングしない。
- レガシーコードを変更する必要がある場合は、変更前にテスト（キャラクタリゼーションテスト）を追加する。
## 依存関係
- 機能変更の副作用として依存関係をアップグレードしない。依存関係のアップグレードは独立した PR にする。
- `src/legacy/` 内のファイルを変更する前に `LEGACY_NOTES.md` の既知の癖を確認する。10. API 設計チーム
# Copilot Instructions
## API 設計基準
- RESTful リソース命名：複数形の名詞、URL パスに動詞を含めない（`/getUsers` ではなく `/users`）。
- HTTP メソッドのセマンティクス：GET（冪等な読み込み）/ POST（作成）/ PUT（全体置換）/ PATCH（部分更新）/ DELETE。
- すべてのレスポンスに統一エンベロープを使う：`{ "data": ..., "meta": ..., "errors": [] }`。
## バージョニング
- API バージョンは URL パスに含める：`/v1/`・`/v2/`。ヘッダーベースのバージョニングは使わない。
- メジャーバージョンバンプなしにレスポンスからフィールドを削除しない。
- 削除前に OpenAPI 仕様の `deprecated: true` マーカーでフィールドを非推奨にする。
## ドキュメント
- すべてのエンドポイントは実装開始前に `openapi.yaml` に記載する。
- エラーコードは `docs/error-codes.md` に一覧化する。上級パターン
トークン予算：2,000 トークン以内に収める
Copilot のコンテキストは無限ではない。指示ファイルはコード・開いているファイル・会話履歴とコンテキストウィンドウを奪い合う。2,000 トークン（英語で約 1,500 語、日本語で約 1,000〜1,200 文字相当）を超えると切り捨てられる可能性があり、その通知は届かない。
優先順位が重要になる理由はここにある。最も重要なルールを先頭に置くこと。ファイルが途中で切られても、言語バージョン要件やセキュリティルールが生き残るようにしたい——コミットメッセージのフォーマットのセクションではなく。
指示の並び順（推奨）
影響の大きいものを先に：
- 言語バージョンとツールチェーン（TypeScript のバージョン・Python のバージョン・フレームワークバージョン）
- ハード制約（セキュリティルール・絶対に許容できないパターン）
- アーキテクチャ規約（ファイル構造・命名パターン・インポートルール）
- テスト要件
- コードスタイルの好み（優先度低——通常はリンターが処理する）
- ドキュメント規約
Copilot が無視しやすい指示
一部の指示は一貫して効果が低い：
- ファイルパスのスコープ指定：
"src/auth/ 内のファイルにのみこのルールを適用する"——Copilot は指示をグローバルに適用する。パススコープのルールにはサブディレクトリレベルのAGENTS.mdファイルを使うこと - ワークフロー指示：
"コード生成前にテストスイートを実行する"——Copilot は補完の途中でコマンドを実行できない - 外部ツール参照：
"Jira チケット XYZ-123 を確認する"——補完中に外部ツールへのアクセス手段がない
AGENTS.md との組み合わせ（マルチツールチーム向け）
複数の AI ツールを使うチームには 2 ファイル構成が機能する：
AGENTS.md（共有のプロジェクトルール）：
# AGENTS.md
## コマンド
npm run build
npm test
## コード基準
- TypeScript strict モード
- any 型は使わない
- テストには Vitest を使う.github/copilot-instructions.md（Copilot 固有の追加）：
# Copilot Instructions
AGENTS.md のすべてのルールを適用する。Copilot 固有の追加ガイダンス：
## 補完の動作
- 関数スタブを補完するときは必ずエラー処理を含める。
- 公開 API を持つ関数には型推論ではなく明示的な戻り値の型を使う。Copilot の指示ファイルから AGENTS.md を明示的に参照することで、2 つのファイルの概念的な同期が保たれ、重複が減る。
よくある質問
copilot-instructions.md とは何ですか？
.github/copilot-instructions.md に置く Markdown ファイルで、GitHub Copilot が自動的に読み込んでカスタム指示を永続的に適用する。インライン補完・Copilot Chat・プルリクエストレビューに適用される。
copilot-instructions.md はどこに置きますか？
リポジトリルートの .github ディレクトリ直下の .github/copilot-instructions.md のみ対応。他のパスは認識されない。
copilot-instructions.md は Copilot CLI で使えますか？
いいえ。2026 年時点で Copilot CLI（gh copilot suggest・gh copilot explain）は copilot-instructions.md を読み込まない。CLI ユーザーは手動でコンテキストを提供するか、対応するツールで AGENTS.md を使う必要がある。
copilot-instructions.md と AGENTS.md の違いは何ですか？
copilot-instructions.md は Copilot 専用。AGENTS.md は Copilot・Cursor・Claude Code・OpenAI Codex が対応するクロスツール標準。複数の AI ツールを使うチームは AGENTS.md をメインの指示ファイルとし、copilot-instructions.md で Copilot 固有の追加を管理するのが推奨。
copilot-instructions.md の適切な長さは？ 2,000 トークン以内（日本語で概ね 1,000〜1,200 文字）。コンテキスト予算を超えた場合に備えて、最重要ルールをファイルの先頭に配置すること。
GitHub Copilot は AGENTS.md を読みますか？
はい。AGENTS.md が存在する場合に読み込む。Copilot 固有の設定については copilot-instructions.md が優先されるが、両ファイルが参照される。マルチツールチームでは両方のファイルを維持することを推奨する。
関連記事
- AGENTS.md と GitHub Copilot の統合 — AGENTS.md が Copilot の各機能とどう連携するか
- AGENTS.md ベストプラクティス — 60,000 以上のリポジトリから導き出した設計原則
- CLAUDE.md ガイド — Claude Code 専用の指示ファイルリファレンス
Copilotエンタープライズの機密情報を守る
.github/copilot-instructions.md で内部ツールや認証パターンを参照する場合、実際のシークレットはファイルに含めないこと。1Password CLI の op run でシークレットをランタイム時に注入すれば、リポジトリに .env ファイルが入ることもなく、シェル履歴にキーが残ることもない。ワークフローが触れるすべてのシークレットの監査ログも自動的に生成される。