カスタム指示でルールを伝える(copilot-instructions.md)

Copilot に「説明は日本語で」「ライブラリは足さないで」のようなルールを毎回書くのは手間です。カスタム指示のファイルにルールを書いておくと、そのルールが Copilot に渡されます。この記事では、リポジトリ全体に効く .github/copilot-instructions.md を中心に、作り方と確かめ方を説明します。

カスタム指示の種類

リポジトリ(コードと変更の記録をまとめた置き場所)に置くファイルのほか、自分用・組織用の指示があります。

VS Code で Copilot を使う場合、公式のおすすめは .github/copilot-instructions.md か AGENTS.md です。対象のファイルを絞りたいときは、.github/instructions/ の .instructions.md を使います。

リポジトリ全体の指示を作る

いちばん基本になるのが、リポジトリ全体に効く .github/copilot-instructions.md です。

VS Code の画面からも作れます。

• チャットで /init と入力して送ると、プロジェクトを調べて、最初のカスタム指示を作ります。できた中身は、読んで確かめてから使います。
• チャットビューの歯車(Configure Chat)か、コマンドパレットの「Chat: Open Customizations」から Instructions → New で作れます。コマンド「Chat: New Instructions File」もあります。

書き方の例

公式ドキュメントは、次のような書き方をすすめています。

• 短く、1 つの文に 1 つの指示を書く。
• 理由も書く。
• よい例と、よくない例のコードを見せる。
• リンター(書き方を自動で確かめる道具)で済む決まりは書かない。

次は、ブラウザで動くやることリストのリポジトリを想定して、編集部が作った例です。

## このリポジトリについて

ブラウザで動くやることリストです。
index.html・app.js・style.css の 3 つのファイルでできています。

## 守ってほしいこと

- 説明とコメントは日本語で書いてください。
- ライブラリは追加しないでください。
  index.html を開くだけで動くようにしたいからです。
- 入力された文字は textContent で表示してください。
  innerHTML に入れると、入力が HTML として扱われるからです。
  - よい例: `label.textContent = todo.text;`
  - よくない例: `label.innerHTML = todo.text;`

決まったファイルにだけ効かせる(.instructions.md)

.github/instructions/ の中に、名前が .instructions.md で終わるファイル(例: js.instructions.md)を作ると、決まったファイルを作ったり変えたりするときにだけ使う指示を書けます。対象は、ファイルの先頭の frontmatter(--- で囲んで書く設定)で決めます。

---
name: "JavaScript のルール"
description: "JavaScript のファイルを書くときのルール"
applyTo: "**/*.js"
---

- 変数は const で宣言し、値を変えるときだけ let を使ってください。

• name: 表示される名前です。
• description: どんな作業のための指示かを書きます。必要なときに読み込むのに使われます。
• applyTo: 対象のファイルを、glob という書き方で指定します。作ったり変えたりするファイルが一致すると、自動で付きます。

**/*.js は「どのフォルダにある .js のファイルも」という意味です。description と applyTo のどちらも書かないと自動では付かないので、チャットで手で添付します。

指示が重なったときの優先順位

優先順位は、個人 > リポジトリ(パス別 > リポジトリ全体 > エージェント用)> 組織 です。ただし、当てはまる指示はすべて Copilot に渡されます。ファイルどうしで食い違うことを書かないようにします。

機能ごとに読む指示

どの指示を読むかは、Copilot の機能によって違います(GitHub Docs の対応表から抜き出したもの)。

• VS Code の設定 github.copilot.chat.codeGeneration.useInstructionFiles(指示のファイルを使う)と chat.useAgentsMdFile(AGENTS.md を使う)は、どちらも既定で true です。フォルダの中に置いた AGENTS.md を使う chat.useNestedAgentsMdFiles は、既定でオフです。
• Session Target を Local にしたときのエージェントは、CLAUDE.md なども読めます。
• Copilot のコードレビューは、プルリクエストの head ブランチ(変更する側)にある指示を読みます。

指示が効いているかを確かめる

応答の上の References(「Used n references」と出ているところ)を開くと、その応答で使われたファイルが並びます。ここに指示のファイルがあれば、指示が読み込まれています。

プロンプトファイルについて

次の記事では、GitHub の Issue を Copilot に任せる cloud agent と、コードレビューを説明します。どちらも、ここで作ったカスタム指示を読みます。