GitHub Copilotがcopilot-instructions.mdを無視する原因｜配置場所と適用範囲を確認

GitHub Copilotにプロジェクト固有のルールを適用するため、copilot-instructions.mdを作成したものの、Copilot Chatがルールを無視しているように見えることがあります。

たとえば、

このプロジェクトではnpmではなくpnpmを使用する。

ReactではClass Componentを作成しない。

新しいAPIを追加した場合はVitestでテストを書く。

と書いているのに、Copilotがnpm installを提案したり、Class Componentを生成したりするケースです。

この場合、最初に確認したいのは指示の文章ではありません。

GitHub CopilotのRepository-wide Custom Instructionsには決められた配置場所があり、基本となるファイルは.github/copilot-instructions.mdです。GitHub公式ドキュメントでも、Repository全体へ適用するCustom InstructionsはRepository Root直下の.githubディレクトリにcopilot-instructions.mdを置くよう定められています。

さらに現在のGitHub CopilotにはRepository-wide Instructionsだけでなく、特定Pathだけに適用する*.instructions.mdや、AI Agent向けのAGENTS.mdなど複数のInstruction機能があります。どのファイルが使われるかは、VS Code、GitHub.com、Copilot Code Review、Copilot Cloud Agent、Copilot CLIなど利用している機能によっても異なります。

この記事では、GitHub Copilotがcopilot-instructions.mdを読まない、または無視しているように見えるときに確認したい配置場所、Workspace Root、適用範囲、VS Code設定、Path-specific Instructions、AGENTS.mdとの違いを解説します。copilot-instructions.md自体の基本的な書き方はGitHub Copilot完全ガイドで解説しているため、この記事では「なぜ無視されているように見えるのか」という切り分けにしぼります。

正しい配置場所は.github/copilot-instructions.md

Repository全体へ適用する場合、基本構成は次のようになります。

my-project/
├── .github/
│   └── copilot-instructions.md
├── package.json
└── src/

ファイル名はcopilot-instructions.mdですが、Repository Rootへそのまま置くのではありません。次の配置ではありません。

my-project/
├── copilot-instructions.md
├── package.json
└── src/

GitHub公式ドキュメントでは、.github/copilot-instructions.mdという場所がRepository-wide Instructionsの標準位置として定義されています。「copilot-instructions.mdを作ったのに読まれない」という場合は、まず.github以下にあるか確認してください。

.githubディレクトリの場所にも注意する

.githubという名前が合っていても、Repository Rootからずれた場所に作ると期待どおり認識されない可能性があります。正常なのは、

my-project/
├── .git/
├── .github/
│   └── copilot-instructions.md
└── src/

です。たとえば誤って、

my-project/
├── src/
│   └── .github/
│       └── copilot-instructions.md
└── package.json

としている場合、Repository-wide Instructionsの標準配置ではありません。GitHub公式ドキュメントでも「RepositoryのRootに.github/copilot-instructions.mdを作成する」と説明されています。ファイル名だけでなく、どの.githubディレクトリなのかまで確認してください。

VS CodeではWorkspace Rootも重要

Repository Rootへ正しく置いているのにVS Codeでだけ認識されない場合は、VS CodeでどのDirectoryをWorkspaceとして開いているか確認します。

たとえばRepositoryが次の構造だとします。

my-project/
├── .git/
├── .github/
│   └── copilot-instructions.md
└── packages/
    └── frontend/
        └── src/

通常はmy-project/をVS Codeで開けば.github/copilot-instructions.mdをWorkspace Instructionsとして認識できます。しかしmy-project/packages/frontend/だけをVS Codeで開いている場合、.githubは現在のWorkspace Rootより上にあります。

現在のVS Codeには親RepositoryからCustomizationsを探す機能がありますが、chat.useCustomizationsInParentRepositoriesはデフォルトで無効です。親RepositoryのCustom Instructionsを発見するには、この設定を有効にし、親RepositoryをTrusted Folderとして扱う必要があります。

つまり、Repositoryには正しくcopilot-instructions.mdがあるのに、VS CodeではRepository内のサブディレクトリだけを開いている、という状態が「CopilotがInstructionsを無視する」原因になることがあります。

まずReferencesで読み込まれているか確認する

copilot-instructions.mdが効いているかを、生成されたコードだけで判断する必要はありません。

VS CodeのCopilot Chatでは、ResponseのReferencesから、そのRequestに利用されたInstruction Fileを確認できます。GitHub公式ドキュメントでも、Custom Instructionsがモデルへ送られた場合、ResponseのReferencesに.github/copilot-instructions.mdが表示されると説明されています。

つまり、「ルールどおりのコードにならなかった」だけでは、「Instruction File自体が読み込まれなかった」のか、「読み込まれたがモデルが指示に完全には従わなかった」のか判断できません。最初にReferencesを確認し、この2つを分けて考えることが重要です。

VS CodeのDiagnosticsからInstructionの読み込み状況を確認できる

さらに詳しく調べたい場合は、VS CodeのChat Customization Diagnosticsを利用できます。Chat ViewのContext MenuからDiagnosticsを開きます。

ここでは、どのInstruction Fileが発見されたか、読み込みエラーが発生していないか、Instructionが現在のRequestへ適用されたかなどを確認できます。

たとえばDiagnostics上でファイル自体が見つからないなら、配置場所やWorkspace設定を調べます。ファイルは見つかっているのに適用されていないなら、applyToなど適用条件を確認します。読み込まれているなら、今度はInstructions同士の競合や指示内容を疑えます。

VS Codeではcopilot-instructions.mdの利用設定も確認する

VS Codeでは.github/copilot-instructions.mdをChat Requestへ自動追加する設定があります。現在の設定名はgithub.copilot.chat.codeGeneration.useInstructionFilesです。デフォルト値はtrueです。

つまり通常は設定しなくても有効になっています。しかし以前の設定変更などで、

{
  "github.copilot.chat.codeGeneration.useInstructionFiles": false
}

となっていれば、.github/copilot-instructions.mdを作成していてもCopilot Chatへ自動追加されません。「以前は動いていたのに急に効かなくなった」という場合は、User SettingsだけでなくWorkspace Settingsにも同じ設定がないか確認するとよいでしょう。

copilot-instructions.mdはすべてのCopilot機能で同じように使われるわけではない

GitHub Copilotには現在、Copilot Chat、Cloud Agent、Code Review、CLIなど複数の機能があります。Custom Instructionsの対応範囲は機能によって異なります。

.github/copilot-instructions.mdは幅広く対応していますが、AGENTS.md、CLAUDE.md、Path-specific Instructionsなどは利用できる機能が異なります。

GitHubの現在のSupport Matrixでは、GitHub.comのCopilot ChatはRepository-wide Instructionsを利用できます。Copilot Cloud AgentではRepository-wide Instructionsに加えてPath-specific InstructionsやAGENTS.md、CLAUDE.md、GEMINI.mdなども利用できます。VS CodeのCopilot ChatではRepository-wide Instructions、Path-specific Instructions、AGENTS.mdがサポートされています。

そのため、「別のCopilot機能では効いた」からといって、「すべてのCopilot機能で同じInstruction Fileが使われる」とは限りません。

Inline Completionだけで効いているか判断しない

copilot-instructions.mdはGitHubのドキュメント上、Copilot ChatやCloud Agent、Code ReviewなどCustom Instructionsに対応する機能について明示されています。一方、通常のInline Code CompletionはこのCustom Instructions Support Matrixとは別の機能です。

そのため、「エディタでTab補完されたコードがルールに従わなかった」という結果だけを見て、「copilot-instructions.mdが読み込まれていない」と判断するのは避けたほうがよいでしょう。

動作確認にはCopilot Chatで明確なタスクを依頼し、ResponseのReferencesにcopilot-instructions.mdが含まれているか確認する方法が分かりやすくなります。

Pathごとにルールを変えたいならcopilot-instructions.mdへ全部書かない

大規模なRepositoryでは、frontendではReactのルール、backendではLaravelのルール、testsではテスト用のルールといったようにDirectoryごとに異なる規約があることがあります。

これらをすべてRepository-wideの.github/copilot-instructions.mdへ書くこともできますが、現在のGitHub CopilotにはPath-specific Instructionsがあります。

たとえば、

.github/
├── copilot-instructions.md
└── instructions/
    ├── frontend.instructions.md
    └── backend.instructions.md

という構成にできます。Path-specific Instructionsは.github/instructions/**/*.instructions.mdに配置します。

Path-specific InstructionsではapplyToを確認する

たとえばReactファイルだけへ適用するなら、次のようにします。

---
applyTo: "src/**/*.tsx"
---

# React Rules

Use function components.

Use hooks instead of class components.

Use Vitest for unit tests.

applyToに一致するファイルをCopilotが扱う場合だけ、このInstructionsが自動的に適用されます。つまりsrc/components/Button.tsxなら適用されますが、scripts/build.jsでは適用されません。

「instructions.mdを作ったのに無視される」という場合は、ファイル内容より先にapplyToが対象File Pathと一致しているか確認してください。

*.instructions.mdはファイル名だけでは適用対象が決まらない

たとえばreact.instructions.mdという名前だからといって、React Fileへ自動的に適用されるわけではありません。適用条件として重要なのはFrontmatterのapplyToです。

VS Codeの現在の仕様では、*.instructions.mdにapplyToが設定されていない場合、そのInstructionは自動では適用されません。つまり、

# React Rules

Use function components.

だけではなく、

---
applyTo: "**/*.tsx"
---

# React Rules

Use function components.

のように対象を指定します。VS CodeにはTask DescriptionなどからInstructionをOn-demandで選択する仕組みもありますが、特定Fileへ確実に自動適用したい場合はapplyToを明示したほうが分かりやすくなります。

applyToのGlobが間違っていないか確認する

applyToを書いていても、Globが実際のRepository構成に合っていないことがあります。

たとえば、

---
applyTo: "src/*.ts"
---

とした場合、src/index.tsには一致しても、src/api/user.tsのような下位Directoryまで想定どおり一致するか確認が必要です。下位Directoryを含めたいなら、

---
applyTo: "src/**/*.ts"
---

のようなPatternを検討します。VS CodeのCustom InstructionsではapplyToはWorkspace Rootを基準にしたGlob Patternとして扱われます。InstructionsがDiagnosticsでは発見されているのにResponseへ適用されない場合は、このPatternを確認してください。

copilot-instructions.mdとPath-specific Instructionsは両方使われる

Path-specific Instructionsを作ったからといって、Repository-wide Instructionsが無効になるわけではありません。

たとえば.github/copilot-instructions.mdに「Use pnpm for package management.」と書き、.github/instructions/react.instructions.mdに「Use function components.」と書いたとします。Copilotがsrc/components/Button.tsxを扱う場合、両方のInstructionsが利用されます。

GitHub公式ドキュメントでも、対象Pathに一致するPath-specific InstructionsとRepository-wide Instructionsが存在する場合、両方が使用されると説明されています。したがって両者へ矛盾するルールを書かないことが重要です。

複数のInstructionsが競合していないか確認する

たとえばRepository-wide Instructionsに「Use Jest for all JavaScript tests.」と書き、Path-specific Instructionsに「Use Vitest for TypeScript tests.」と書いている場合、対象によっては両方がモデルへ渡されます。

GitHubの現在の優先関係では、Personal Instructionsが最も高く、その次にRepository Custom Instructions、Organization Instructionsとなります。Repository Instructions内部では、Path-specific Instructions、Repository-wideのcopilot-instructions.md、Agent Instructionsという順序が示されています。

ただし、優先順位へ頼って相反するルールを大量に書くより、最初から競合をなくすほうが安全です。GitHubもCustom Instructions同士のConflictを可能な限り避けることを推奨しています。

AGENTS.mdとcopilot-instructions.mdは用途が少し違う

現在のGitHub CopilotではAGENTS.mdも利用できます。copilot-instructions.mdはCopilot専用のRepository-wide Instructionsです。一方AGENTS.mdは、複数のAI Coding Agent間で共有する常設ルールとして利用しやすい形式です。

GitHubのCustomization Cheat Sheetでも、Repository-wideのCopilot固有ルールには.github/copilot-instructions.mdを使い、複数Agentへ共有するStanding RulesにはAGENTS.mdを使う整理が示されています。

たとえば「Copilot Code ReviewではSecurity問題を優先して指摘する。」という内容ならcopilot-instructions.mdが自然です。一方「Package Managerはpnpm。テストはVitest。」といったプロジェクト全体のAI共通ルールならAGENTS.mdへまとめる方法もあります。

CLAUDE.mdを置けばCopilot Chatでも必ず読まれるわけではない

Claude Codeを併用しているRepositoryではCLAUDE.mdがすでに存在することがあります。

現在のGitHub Copilotは一部機能でCLAUDE.mdにも対応していますが、すべてのCopilot機能が同じ対応をしているわけではありません。GitHubのSupport Matrixでは、Copilot Cloud AgentはAGENTS.md、CLAUDE.md、GEMINI.mdをAgent Instructionsとして利用できます。一方、VS CodeのCopilot ChatについてGitHub側のSupport MatrixでAgent Instructionsとして明記されているのはAGENTS.mdです。

VS Code自体は現在、Claude互換のInstructionsとしてCLAUDE.mdも扱う機能を持っていますが、Copilot各機能での対応は同一ではありません。そのためCopilot専用のRepository-wide Ruleを確実に適用したいなら.github/copilot-instructions.mdを基本にするのが分かりやすいでしょう。

Copilot CLIではさらにUser-level Instructionsがある

Copilot CLIを使っている場合は、IDEとは別にUser-level Custom Instructionsも利用できます。現在のCopilot CLIでは~/.copilot/copilot-instructions.mdをすべてのRepositoryへ適用する個人用Instructionsとして利用できます。さらに~/.copilot/instructions/**/*.instructions.mdにも個人用のInstruction Fileを置けます。

そのためCLIだけ挙動が違う場合は、Repository側の.github/copilot-instructions.mdだけではなく~/.copilot/copilot-instructions.mdも確認してください。Copilot CLIでは複数のInstruction Fileが組み合わされるため、User側とRepository側で矛盾する指示を書いていると意図しない挙動になる可能性があります。

Copilot CLIなら/instructionsで読み込み状態を確認できる

Copilot CLIでは/instructionsコマンドを利用できます。現在のSessionで発見されたInstruction Fileを表示し、個別に有効・無効を切り替えられます。VS CodeでいうReferencesやCustomization Diagnosticsに近い切り分けができます。

CLIだけcopilot-instructions.mdが効かない場合は、ファイルを何度も修正する前に/instructionsで発見されているか確認してください。

Instruction Fileを保存すれば通常はすぐに利用できる

GitHub公式ドキュメントでは、Custom Instructionsはファイルを保存すると利用可能になり、その後のCopilot Requestへ自動的に追加されます。

そのため、「VS Codeを何回再起動しても反映されない」という場合は、再起動不足より、配置場所、Workspace Root、Instruction利用設定、適用範囲を疑うほうがよいでしょう。もちろんExtensionやVS Code自体を長期間更新していない場合には、現在のInstruction機能へ対応していない可能性があるため、Version確認も必要です。

指示が長すぎると「無視された」ように見えることがある

copilot-instructions.mdへプロジェクトの仕様書全体をコピーするのはおすすめできません。GitHubはCustom Instructionsについて、短く自己完結したStatementとして書く方法を推奨しています。

たとえば「Clean codeを書いてください。」では曖昧です。次のように具体的にします。

Use pnpm instead of npm or yarn.

Use TypeScript for all new source files.

Do not use the any type.

Use Vitest for unit tests.

Run pnpm test after changing business logic.

モデルが実行可能な形まで具体化すると、「読んではいるが解釈が違った」というケースを減らせます。

FormatterやLinterで強制できるものをInstructionsだけに任せない

たとえば「Use single quotes. Indent with 2 spaces. Do not leave trailing whitespace.」のような機械的ルールを、すべてcopilot-instructions.mdだけで制御する必要はありません。ESLint、Prettier、Biomeなどで強制できるものはTool側へ任せたほうが確実です。

Custom Instructionsは、「既存のRepository Patternを使う」「新しいDependencyを勝手に増やさない」「API変更時は互換性を維持する」といった、単純なFormatterでは表現しにくいProject Contextに向いています。GitHubもInstructionsについて、モデルへCodebase-wide ContextやTeam Standardを与えるための仕組みとして位置付けています。

「絶対に実行禁止」のSecurity機構として使わない

Custom Instructionsは自然言語でモデルへ与える指示です。そのため、「Never modify production configuration.」と書いたからといって、それ自体が技術的なAccess Controlになるわけではありません。

GitHubもAIの非決定的性質によって、Custom Instructionsが毎回まったく同じ形で守られるとは限らないと説明しています。本当に書き換えてはいけないFileや実行してはいけない処理があるなら、Repository Permission、CI、Branch Protection、Tool Permissionなど別の仕組みでも保護する必要があります。「copilot-instructions.mdへ禁止と書いたので安全」という設計にはしないほうがよいでしょう。

Code Reviewで使う場合は設定も確認する

GitHub Copilot Code ReviewでもRepository-wide Custom Instructionsを利用できます。ただしRepository SettingsからCustom InstructionsをCode Reviewに利用するか切り替えられます。

GitHub公式ドキュメントでは、Repository Settings → Copilot → Code reviewからCustom Instructions利用のOn/Offを変更できると案内されています。

つまり、「VS CodeのCopilot Chatでは効く」のに「GitHub上のCopilot Code Reviewでは効かない」場合は、Instruction FileそのものではなくCode Review側の設定を確認する必要があります。

環境によって対応しているInstruction Typeが違う

Custom Instructions関連の記事を検索すると、copilot-instructions.md、.instructions.md、AGENTS.md、CLAUDE.md、GEMINI.mdなどさまざまな形式が見つかります。しかし「GitHub Copilotが対応している」というだけでは不十分です。

重要なのは、どのEnvironmentのどのCopilot機能でどのInstruction Typeが対応しているかです。現在のGitHub公式Support Matrixでも、GitHub.com、VS Code、Visual Studio、JetBrains、Eclipse、Xcode、Copilot CLIごとに対応状況が分けられています。別の環境向けの記事から設定をコピーした場合は、現在使っているCopilot機能でも対応しているか確認してください。

MonorepoではRepository-wide Instructionsを巨大化させない

Monorepoではapps/web、apps/api、packages/ui、packages/databaseのように複数の技術領域が1Repositoryへ入ることがあります。

すべての規約を.github/copilot-instructions.mdへ書くと、Webだけを変更するときにもDatabase用のルールが一緒にモデルへ渡されます。この場合はRepository全体で共通する内容だけをcopilot-instructions.mdへ残します。

Web固有のルールは.github/instructions/web.instructions.mdへ、API用なら.github/instructions/api.instructions.mdへ分けます。GitHubもPath-specific Instructionsを使う理由として、特定Directoryだけに必要な情報でRepository-wide Instructionsを過負荷にしないことを挙げています。

VS Codeでは複数のInstructionが順不同で結合される場合もある

VS Codeでは複数のInstruction Fileが適用される場合、それらがChat Contextへ組み合わされます。VS Code公式ドキュメントでは、複数Instruction Fileについて特定の順序が保証されない場合があるため、互いに依存した指示を書かないほうが安全だとされています。

たとえば一方のFileで「Rule Aを参照すること。」とだけ書き、別Fileで初めてRule Aを定義するような構造より、それぞれのInstructionを自己完結させます。特にPath-specific Instructionsを細かく分割する場合は、読み込み順に依存しない文章にすると安定します。

Personal Instructionsと競合していないか確認する

GitHub.comのCopilot ChatにはPersonal Instructionsもあります。Repository Instructionsに「Responses must be concise.」と書いていて、Personal Instructions側に別の方針があれば、両方がモデルへ提供される可能性があります。

現在のGitHubの優先関係ではPersonal InstructionsがRepository Instructionsより上です。Repository側を何度書き換えても特定の挙動だけ変わらない場合は、Personal Instructionsなど別Scopeから矛盾する指定が入っていないか確認してください。

Organization Instructionsが適用されている場合もある

OrganizationでGitHub Copilotを利用している場合はOrganization Instructionsが適用されるケースもあります。現在のGitHubでは、Personal、Repository、Organizationという複数ScopeのInstructionsを組み合わせられます。優先度はPersonal、Repository、Organizationの順です。

会社のRepositoryだけCopilotの動作が違う場合は、Repository内の.github/copilot-instructions.mdだけでなくOrganization側のInstructionsも影響している可能性があります。

効いているか確認するなら検証しやすいルールを一時的に書く

Instruction Fileが読み込まれているか動作から検証したい場合は、曖昧なルールより明確なルールを使います。

たとえば一時的に、

When creating a new JavaScript file, always use the .mjs extension.

のような分かりやすいInstructionを追加します。その状態でCopilot Chatへ「新しいユーティリティファイルを作成してください」と依頼します。その際、Referencesにもcopilot-instructions.mdが含まれているか確認します。

Referenceがなくルールにも従わないなら、読み込み設定を優先して調べます。Referenceはあるのに従わないなら、Instructionsの競合や指示内容を調べます。検証後はテスト用ルールを削除してください。

GitHub Copilotのcopilot-instructions.mdに関するよくある質問

まず「読み込まれない」と「従わない」を分ける

GitHub CopilotのCustom Instructionsトラブルで最も重要なのは、「ファイルが読み込まれていない」ケースと、「ファイルは読み込まれたが、期待した行動にならなかった」ケースを区別することです。

前者なら、文章をどれだけ修正しても解決しません。.github/copilot-instructions.mdの配置、Workspace Root、親RepositoryのDiscovery設定、github.copilot.chat.codeGeneration.useInstructionFilesなどを確認します。

後者なら、Instructions同士のConflict、文章の曖昧さ、適用範囲、モデルの非決定性などを調べます。VS CodeならResponseのReferencesとCustomization Diagnosticsを利用すると、どちらの問題なのか判断しやすくなります。

GitHub Copilotがcopilot-instructions.mdを無視するときはReferencesから確認する

GitHub Copilotがcopilot-instructions.mdを読まないように見える場合、最初に確認したいのは配置場所です。

Repository-wide Custom Instructionsは.github/copilot-instructions.mdへ置きます。VS Codeでは、基本的にWorkspace Rootにある.github/copilot-instructions.mdが自動的にChat Requestへ追加されます。

RepositoryのサブDirectoryだけをWorkspaceとして開いている場合は、親RepositoryにあるInstructionsが自動Discoveryされない可能性があります。現在のVS Codeでは親RepositoryのCustomization Discoveryを制御するchat.useCustomizationsInParentRepositoriesがデフォルトで無効です。

配置が正しければ、Copilot ChatのResponseにあるReferencesを確認します。そこに.github/copilot-instructions.mdが表示されていれば、少なくともそのRequestではInstruction Fileがモデルへ渡されています。

特定Directoryだけのルールなら、Repository-wide Fileへすべて詰め込むのではなく、.github/instructions/*.instructions.mdへ分け、applyToで対象Pathを指定します。そしてAGENTS.md、CLAUDE.md、Personal Instructions、Organization Instructionsなども利用している場合は、別のInstructionsとの競合も確認してください。

Custom InstructionsはSecurity PolicyやFormatterの代わりではなく、モデルへProject Contextを与える仕組みです。GitHub自身もAIの非決定的な性質により、Instructionsが毎回完全に同じ形で守られるとは限らないと説明しています。

GitHub Copilotのcopilot-instructions.mdトラブルでは、「ルールを無視された」と判断する前に、まずReferencesやDiagnosticsを使って、そのRequestにInstruction Fileが実際に読み込まれていたかを確認することが最も効率的な切り分け方法です。