1. はじめに

GitHub Copilot の出力がチーム方針とずれる場面では、前提の共有不足が課題になりやすいです。本記事を作成した背景は、Markdown ベースの指示ファイルが複数種類あり、どれをどう組み合わせるべきか分かりにくいことです。本記事の目的は、.github/copilot-instructions.md と .github/instructions/*.instructions.md の使い分けと設定手順を、公式ドキュメントに基づき整理することです。Markdown の指示ファイルを使うと、毎回プロンプトで説明しなくても、命名規則や設計方針を自動適用できます（参考: VS Code: Use custom instructions）。

2. 機能概要

Markdown で使う主なカスタマイズは次の 2 つです。

  1. リポジトリ全体指示: .github/copilot-instructions.md
  2. パス別指示: .github/instructions/NAME.instructions.md

VS Code では両方を組み合わせて自動適用できます。GitHub.com でも活用できますが、path-specific instructions は Copilot cloud agent と Copilot code review でサポートされます（参考: Adding repository custom instructions for GitHub Copilot - GitHub Docs）。

機能VS Code ChatGitHub.com ChatCopilot Code Review
.github/copilot-instructions.md対応対応対応
.github/instructions/*.instructions.md対応機能によって差分あり対応

Copilot の Markdown 指示読み込みフロー

3. セットアップ

ステップ 1: 全体ルールを作る

.github/copilot-instructions.md を作成します。

markdown
# Repository coding rules

- 返答は日本語で、結論を先に書く。
- TypeScript は strict 前提で実装する。
- 公開関数には JSDoc を付ける。
- 変更後は必ず npm run format:check と npm test を実行する。

ステップ 2: ファイル別ルールを追加する

.github/instructions/frontend.instructions.md などを作り、applyTo を設定します。

markdown
---
name: Frontend Rules
applyTo: "web/**/*.{ts,tsx}"
---

# Frontend rules

- コンポーネントは関数コンポーネントで作成する。
- UI 文言は i18n キー経由で管理する。

ステップ 3: 反映を確認する

Chat の応答で References を開き、対象指示ファイルが含まれているか確認します。

確認項目は次の 3 つです。

  1. References に対象ファイルが表示される
  2. applyTo 対象外ファイルでは適用されない
  3. 競合時に優先順位どおりの応答になる

4. 実践例

例 1: 小規模リポジトリ

全体ルール 1 ファイルのみ運用。

  • Before: レビューで命名指摘が毎回発生
  • After: 体感として規約違反の指摘が減少（定量計測は未実施）

例 2: モノレポ

フロントとバックエンドで instructions を分離。

  • Before: 別言語の規約が混在
  • After: applyTo で対象を限定し、規約混在を抑制

5. Before / After 比較

観点BeforeAfter
プロンプト量毎回説明が必要共通ルールを自動適用
レビュー指摘規約違反が多い初稿での適合率が上がる
オンボーディング属人化しやすいルールを Markdown で共有

6. Tips & トラブルシューティング

  • 指示が効かない場合: applyTo の glob と配置場所を確認します。
  • モノレポの場合: chat.useCustomizationsInParentRepositories を有効化します。
  • 診断する場合: Chat ビューの Diagnostics で読み込まれた instruction files とエラーを確認します。
  • 指示が競合する場合: 個人指示 > リポジトリ指示 > 組織指示の順を意識します（About customizing GitHub Copilot responses - GitHub Docs）。

7. 注意点・制限事項

  • 指示は万能ではなく、曖昧な要求は曖昧な出力になります。
  • 長文化しすぎると逆に効果が落ちるため、短いルールを分割して管理します。
  • Custom instructions はエディターの inline suggestions には反映されません。
  • プランや実行環境により、使える機能（レビュー連携など）は異なります。

8. まとめ

Markdown ベースのカスタマイズは、Copilot の品質を「運用で安定化」するための仕組みです。まずは全体ルール 1 ファイルから始め、次に applyTo 付きの分割ルールへ進めると、少ないコストで効果を実感できます。

9. 参考情報

この記事の執筆にあたり、AI の支援を受けています。