なぜCopilot CLIの指示ファイルはエディタと異なる挙動をするのか
まずはリストから始めましょう。GitHubのCLI用カスタム指示ファイルに関するページでは、8種類の場所が挙げられています。ユーザーレベルでは、$HOME/.copilot/copilot-instructions.mdが「リポジトリを横断して適用されるユーザーレベルの指示」を保持し、$HOME/.copilot/instructions/**/*.instructions.mdが「モジュール化されたユーザーレベルの指示」を保持します。リポジトリ内には、 「リポジトリ全体の指示」用の.github/copilot-instructions.md、モジュール化された.github/instructions/**/*.instructions.mdファイル、および3つのエージェント指示ファイル（AGENTS.md、CLAUDE.md、GEMINI.md）があります。CLAUDE.mdについて、表には「Copilot CLIは.claude/CLAUDE.mdも使用します」と追記されています。
次に、探索場所についてです。「以下の表に記載がない限り、Copilot CLIは標準の場所（リポジトリのルート、現在の作業ディレクトリ、それらの間の中間ディレクトリ、および作業中のファイルのパスにネストされたディレクトリ）でリポジトリおよびエージェントの指示ファイルを検出します。」覚えておくべき例外が1つあります。モジュール化されたリポジトリ指示ファイルは「標準の場所で検出されますが、中間ディレクトリでは検出されません。」
そして、どのように結合されるかです。最も重要な一文がこれです。「適用可能なユーザーレベルおよびリポジトリの指示ファイルが複数存在する場合、Copilot CLIはそれらの指示を結合します。同一のユーザーレベルのcopilot-instructions.md、リポジトリ全体、およびエージェントの指示ファイルの重複コピーは削除されますが、これらのファイル間の一般的な優先順位は定義されていません。指示の競合は避けてください。」
これは、多くの人がCopilotの指示ファイルについて考えている方法とは異なります。エディタおよびgithub.comのドキュメントでは、個人用、パス固有、リポジトリ全体、エージェント、組織の指示の間の優先順位が説明されており、which Copilot instruction file wins, and whereにまとめられています。一方、CLIのページでは、重複排除を伴う結合と、競合を避けるという明示的な指示が記載されています。もしAGENTS.mdが1つのことを言い、CLAUDE.mdが別のことを言っている場合、CLIのドキュメントはどちらに従うかを教えてくれません。そのような状況を作らないようにと指示しているのです。
よくある誤ったアプローチ
ホームフォルダに個人用のAGENTS.mdを置く。 CLIがドキュメント化しているユーザーレベルの場所は、copilot-instructions.mdと$HOME/.copilot内のモジュール化された指示フォルダです。それらの隣に置かれたAGENTS.mdは、ドキュメント化されたリストには含まれていません。追加のAGENTS.mdファイルを指定するドキュメント化されたルートは異なり、ステップ2で説明します。
セッションの途中で指示ファイルを編集し、その変更が反映されることを期待する。 GitHubのページには、「カスタム指示ファイルに加えた変更は、アクティブなCLIセッションですぐには利用できません」とあります。セッションを終了して再開するか、新しいセッションを開始する必要があります。これが、編集したAGENTS.mdが無視されているように見える最も一般的な理由です。
ホームフォルダから共有ファイルを参照する。 CLIは.github/copilot-instructions.md、AGENTS.md、CLAUDE.mdでの@参照をサポートしていますが、「絶対パスおよび~/で始まるパスはロードされません。」~/notes/conventions.mdを指す行は何も行いません。
GEMINI.mdやモジュール化されたファイルで@参照を使用する。 「ファイル参照はGEMINI.mdや*.instructions.mdファイルでは展開されません。」参照はそのままのテキストとして残ります。
すべてのパッケージにモジュール化された指示フォルダを置く。 モノレポでは、各レベルに独自の.github/instructionsフォルダを持たせるのが自然に感じられます。しかし、パッケージ内でセッションを開始すると、リポジトリのルートとそのパッケージの間にあるフォルダは中間ディレクトリになります。GitHubの表によると、モジュール化されたリポジトリ指示は標準の場所で検出されますが「中間ディレクトリでは検出されない」ため、AGENTS.mdのルールよりも狭くなります。これらの中間フォルダにあるモジュール化フォルダはスキップされますが、同じフォルダにあるAGENTS.mdは検出されます。
3つのエージェントファイルを手動で同期させ、うまくいくことを祈る。 異なるツールが異なるファイルを読み込むため、多くのリポジトリにはAGENTS.md、CLAUDE.md、GEMINI.mdが含まれています。CLIはこれら3つすべてを読み込みます。同一のコピーは削除されますが、わずかに異なるコピーはすべて含まれてしまいます。この乖離の問題は、reconciling conflicting CLAUDE.md layersで説明されているものと同じです。
解決策：CLIがロードしたものを確認し、各事実に1つの場所を与え、個人用ファイルをCLIが探索する場所に配置する
目標は、すべての事実が1回だけ現れ、すべてのファイルがドキュメント化された場所にあり、セッションが実際に何をロードしたかを確認できる指示セットを構築することです。
ステップ 1: このセッションでCLIが何を検出したかを確認する
GitHubはまさにこのためのコマンドをドキュメント化しています。「/instructionsコマンドを使用して、現在のセッションで検出された指示ファイルを表示し、個々のファイルを有効または無効にします。」
普段作業しているディレクトリでこれを実行し、リストを書き留めてください。次に、サブディレクトリから再度実行します。検出はリポジトリのルート、作業ディレクトリ、およびそれらの間のディレクトリをカバーするため、ツリーの深い場所で開始されたセッションは、ルートでのセッションでは検出されないファイルを拾うことがあります。パス固有のファイルは別の変数をもたらします。これらは「applyToの値がCopilot CLIが処理しているファイルと一致する場合にのみ含まれます。」
リストを期待していたものと比較してください。通常、3つのものが現れます。誰も覚えていなかったCLAUDE.mdまたは.claude/CLAUDE.md、サブフォルダにネストされたAGENTS.md、そして誰かが以前に無効にしたファイルです。GitHubは、無効にされたファイルは除外されたままであることを明示しています。「/instructionsを使用して無効にした指示ファイルは含まれません。」
セッション中にこれらのファイルを編集した場合、リストはセッション開始時の状態を反映していることに注意してください。結論を出す前に、終了して再開するか、新しいセッションを開始してください。
ステップ 2: 各事実に1つの場所を与え、個人用ファイルを正しく配置する
次に、各ファイルの用途を決めます。複数のエージェントで使用されるリポジトリの実用的な分割例は以下の通りです。
AGENTS.mdは、ビルドやテストのコマンド、規約、制約など、共有のツールに依存しない事実を保持します。これは、Copilot CLIを含むすべてのエージェントが読み込むファイルです。
.github/copilot-instructions.mdは、Copilotに特有の指示がある場合にそれを保持します。
CLAUDE.mdとGEMINI.mdは、それらのツールに特有のものだけを保持するか、AGENTS.mdを指すようにします。CLAUDE.mdでは@参照が展開されますが、「GEMINI.mdでは展開されない」ため、ポインタパターンは一方でのみ機能することに注意してください。Claude Codeが同じファイルのペアをどのように処理するかは、Claude Code's AGENTS.md defaultで説明されています。
重複する事実は、その本拠地以外のすべての場所から削除してください。CLIは同一のコピーを削除しますが、ほぼ同一のコピーこそが矛盾を引き起こす原因になります。
個人用の指示には、ドキュメント化されたユーザーレベルのファイルである$HOME/.copilot/copilot-instructions.md、または$HOME/.copilot/instructions/配下のモジュール化されたファイルを使用します。すべてのリポジトリに認識させたい個人用のAGENTS.mdを保持する場合、GitHubは追加ディレクトリ用の環境変数をドキュメント化しています。「COPILOT_CUSTOM_INSTRUCTIONS_DIRSにリストされたディレクトリ」は「追加のAGENTS.mdおよび*.instructions.mdファイル」を提供します。「複数のディレクトリはカンマで区切ります。」個人用のAGENTS.mdを独自のディレクトリに置き、そのディレクトリをリストに指定してください。
デフォルト以外のCopilotホームを使用する場合、「COPILOT_HOME環境変数を設定すると、Copilot CLIはユーザーレベルの指示場所の両方に、$HOME/.copilotではなくそのディレクトリを使用します」という点に注意してください。
ステップ 3: 新しいセッションを開始して結果を確認する
終了し、新しいセッションを開始して、再びinstructionsコマンドを実行します。リストは計画と一致しているはずです。1つの共有エージェントファイル、ドキュメント化された場所からの個人用指示、そして意図しないものは何も含まれていない状態です。
次に、挙動をテストします。現在1つのファイルだけに存在する事実に依存する質問をCLIに投げかけてみてください。正しい回答が得られれば、連携は機能しています。そうでない場合は、狭いapplyToパターンを持つパス固有のファイルが関与していないか確認してください。これらは一致するファイルが処理されている場合にのみ適用されるためです。
また、実際に最もよく作業するサブディレクトリからチェック全体を繰り返す価値もあります。パッケージフォルダにネストされたAGENTS.mdを持つモノレポでは、そのパッケージ内で開始されたセッションは、ルートで開始されたセッションとは異なる指示セットを取得し、検出ルールに従えばどちらも正解です。自分がどちらのセッションにいるかを知ることで、「昨日はルールに従っていたのに」という報告のほとんどを説明できます。
誰かが新しいエージェントの指示ファイルを追加するたびに、このチェックを繰り返してください。リポジトリにはこれらが静かに蓄積され、CLIは指示されなくても新しいファイルをそれぞれ読み込みます。
MemoryLakeでのセットアップ
ステップ2の整理により、どのエージェントが読み込むかに関係なく、プロジェクトにとって真実である事実の短いリストが作成されます。MemoryLakeは、特定のツールが今年どのファイル名を読み込むかに依存しないように、そのリストを保持する場所です。
エントリーはご自身で、ご自身の言葉で記述します。.copilotフォルダ、リポジトリの指示ファイル、またはベンダーのストアから何かが読み込まれたり、書き込まれたり、削除されたりすることはありません。
ステップ 1: APIキーを作成する
サインインし、ダッシュボードからキーを生成します。このキーにより、エージェントがAGENTS.mdを読み込むか、CLAUDE.mdを読み込むか、あるいはどちらも読み込まないかに関わらず、記述したエントリーを読み込むことができるようになります。
ステップ 2: 最初のメモリをアップロードする
ステップ2の共有された事実を、各制約が存在する理由とともに、1エントリーずつ追加します。理由を記載しておくことで、次の人がそのルールがまだ適用されるかどうかを判断できるようになります。
ステップ 3: AIとエージェントを接続する
エージェントをワークスペースに向けます。これにより、CLI、エディタ、およびこれらの指示ファイルを一切読み込まないツールでも、同じ事実を利用できるようになります。
実務における変化
第一の変化は、「AGENTS.mdが読み込まれない」という問題が診断可能になることです。ほとんどの場合、セッションの途中でファイルが編集されたか、ドキュメント化された場所以外にあるか、あるいは無効化されているかのいずれかです。instructionsコマンドを実行すれば、どれが原因であるかがわかります。
第二に、競合が静かに発生することがなくなります。CLIのドキュメントには「一般的な優先順位は定義されていない」とあるため、2つのファイル間の矛盾は、調べればわかるようなルールによって解決されることはありません。各事実を1つの場所に保持することで、この疑問自体が解消されます。
第三に、個人用とチーム用の指示が明確に分離されます。個人の好みはホームフォルダまたはリストされたディレクトリに配置し、チームの事実はリポジトリに配置します。これは、リポジトリスコープのメモリと個人用の指示が異なる役割を果たすsetting up Copilot memory in VS Codeの背景にある分割と同じです。
第四に、コンテキストが軽量に保たれます。CLIが検出したすべてのファイルは、動作のベースとなるものに結合されます。ファイルが少なく明確であることは、重複が少ないことを意味します。これは、how Copilot assembles context per requestの背景にある懸念と同じです。
Copilot CLI指示ファイルのベストプラクティス
挙動をデバッグする前に、instructionsコマンドを実行する。 現在のセッションで検出されたファイルが表示されます。これが唯一重要なリストです。
編集後は再起動する。 指示の変更は、セッションを再開するか、新しいセッションを開始したときに有効になります。
各事実に1つの場所を維持する。 同一のコピーは削除されますが、ほぼ同一のコピーはすべて含まれてしまい、矛盾の原因になります。
ドキュメント化されたユーザーレベルの場所を使用する。 個人用のAGENTS.mdファイルには、$HOME/.copilot/copilot-instructions.md、モジュール化された指示フォルダ、またはCOPILOT_CUSTOM_INSTRUCTIONS_DIRSにリストされたディレクトリを使用します。
ホームフォルダの参照を避ける。 ~/で始まるパスはロードされず、GEMINI.mdやモジュール化されたファイルでは参照が展開されません。
新しいエージェントファイルをCopilotのコンテキストへの変更として扱う。 別のツール用に追加されたCLAUDE.mdも、CLIによって読み込まれます。指示をツール間で移動する場合は、migrating CLAUDE.md to Copilotでマッピングを説明しており、why Copilot forgets codebase contextでは指示ファイルに保持できないものについて説明しています。
結論
Copilot CLIの指示の処理は寛大です。独自ファイル、他のエージェントのファイル、個人用ファイル、およびリストしたディレクトリを、リポジトリのルートから編集中のファイルに至るまで読み込みます。GitHubはこれらすべてを明確にドキュメント化しています。
同様に明確にドキュメント化されているのは、CLIが優先順位をつけるのではなく結合するということです。CLIは「これらのファイル間の一般的な優先順位を定義していない」ため、競合を避けるよう求めています。これにより、一貫性を保つ責任はファイルの整理方法に委ねられます。
セッションが何を検出したかを確認し、各事実に1つの場所を与え、個人用ファイルをCLIが探索する場所に配置し、編集後は再起動してください。共有された事実をファイル名の慣例よりも長生きする場所に保管しておけば、リポジトリに次のエージェントを追加するときに、前のエージェントの整理に追われることはなくなります。