GitHub Copilot Code ReviewのCustom Instructionsでハマった2つの落とし穴

TL;DR

• Copilot Code ReviewはAGENTS.mdやCLAUDE.mdを読まない
• instructionsファイル内の外部ファイルの参照指示はフォローされない
• Copilotの利用元と機能ごとに参照するファイルが異なるため、適切な場所にファイルを配置する必要がある

背景

普段はVS Codeで開発し、GitHubを利用しています。
プロジェクトにAGENTS.mdを配置し、そこにコーディング規約やアーキテクチャルールなどを記載していました。
多重管理したくないのでCLAUDE.mdにはAGENTS.mdへの参照指示だけを書いていました。
Copilot ChatでもAGENTS.mdをサポートし、読み込んでいるので、Copilotはこの構成で問題ないと思っていました。
しかし、Copilot Code Reviewを利用したときに英語で誤字脱字レベルの指摘しかしてくれないことに不満を持っていました。
そこで原因を調査することにしました。

原因1： 機能ごとに参照ファイルが違う

instructionsの種類

まずCopilotへの指示を書くinstructionsには下記の種類があります。

種類	ファイル
Repository-wide custom instructions	.github/copilot-instructions.md
Path-specific custom instructions	.github/instructions/*.instructions.md
Agent instructions	AGENTS.md、CLAUDE.md、GEMINI.mdなど

参照元

Copilotの各機能が参照するinstructions

調査¹の結果、利用する環境と利用するGitHub Copilotの各機能で参照するファイルが異なることがわかりました。
私はVS Codeでローカル開発し、GitHub上でReviewやCodingAgentを動かすのでまとめると下記の通りです。他のIDEをお使いの方は公式ドキュメントを参照ください。

Copilot機能(利用元)	Agent instructions	Repository-wide	Path-specific
Copilot Chat(VS Code)	△2	○	○3
Copilot Coding Agent(GitHub)4	○	○	○
Copilot Code Review(GitHub)	×	○	○

つまりCode ReviewだけAgent instructionsを読まない！
これのせいでレビューの指摘の精度が悪いのだとわかりました。

対応策1： Custom Instructionsファイルを配置

前述の通りCopilot Code ReviewでもRepository-wide custom instructionsとPath-specific custom instructionsは読み込むのでそちらにプロジェクトルールなどを書くことにします。
AI用Instructionファイルの多重管理が嫌だったので、参照の指示だけを記載することにしました。

.github/copilot-instructions.md

必ず[AGENTS.md](../AGENTS.md) を参照してください。

しかし、instructionsファイルを作成しても残念ながら効果を感じられませんでした。

原因2: 他ファイル参照指示はフォローされない

GitHubドキュメントの記述

改めてドキュメントを見ているとPromptingのページで歯切れの悪い下記の記述がありました。

for a large and diverse repository, these may cause problems:

• Requests to refer to external resources when formulating a response

次のような例では may not have the intended results と言っています。

Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code.

参照元

まさに必ず[AGENTS.md](../AGENTS.md) を参照してください。と書いた私のパターンと同じです。

GitHub公式ブログの記事

またGitHub公式ブログで次の記事を見つけました。

Unlocking the full power of Copilot code review: Master your instructions files

ここのしてはいけないことのリストに次の記述があります。

Including external links. Copilot won’t follow them. You should copy relevant info into your instructions files instead.

外部リンクを含める（ことはしてはいけない）。Copilotはそれらをフォローしない。代わりに内容をinstructionsにコピーしろと明快に書かれています。
必要な情報はcustom instructionsファイルに直接記載する必要があるようです。

対応策2： instructionsファイルにプロジェクトルールを直接書く

instructionsファイル内で他のファイルを参照してもCopilotは参照先を読みに行かないようです。
たしかにGitHubActionsのログを見ても直接のinstructionを読み込むだけでそこから他への参照は行っていないように見えます。
仕方がないので重複管理となって嫌ですが、一旦必要な情報はinstructionsファイルに直接記載することとしました。

おまけ: Code Review用にpath-specific instructionsを作成

ついでにCode Review用のpath-specific instructionsも作成しました。

.github/
└── instructions/
    └── code-review.instructions.md

---
applyTo: "**/*"
excludeAgent: "coding-agent"
---

これでレビュータスクの内容がCoding Agentに読み込まれなくなります。
excludeAgentで指定可能な値は "coding-agent" と "code-review" のみです。
つまり分かり辛いですが、記述していない方が使うinstructionsになります。
また現状chatは指定できないのでCopilot Chatもこのinstructionを読み込んでしまいます。レビューに関係なくても読み込んでしまうので今後のアップデートに期待です。

まとめ

以上の対応をdefault branchに入れてからCopilot Code Reviewをしてもらったら日本語でプロジェクトルールに則した指摘をしてもらうことができました。

やりたいこと	正しい方法
Code Review にルールを適用	Repository-wide or Path-specific custom instructionsに記載
Code Review 専用の指示	Path-specific custom instructionsでexcludeAgent: "coding-agent"を使用
他ファイルの内容を参照させる	リンクではなく内容を直接コピー

GitHub Copilot Code Reviewにうまく指示が伝わらないなと困っている方の一助になれば幸いです。

1. 利用元の環境によっても差があるのは本当にややこしいですね。実際reviewerにCopilotをアサインしたりissueをCopilotにアサインした結果やそのGitHubActionsのログを見てもドキュメントの通りのように感じています。 ↩

2. 公式ドキュメントによるとVS CodeからChatを使う場合はAgent instructionsのうちAGENTS.mdのみサポートしているようなので△と表現しています。 ↩

3. 公式ドキュメントに「Currently, on GitHub.com, path-specific custom instructions are only supported for Copilot coding agent and Copilot code review.」とありますが、Copilot Chatでもpath-specific custom instructionsを読み込んでくれているように見えるので◯にしています。 ↩

4. Chatのagent modeではなくGitHub上で自律的に動作する機能のことです。 ↩