GitHub Copilotの指示ファイルを分ける：copilot-instructions.md・.instructions.md・AGENTS.mdの置き場所

このテーマをもう少し広げて見るなら、AGENTS.md標準化の実務影響：AIコーディング指示ファイルをチーム運用に入れる判断基準 と VS CodeのCopilot Agent ModeにMCPをつなぐ前に：sandbox・allowlist・料金を確認する も合わせて確認してください。AGENTS.mdをCopilotだけでなく複数agentの共通指示として扱うときの前提を補える。

3行まとめ

Repo-wide

全体ルールはcopilot-instructions.mdへ短く置きます。

Path-specific

言語やディレクトリ固有ルールは.instructions.mdへ分けます。

Agent-wide

複数agent共通の作業規約はAGENTS.mdで補います。

1つの巨大な指示ファイルにしないことが出発点です。

• GitHub Copilotの指示ファイルは、全体ルールを.github/copilot-instructions.md、言語やディレクトリ固有ルールを.github/instructions/*.instructions.md、複数agent共通の作業規約をAGENTS.mdへ分けると管理しやすくなります。
• PRレビューで使わせたい指示は、GitHub Docsが示す4,000文字制限とbase branch参照を前提に、重要なルールをファイル前半へ置きます。
• 「Copilotが指示を読まない」と感じたら、ファイル名だけでなく、GitHub.com、VS Code、Copilot code review、cloud agent、IDEごとの対応差を確認します。

本文の事実確認には、GitHub Copilotのcustom instructions公式Docs、custom instructions support matrix、VS Codeのcustom instructions Docs、GitHub Changelogを使っています。Xで見かける「指示ファイルが効かない」「AGENTS.mdとcopilot-instructions.mdをどう分けるか」という話題は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

置き場所

どの指示をどのファイルへ置くか。

PRレビュー

4,000文字制限とbase branch参照を前提にします。

対応差

GitHub.com、VS Code、IDE、CLIの差を見ます。

テンプレート

最小構成から始めます。

Copilotに伝える前に、人間が管理できる形へ分けます。

• .github/copilot-instructions.mdに入れるべき全体ルール
• .github/instructions/*.instructions.mdへ逃がすべきpath固有ルール
• AGENTS.mdとCopilot専用ファイルを併用するときの考え方
• Copilot code reviewで効かせる前に確認する制限
• VS CodeとGitHub.comで指示の対応範囲が違う点
• 最小テンプレートと導入初週の進め方

AIエージェント向けの指示ファイルは、増やすほど安心に見えます。ただ、実際には長すぎる指示、矛盾した指示、対象外の機能に期待した指示が増えると、出力はむしろ不安定になります。

この記事では、指示ファイルを「どこに置くか」ではなく、「どの作業に読ませたいか」から分けます。

前提知識

項目	内容	見方
Repo-wide		リポジトリ全体へ効く短い指示。
Path-specific		特定pathや言語だけに効く指示。
Agent instructions		複数agent向けの共通規約。
Organization		組織で共通に配る指示。

指示ファイルは、置ける場所と読まれる機能を分けて見ます。

GitHub Docsでは、Copilotのrepository custom instructionsとして、repository-wide custom instructions、path-specific custom instructions、agent instructionsが説明されています。repository-wideは.github/copilot-instructions.md、path-specificは.github/instructions配下のNAME.instructions.md、agent instructionsはAGENTS.mdなどです。

VS Code Docsでも、.github/copilot-instructions.mdはworkspace内のchat requestへ自動適用される全体指示、.instructions.mdはfile typeやlocationに応じて適用する指示として説明されています。ただし、VS Code Docsはinline suggestionsにはcustom instructionsが考慮されないとも説明しています。

公式Docsで押さえること

この記事では、次の範囲を前提にします。

種類	例	主な用途
repository-wide	.github/copilot-instructions.md	リポジトリ全体の規約
path-specific	.github/instructions/frontend.instructions.md	特定path、言語、領域の規約
agent instructions	AGENTS.md	複数agent共通の作業規約
organization instructions	GitHub organization設定	複数repoへ配る共通ルール

条件

2026年5月31日時点で、GitHub DocsとVS Code Docsの公開情報を確認しています。Copilotの対応範囲は変わりやすいため、導入時には最新のsupport matrixと組織設定を確認してください。

注意点

「このファイル名なら常に効く」と考えると事故ります。Copilot Chat、Copilot cloud agent、Copilot code review、VS Code、JetBrains、CLIでは対応範囲が違います。

まず1枚で分ける

項目	内容	見方
全体方針		短く全員向けに置きます。
Reactだけ		UIやtsxの規約だけ分けます。
APIだけ		認可、DB、handler規約を分けます。
複数agent		ツール横断の作業規約を置きます。

全体ルールと局所ルールを混ぜないようにします。

指示ファイルは、最初に置き場所を決めるより、読み手を分ける方が失敗しにくいです。

読ませたい相手	置き場所	入れる内容
Copilot全体	.github/copilot-instructions.md	技術スタック、標準コマンド、禁止操作、レビュー形式
frontend作業	.github/instructions/frontend.instructions.md	React、CSS、アクセシビリティ、UIテスト
backend作業	.github/instructions/backend.instructions.md	API、DB、認可、transaction
docs作業	.github/instructions/docs.instructions.md	文体、用語、公開前チェック
複数agent	AGENTS.md	破壊的操作、テスト、承認、作業報告
組織全体	organization instructions	全社共通のセキュリティ、コンプライアンス

全体指示と局所指示を混ぜない

.github/copilot-instructions.mdに、Reactの細かいコンポーネント規約、DB migrationの手順、ドキュメントの文体、PRレビューの観点を全部入れると、全リクエストで重くなります。

全体指示は、すべての作業で読まれても邪魔にならないものだけにします。たとえば、標準コマンド、secretを出さない、未実行テストを書く、破壊的操作は承認を取る、といったルールです。

詳細は必要な場所に置く

path-specific instructionsは、特定のfile pathや作業領域に効かせるための置き場所です。Reactのルールはfrontend、PrismaやSQLのルールはbackend、Markdownの文体はdocsへ分けます。

判断基準

迷ったら、「この指示はREADME修正でも必要か」と考えます。必要なら全体指示、不要ならpath-specificへ分けます。

copilot-instructions.mdに入れること

Stack

主要技術、避けるライブラリ。

Commands

標準のlint、typecheck、test。

Security

secret、権限、外部通信の扱い。

Review

PRで必ず書く検証結果。

毎回読まれても邪魔にならない情報だけに絞ります。

.github/copilot-instructions.mdは、リポジトリ全体で毎回読まれてよい短いルールに向いています。

入れる項目

項目	書く内容
技術スタック	Next.js、TypeScript、Node、Pythonなど
標準コマンド	npm run typecheck、npm test、npm run lint
禁止操作	secret出力、破壊的DB操作、勝手なdependency追加
レビュー形式	Summary、Tests run、Not run、Risks
セキュリティ	API key、個人情報、本番ログの扱い
変更範囲	関係ないリファクタを広げない方針

書き方の例

# Copilot instructions

- Use TypeScript strict patterns already present in this repository.
- Before opening a pull request, report Summary, Tests run, Not run, and Risks.
- Do not print secrets, tokens, cookies, private keys, customer data, or production logs.
- Prefer small diffs. Do not rewrite unrelated files.
- Use `npm run typecheck` and the nearest relevant test before saying the change is ready.

この程度で十分です。プロジェクトの全仕様を入れるのではなく、作業の外枠を固定します。

先頭に重要ルールを置く

GitHub Docsでは、Copilot code reviewは各custom instruction fileの先頭4,000文字だけを読むと説明されています。PRレビューで使わせたい規約は、先頭へ寄せます。

入れすぎない

全体指示が長いほど、重要な指示が埋もれます。特にPRレビュー向けのルールは、ファイルの前半だけで意味が通るようにします。

.instructions.mdに分けること

Frontend

React、CSS、アクセシビリティ。

Backend

API、DB、transaction、認可。

Tests

test fixture、mock、E2E。

Docs

文体、用語、公開前確認。

詳細ルールは必要な作業のときだけ読ませます。

.github/instructions/*.instructions.mdは、path-specific custom instructionsとして扱います。GitHub Docsでは、該当pathのfile contextに応じて使う説明があります。

分ける単位

ファイル例	対象
.github/instructions/frontend.instructions.md	app/、components/、*.tsx
.github/instructions/backend.instructions.md	api/、server/、DB access
.github/instructions/tests.instructions.md	tests/*、.spec.ts、*.test.ts
.github/instructions/docs.instructions.md	docs/*、.md

frontendの例

---
applyTo: "app/**/*.{ts,tsx},components/**/*.{ts,tsx}"
---

- Keep UI text concise and avoid explaining implementation details in the interface.
- Prefer existing components before adding new UI primitives.
- Include accessibility states for interactive controls.
- Run the nearest component or Playwright test when changing behavior.

VS Code Docsでは、file-based instructionsはglob patternで条件適用できると説明されています。フロントエンドだけの規約を全体指示に混ぜず、対象pathに寄せます。

backendの例

---
applyTo: "api/**/*.{ts,tsx},server/**/*.{ts,tsx},db/**/*.{ts,tsx}"
---

- Treat authorization checks as part of the handler, not as a follow-up.
- Do not log access tokens, cookies, request bodies with personal data, or database URLs.
- For schema changes, include migration notes and rollback considerations.

注意点

path-specific instructionsを増やしすぎると、どの指示が効くべきか人間が追えなくなります。最初はfrontend、backend、tests、docs程度に止め、失敗例が出た領域だけ足します。

AGENTS.mdと併用するときの考え方

1. 1共通規約

   破壊的操作、テスト、承認をAGENTS.mdへ。

2. 2Copilot向け

   Copilotで確実に見たい短い規約をcopilot-instructionsへ。

3. 3局所ルール

   path別の詳細を.instructions.mdへ。

4. 4重複削除

   同じルールを複数箇所に長く書かない。

AGENTS.mdは便利ですが、対応差を前提に併用します。

AGENTS.mdは、複数のAIエージェントに読ませたい共通の作業規約に向いています。たとえば、破壊的操作を避ける、既存変更を戻さない、テスト手順を守る、PR報告形式を固定する、といった内容です。

ただし、GitHub Docsのsupport matrixでは、agent instructionsの対応範囲は機能ごとに違います。Copilotのすべての機能がAGENTS.mdを同じように扱う前提にはしません。

併用の基本

置き場所	役割
AGENTS.md	複数agent向けの共通作業規約
.github/copilot-instructions.md	Copilotで確実に読ませたい短い全体規約
.github/instructions/*.instructions.md	Copilot向けの領域別詳細

重複させるなら短く

「secretを出さない」「破壊的操作は承認」「未実行テストを書く」のような重要ルールは、AGENTS.mdとcopilot-instructions.mdの両方へ短く置いても構いません。

一方で、同じ長文を複数ファイルへコピーすると、片方だけ古くなります。共通の一文だけ重ね、詳細は片方へ寄せます。

実務上の目安

AGENTS.mdは開発チーム全体の作業契約、copilot-instructions.mdはCopilot向けの最短版、.instructions.mdは領域別の補足、と考えると分けやすいです。

PRレビューで効く前提を確認する

項目	内容	見方
4,000 chars		Code reviewは各指示ファイルの先頭4,000文字まで。
Base branch		PRレビューはbase branch側の指示を使います。
設定		custom instructions利用設定を確認します。
要点先頭		重要ルールをファイル前半へ置きます。

PRレビュー用の指示は短く、先頭に寄せます。

Copilot code reviewに指示を効かせたい場合は、通常のChatより制限を強く見ます。

GitHub Docsでは、Copilot code reviewがcustom instruction fileの先頭4,000文字だけを読むこと、PRレビューではbase branchのcustom instructionsを使うことが説明されています。また、repository settingsのCopilot code reviewでcustom instructions利用を切り替える案内もあります。

PRレビュー用に置くルール

PRレビューで見てほしいルールは、.github/copilot-instructions.mdの先頭へ置きます。

# Review priorities

- Flag missing authorization checks in API handlers.
- Flag logs that may contain tokens, cookies, private keys, customer data, or production payloads.
- Flag PRs that claim tests passed without listing the exact command.
- Prefer comments on changed lines over broad style suggestions.

base branchを忘れない

feature branchに指示ファイルを追加しても、そのPRレビューがbase branchの指示を見るなら、すぐには効きません。最初に指示ファイルをmainへ入れてから、後続PRでレビュー品質を見る方が検証しやすいです。

4,000文字を前提にする

PRレビュー用の指示は、長い背景説明より優先順位です。重要なものを先頭に置き、詳細な実装ルールはpath-specificへ分けます。

失敗しやすい例

• 先頭にプロジェクト紹介を長く書く
• PRレビューで見てほしいルールが後半にある
• base branchに指示ファイルが入っていない
• repository設定でcustom instructions利用が有効か確認していない

VS CodeとGitHub.comで違うところ

項目	内容	見方
GitHub.com Chat		個人、repo-wide、組織指示を見ます。
Cloud agent		repo-wide、path-specific、agent instructionsに対応。
VS Code Chat		repo-wide、path-specific、AGENTS.mdを扱います。
Inline suggestion		VS Code Docsではcustom instructions対象外と説明。

効かないときは、まず対象機能の対応表を確認します。

同じcustom instructionsでも、機能ごとに対応範囲が違います。GitHub Docsのsupport matrixでは、GitHub.comのCopilot Chat、Copilot cloud agent、Copilot code review、VS Code、Visual Studio、JetBrains、Eclipse、Xcode、Copilot CLIで対応するinstruction typeが分かれています。

大きな違い

場所	見方
GitHub.com Copilot Chat	personal、repo-wide、organization instructionsを見る
GitHub.com cloud agent	repo-wide、path-specific、agent instructions、organization instructionsを見る
GitHub.com code review	repo-wide、path-specific、organization instructionsを見る
VS Code Chat	repo-wide、path-specific、AGENTS.mdを見る
VS Code inline suggestions	VS Code Docsではcustom instructions対象外

「効かない」ときの確認順

1. そのCopilot機能が対象instruction typeに対応しているか
2. 指示ファイルがbase branchやworkspace rootにあるか
3. path-specificのglobが対象fileに合っているか
4. 重要ルールが先頭4,000文字以内にあるか
5. 個人、repo、組織の指示が矛盾していないか

個人設定とチーム設定を混ぜない

個人の文体や好みはpersonal instructionsでよいですが、チームのセキュリティ、テスト、PR形式はrepoかorganizationへ置きます。個人設定にチーム規約を置くと、他のメンバーやagentに効きません。

悪い指示ファイルのサイン

長すぎる

全体指示が仕様書になっている。

矛盾

複数ファイルで同じ項目が違う。

局所混在

ReactとDB規約が同じ場所にある。

検証不明

実行すべきtestが書かれていない。

指示ファイルは詳しさより、衝突しない短さが効きます。

指示ファイルは、長いほど賢くなるわけではありません。次の状態になったら、分割か削除を考えます。

サイン	起きる問題
200行を超えた全体指示	重要ルールが埋もれる
同じルールが複数箇所にある	更新漏れで矛盾する
作業と関係ない指示が毎回入る	回答が鈍くなる
禁止だけが多い	何をすればよいかが曖昧
テスト手順がない	完了報告の品質が上がらない
古いコマンドが残る	agentが失敗を繰り返す

よい指示は短く具体的

「品質高く書いて」ではなく、「変更後はnpm run typecheckと該当testを実行し、未実行なら理由を書く」と書きます。

「セキュリティに注意」ではなく、「token、cookie、private key、顧客情報、本番payloadをログに出さない」と書きます。

指示ではなく仕組みにする

毎回守らせたいルールは、可能ならCI、lint、test、PR templateへ移します。指示ファイルは、仕組みで縛れない判断材料を補う場所です。

削る基準

人間が読んでも「これは今のrepoで本当に使うのか」と迷う指示は削ります。Copilotにだけ長文で期待するより、repoの標準コマンドやチェックリストを短く置く方が効きます。

最小テンプレート

項目	内容	見方
copilot-instructions.md		全体方針、標準コマンド、禁止操作。
frontend.instructions.md		UI、React、アクセシビリティ。
backend.instructions.md		API、DB、権限。
AGENTS.md		複数agent共通の作業ルール。

最初から細かく分けすぎず、衝突しやすい領域だけ分けます。

最初は、4ファイルで十分です。

.github/
  copilot-instructions.md
  instructions/
    frontend.instructions.md
    backend.instructions.md
AGENTS.md

.github/copilot-instructions.md

# Copilot instructions

- Keep changes focused. Do not rewrite unrelated files.
- Report Summary, Tests run, Not run, and Risks for every PR.
- Do not print secrets, tokens, cookies, private keys, customer data, or production logs.
- Use existing project patterns before adding new abstractions.
- Run `npm run typecheck` and the nearest relevant test when code changes.

.github/instructions/frontend.instructions.md

---
applyTo: "app/**/*.{ts,tsx},components/**/*.{ts,tsx}"
---

- Prefer existing UI components and design tokens.
- Keep text concise and do not expose implementation notes in the UI.
- Include loading, empty, error, disabled, and keyboard states for interactive UI.
- For behavior changes, run the nearest component or Playwright test.

.github/instructions/backend.instructions.md

---
applyTo: "api/**/*.{ts,tsx},server/**/*.{ts,tsx},db/**/*.{ts,tsx}"
---

- Treat authorization and input validation as part of the change.
- Do not log secrets, credentials, full request bodies, or customer data.
- Include migration and rollback notes for schema changes.

AGENTS.md

# AGENTS.md

- Do not run destructive commands without explicit approval.
- Do not revert user changes you did not make.
- Prefer the repository's existing patterns.
- Before completion, run the relevant tests and report anything not run.

ここから増やす

失敗例が出たときだけ、該当するファイルへ1つ追記します。たとえば、frontendでアクセシビリティ抜けが続くならfrontend.instructionsへ、PRレビューで未実行テストの見逃しが続くならcopilot-instructionsの先頭へ足します。

導入初週の進め方

1. 1日目

   repo-wideを30行以内で作る。

2. 2日目

   PRレビューで読ませたいルールを先頭へ。

3. 3日目

   frontend/backendをpath別へ分離。

4. 5日目

   AGENTS.mdとの重複を削る。

5. 7日目

   失敗例から指示を1つだけ追加。

失敗したたびに巨大化させず、効く場所へ移します。

指示ファイルは、最初の1週間で小さく試します。

1日目: repo-wideを30行以内で作る

.github/copilot-instructions.mdを作り、標準コマンド、禁止操作、PR報告形式だけを書きます。最初から全領域を網羅しません。

2日目: PRレビュー向けルールを先頭へ置く

Copilot code reviewで見てほしい内容を先頭に置きます。認可、secretログ、テスト未実行、過大な差分など、レビューの優先順位を短く書きます。

3日目: frontend/backendを分ける

ReactやAPIの細かい規約を、path-specific instructionsへ分けます。全体指示から局所ルールを削ります。

5日目: AGENTS.mdとの重複を削る

複数agentで共有したい作業規約はAGENTS.mdへ置き、Copilotで確実に読ませたい短い要約だけを.github/copilot-instructions.mdへ残します。

7日目: 失敗例から1つだけ足す

「また同じ失敗をした」と言えるものだけ足します。なんとなく不安だから長文を追加する、という増やし方は避けます。

評価するログ

• Copilotが未実行テストを明記したか
• PRレビューが認可やsecretログに触れたか
• path-specificな規約が関係ない作業へ出ていないか
• 人間が指示ファイルを読んで保守できる長さか

FAQ

全部1ファイル

最初はよいが、長くなる前に分けます。

AGENTSだけ

Copilot全機能で同じ扱いとは見ません。

PRで効かない

base branchと4,000文字を確認します。

個人設定

チーム規約はrepoか組織へ置きます。

読まれないときは、ファイル名より対象機能とbranchを確認します。

.github/copilot-instructions.mdだけでよいですか

小さいrepoなら最初はそれで十分です。ただし、frontend、backend、docs、testsの規約が混ざり始めたら、.github/instructions/*.instructions.mdへ分けます。

AGENTS.mdだけに寄せてよいですか

複数agent向けの共通ルールはAGENTS.mdに置けます。ただし、GitHub Docsのsupport matrixでは、agent instructionsの対応範囲は機能ごとに違います。Copilot code reviewなどで確実に見たい短いルールは、Copilot向けファイルにも置きます。

PRレビューで指示が効いていない気がします

まず、base branchに指示ファイルが入っているか、custom instructions利用設定が有効か、重要ルールが先頭4,000文字以内かを見ます。次に、その機能がpath-specificやagent instructionsに対応しているかsupport matrixで確認します。

個人の好みはどこに置きますか

文体や説明の好みはpersonal instructionsで構いません。チームのテスト、セキュリティ、PR形式はrepoかorganizationへ置きます。

指示ファイルとPRテンプレートはどちらが大事ですか

両方です。PRテンプレートは人間とCIが見える形、指示ファイルはCopilotへ作業時に伝える形です。PR本文のSummary、Tests run、Not run、Risksは、AIエージェントPRテンプレートのように固定すると運用しやすくなります。

セキュリティ指示はどこまで書きますか

全体指示には「secret、token、cookie、private key、顧客情報、本番ログを出さない」と短く書きます。APIやDBの詳細な認可ルールはbackend.instructionsへ分けます。チーム導入の権限設計は、法人導入前のAIコーディング権限設計も合わせて確認すると整理しやすいです。

---

次に読むなら

参照した主な情報源

• GitHub Docs: About customizing GitHub Copilot responses

https://docs.github.com/en/copilot/concepts/prompting/response-customization

• GitHub Docs: Adding repository custom instructions for GitHub Copilot

https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions

• GitHub Docs: Support for different types of custom instructions

https://docs.github.com/en/copilot/reference/custom-instructions-support

• VS Code Docs: Use custom instructions in VS Code

https://code.visualstudio.com/docs/copilot/customization/custom-instructions

• GitHub Changelog: GitHub Copilot coding agent now supports .instructions.md custom instructions

GitHub Copilot coding agent now supports .instructions.md custom instructions

次に読むなら

更新履歴

1. 2026年5月31日

   GitHub Docs、VS Code Docs、GitHub Changelogを確認して初版を作成しました。

導入時には最新のsupport matrixと組織設定を確認してください。

• 2026年5月31日: GitHub Docs、VS Code Docs、GitHub Changelogを確認し、初版を公開しました。