GitHub Copilotは、開いているファイルや入力中のコードだけでなく、プロジェクトに保存した指示も参考にして回答や変更を生成できます。プロジェクトのルールをコンテキストファイルにまとめると、毎回同じ説明を入力する手間を減らせます。

この記事では、Visual Studio Code（VS Code）で使える代表的なコンテキストファイルの種類と、リポジトリに設定する手順を解説します。Copilotのバージョンや利用するAgentによって、対応するファイルや表示名が異なる場合があります。実際に利用するときは、最新の公式ドキュメントも確認してください。

# 前提条件

次のものを準備します。

• VS Code
• GitHub Copilotを利用できるGitHubアカウント
• Gitで管理しているプロジェクト

この記事では、プロジェクトのルートディレクトリをPROJECT_ROOTと表記します。すでにプロジェクトをVS Codeで開いている場合は、PROJECT_ROOTを実際のプロジェクトの場所に読み替えてください。

# コンテキストファイルの種類

VS Codeでプロジェクトの指示を共有するときは、目的に応じて次のファイルを使い分けます。

copilot-instructions.mdは、プロジェクトの目的や共通の開発ルールを書くファイルです。ファイル名と配置場所を変更すると、自動的に読み込まれないことがあります。

パス別の指示ファイルは、先頭のfront matterにapplyToを記述して適用対象を指定します。例えば、次の指定はすべてのTypeScriptファイルに適用されます。

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

AGENTS.mdは、モノレポなどでディレクトリごとに異なるルールを設定したい場合に便利です。利用するAgentや実行環境によって対応状況が異なるため、対象となるAgentのドキュメントも確認します。

# リポジトリ全体に指示を追加する

まず、すべての作業で共有したいルールを.github/copilot-instructions.mdに記述します。

## ファイルを作成する

プロジェクトのルートで、次のディレクトリとファイルを作成します。

PROJECT_ROOT/
└── .github/
    └── copilot-instructions.md

ファイルには、Copilotが作業に必要とする情報を短く具体的に記述します。例えば、次のように書きます。

# Project instructions

- このプロジェクトはHugo Extendedでビルドする多言語サイトです。
- コンテンツはcontent/ja/とcontent/en/に分けて管理します。
- ブログ記事を変更したときは、日本語版と英語版の内容を確認します。
- 変更後はhugo --minifyを実行してビルドを確認します。
- 生成されたpublic/とresources/_gen/は直接編集しません。

プロジェクトの目的、主要なディレクトリ、使用するコマンド、変更時に守るルールを含めると、Copilotが作業の前提を理解しやすくなります。長いドキュメントをそのまま貼り付けるのではなく、繰り返し必要になる情報に絞ります。

# パス別の指示を追加する

言語やディレクトリごとにルールが異なる場合は、.github/instructions/に指示ファイルを作成します。

例えば、Markdownファイルに対するルールを次のように保存します。

PROJECT_ROOT/
└── .github/
    └── instructions/
        └── markdown.instructions.md

---
applyTo: "**/*.md"
---

- 見出しは内容を表す短い文にします。
- コマンドはコードブロックで示します。
- 手順には、実行後の確認方法を含めます。

特定のディレクトリだけを対象にする場合は、例えばcontent/ja/**/*.mdのようなglobを指定します。複数の拡張子を対象にするときは、applyToの値をカンマで区切ります。

リポジトリ全体向けの指示とパス別の指示が対象リクエストに一致する場合、両方の指示が使われることがあります。内容が矛盾すると回答や変更の品質に影響するため、共通ルールと個別ルールの役割を分けて記述します。

# AGENTS.mdを使う

Agentの作業に固有のルールを設定するときは、AGENTS.mdを利用できます。リポジトリのルートに置くと、プロジェクト全体のAgent作業に対する指示になります。

PROJECT_ROOT/
└── AGENTS.md

モノレポでサブプロジェクトごとにルールを分ける場合は、次のように配置できます。

PROJECT_ROOT/
├── AGENTS.md
└── packages/
    └── web/
        └── AGENTS.md

サブディレクトリの作業では、より近い場所にあるAGENTS.mdが優先されます。ルートの共通ルールとサブプロジェクト固有のルールが矛盾しないようにします。

AGENTS.mdは、すべてのCopilot機能に同じように適用されるとは限りません。コード補完、Chat、Agent、GitHub.comのCloud AgentやCode Reviewでは、対応するカスタマイズの種類が異なる場合があります。

# 指示内容の書き方

コンテキストファイルには、Copilotが判断しやすい情報を記述します。

• プロジェクトの目的と主要な技術
• ディレクトリやファイルの役割
• コーディング規約と命名規則
• テスト、ビルド、静的解析のコマンド
• 変更してはいけないファイルや互換性の条件
• 変更後に確認すべき項目

例えば、「きれいなコードにする」と書くより、「公開APIの名前を変更せず、既存のテストを実行する」と書くほうが確認可能です。指示を小さな箇条書きに分け、必要な条件や例外を明記します。

# Copilotで適用結果を確認する

ファイルを保存したら、VS CodeでCopilot Chatを開いて、指示が使われているかを確認します。

1. プロジェクトのルートをVS Codeで開きます。
2. .github/copilot-instructions.mdなどの指示ファイルを保存します。
3. Chatで、プロジェクトの構成や変更時の確認手順について質問します。
4. 回答に、指示ファイルに記述した内容が反映されているか確認します。
5. Agentに作業を依頼する場合は、変更されたファイルと実行されたコマンドを確認します。

パス別の指示を確認するときは、applyToに一致するファイルを対象に質問します。例えば、Markdownファイルだけに適用する指示を設定した場合は、Markdown記事の見出しやリンクについて質問します。

指示ファイルの内容が回答に反映されない場合でも、ファイルを読み込んだことだけで正しさが保証されるわけではありません。回答の参照情報やAgentのデバッグログを確認し、必要な指示を質問文にも具体的に含めて結果を比較します。

# 適用されないときの確認

コンテキストファイルが使われていないように見える場合は、次の項目を確認します。

1. ファイル名がcopilot-instructions.mdまたはNAME.instructions.mdの形式になっているか確認します。
2. copilot-instructions.mdがリポジトリの.githubディレクトリにあるか確認します。
3. パス別ファイルが.github/instructions以下にあるか確認します。
4. applyToのglobが対象ファイルのパスと一致しているか確認します。
5. VS Codeでリポジトリのルートを開いているか確認します。
6. VS CodeとGitHub Copilotを最新の状態に更新します。
7. Agentを利用している場合は、Agentのデバッグログで読み込まれたファイルを確認します。

モノレポでリポジトリのサブディレクトリだけを開いている場合は、親リポジトリのカスタマイズを検索する設定が関係することがあります。設定名や既定値はVS Codeのバージョンによって変わる可能性があるため、公式ドキュメントで確認してください。

# 注意点

## 指示は短く具体的にする

指示を増やしすぎると、重要な条件が埋もれたり、指示同士が矛盾したりします。プロジェクト全体のルールと、特定のファイルだけのルールを適切に分けます。

## 生成結果を検証する

コンテキストファイルを設定しても、Copilotが正しいコードを生成するとは限りません。差分、型、例外処理、境界値、セキュリティ上の問題を確認し、テストや静的解析を実行します。

## 機密情報を含めない

APIキー、パスワード、個人情報、顧客情報、社内の機密情報をコンテキストファイルに書かないでください。リポジトリを共有したときに、意図せず他の人やサービスから参照される可能性があります。

## 対応機能を確認する

コンテキストファイルの種類によって、適用されるCopilotの機能が異なります。VS Code、GitHub.com、Cloud Agent、Code Reviewで同じ動作になるとは限らないため、利用する環境の公式ドキュメントを確認します。

# まとめ

GitHub Copilotのコンテキストファイルを使うと、プロジェクトの目的、開発ルール、検証方法を繰り返し伝える手間を減らせます。

• 共通ルールは.github/copilot-instructions.mdに記述する
• ファイルやディレクトリごとのルールは.github/instructions/*.instructions.mdに記述する
• Agent固有のルールはAGENTS.mdに記述する
• 指示は短く具体的にし、生成結果を必ず確認する

詳しい仕様は、GitHub Copilotのリポジトリカスタム指示（GitHub Docs）とVS CodeのCopilotカスタマイズを参照してください。