Visual Studio 2026 で GitHub Copilot 用の設計ドキュメントを整備するときの注意点

2026/01/01 追記
条件は不明ですが、ここで書いているソリューションエクスプローラーにあるファイルしか参照できないという動きをするプロジェクトとしないプロジェクトがあることがわかりました。

詳細は以下に書いているため、そちらを参照してください。
https://zenn.dev/microsoft/articles/github-copilot-vs2026-2

本文

皆さん GitHub Copilot を使っていますか？
私は、Visual Studio Code の方の GitHub Copilot を使うことが多いのですが、今回は Visual Studio 2026 での GitHub Copilot を使う上で気を付けないといけないことに気付いたのでメモしておきます。

GitHub Copilot に活躍してもらうコツ

そもそも GitHub Copilot のような生成 AI を使ってコードを生成してもらうときには、100% の Vibe Coding を除いて、ある程度人間が思い描いている設計・実装に沿ったコードを書いてもらわないといけません。そうしないと、1 つのプロダクトで 10 人のアーキテクトが個別に設計したようなコードが入り混じって生成されてしまい、コードベースがカオスになってしまいます。

このような状態を防ぐためには GitHub Copilot に対して、このコードベースではこういう設計方針でコードを書いてほしい、ということを伝える必要があります。GitHub Copilot では .github/copilot-instructions.md というファイルをリポジトリに追加して、そこに設計方針を記載することで、リポジトリ全体での設計方針を伝えることができます。ここは Visual Studio でも Visual Studio Code でも同じです。

しかし、全てのルールを .github/copilot-instructions.md に書いてしまうとトークンの無駄遣いになってしまいますし、なによりノイズが多くなってしまいます。例えば画面の実装をしているのにデータベースアクセスについてのガイドも書いてあったりすると、画面実装のコードを生成してもらうときにノイズになってしまいます。そのため、AI 用の設計ドキュメントは別のフォルダーに用意しておき、.github/copilot-instructions.md では、そのドキュメントが何処にあって、どういうときにそれを読むべきかということを伝えるのが良いです。
最近だと Skills を使って、実装するものに応じて適切な SKILL.md を読み込むようにするのも良いでしょうが、こちらはまだ Visual Studio 2026 ではサポートされていないですし、Visual Studio Code でも Insider でしか使えないので、今回は触れません。将来的には Skills を使うのが良いと思います。

Visual Studio 2026 での注意点

このような方針で AI が作業をするために必要なドキュメントを整備しておくようなことをやっているのですが Visual Studio 2026 では、私が試した限り以下のような制限があり、うまく動きませんでした。

Agent mode ではソリューションエクスプローラーにあるファイルしか参照できない

例えば .github/copilot-instructions.md に以下のような内容を書いておいても、ちゃんと動いてくれません。

copilot-instructions.md

「にゃーん」と言われたら以下のドキュメントを見て答えてください。
- docs/nya-n.md

nya-n.md は以下のような内容にしました。

docs/nya-n.md

実は「犬」が好きなので「わんわん」と答えてあげてください。

これを Visual Studio Code の Agent モードで試すと、以下のようにちゃんと「にゃーん」と言うと「わんわん」と答えてくれます。

しかし Visual Studio 2026 の Agent モードで同じことを試すと以下のように docs/nya-n.md が見つからないと言われてしまいます。

このように Visual Studio 2026 の Agent モードではソリューションエクスプローラーに表示されているファイルしか参照できないようです。そのため、AI 用の設計ドキュメントを別フォルダーに用意しておく場合には、そのフォルダーをソリューションエクスプローラーに表示されるようにしておく必要があります。一番簡単な方法は ソリューションエクスプローラーのフォルダビューを使うことです。

フォルダビューの切り替えは、ソリューションエクスプローラーにある左上のアイコンで切り替え可能です。

切り替えると以下のように物理フォルダー構造でフォルダーが表示されるようになります。

この状態であれば、Visual Studio 2026 の Agent モードでも docs/nya-n.md を参照できるようになります。実際に動かしてみると以下のような結果になりました。

同様の効果を得る方法として、ソリューションエクスプローラーに以下のようにファイル自体を追加しておく方法もあります。

しかし、どちらの方法もデメリットがあります。

フォルダビューを使う方法のデメリット

フォルダビューを使うと、Visual Studio のデバッグ実行やビルドなどが恐らく出来なくなります。つまり IDE ではなく単なるフォルダーを開いてファイルの編集ができるだけのアプリに成り下がってしまいます。一応ファイルの実行などは出来ますが、それなら Visual Studio Code 使うわ…と思ってしまいます。

そのため IDE としての機能をフル活用したいときにはフォルダビューから元に戻して使い、GitHub Copilot を使うときには、その都度フォルダビューに切り替える、という運用が必要になります。

正直めんどくさいし、忘れてしまうので個人的には無しかなと思います。

ソリューションエクスプローラーにファイルを追加する方法のデメリット

これは AI が見る必要のあるファイルを全て1つ1つ丁寧にソリューションエクスプローラーに追加する必要があるため、手間がかかります。また、AI 用の設計ドキュメントを頻繁に更新する場合には、その都度ソリューションエクスプローラーに追加し直す必要があるため、運用コストが高くなります。

これも個人的には無しかなと思います。

妥協案

Visual Studio 2026 の GitHub Copilot の動きを確認していると、今回のようにファイルパス指定で外部ドキュメントを読み込ませる際に以下の命名規則のファイルであれば、ソリューションエクスプローラーに追加しなくても参照できることがわかりました。

• .github/instructions/**/*.instructions.md

端的に言うと GitHub Copilot のカスタムインストラクションファイルです。厳密にいうとカスタムインストラクションとして使えるのは .github/instructions/*.instructions.md なので、instructions フォルダーの下に、さらにフォルダーを作ることはあまりしないと思いますが Visual Studio 2026 の場合にはプロンプト内でファイル名指定をしてファイルを読んで貰う場合には、そこに置くのが一番良さそうです。

ということで以下のようなフォルダー構造にして動作確認をしてみました。

copilot-instructions.md は以下のような内容にしました。

copilot-instructions.md

「にゃーん」と言われたら以下のドキュメントを見て答えてください。

- .github/instructions/docs/nya-n.instructions.md

ソリューションエクスプローラーのビューをフォルダービューではなく通常の表示にしておいても、以下のようにちゃんと nya-n.instructions.md を参照して「わんわん」と答えてくれました。

この方法であれば、ソリューションエクスプローラーにファイルを追加する手間もなく、IDE としての機能もフル活用できるため、Visual Studio 2026 で GitHub Copilot を使う場合には、この方法が一番良さそうです。

こちらのファイルを読み込む挙動はプロンプト ファイル内で #file:.... を使ってファイルを指定する場合にも当てはまります。

とはいっても、ここら辺の挙動は個人的には不便だと思うので、そのうち Visual Studio Code と同じように動くようになってほしいなと思います。

まとめ

ということで Visual Studio 2026 で GitHub Copilot を使う場合の、関連ファイルを読み込ませる際の注意点について紹介しました。
このような挙動なため、AI に見てほしい AI 用の参考情報は .github/instructions/ フォルダーの下に *.instructions.md ファイルとして用意しておくのが良さそうです。普通のインストラクションファイルと混ざると分かりにくいので、さらにサブフォルダーを作って整理しておくのが良いと思います。

個人的な思いとしては、将来的には Visual Studio 2026 でも Visual Studio Code と同じように、ソリューションエクスプローラーに表示されていないファイルも Agent mode で参照できるようになってほしいなと思います。