開発チームがGitHub Copilotを導入した際、多くの現場で最初に直面するのが「コードの一貫性の欠如」です。プロジェクト固有のガイドラインがプロンプトに与えられていない場合、Copilotは汎用的な学習データと直前で開いているファイルの断片的な情報に基づいて推論します。その結果、TypeScriptプロジェクトでコールバック構文が生成されたり、非推奨のライブラリが採用されたり、Pull Request（PR）で意図しないレイヤリング違反が発生したりします。
GitHub Copilotの「リポジトリカスタム指示（Repository Custom Instructions）」は、このチーム開発の課題を解決する公式機能です。リポジトリ直下の .github/copilot-instructions.md および .github/instructions/**/*.instructions.md をGitでバージョン管理するだけで、アーキテクチャの境界線、コーディング規約、テスト原則、セキュリティ要件を、チームメンバー全員のCopilotセッションやプルリクエストレビューに自動反映させることができます。
本記事では、カスタム指示の適用範囲と優先順位、グローバルおよびパス単位の設定手順、PRコードレビューとの自動連携、そしてコンテキストを圧迫させずに効果を最大化するベストプラクティスを解説します。
カスタム指示の適用範囲と動作メカニズム
ルールを作成する前に、GitHub Copilotがカスタム指示をどのように読み込むかを把握しておく必要があります。
カスタム指示は、ユーザーが高レベルな対話や自律タスクを実行する際、LLMへのプロンプト入力の先頭にシステムコンテキストとして自動追加されます：
- IDE内のCopilot Chat：VS Code、Visual Studio、JetBrains各IDE（IntelliJ IDEA、PyCharm、WebStormなど）、Xcode、Eclipse。
- GitHub.com上の各種機能：Webリポジトリ上でのチャット、Copilotクラウドエージェント（Cloud Agent）、PR自動生成。
- Copilot Code Review（コードレビュー）：GitHub上のPRでCopilotがコード差分（diff）を自動評価する際、カスタム指示を参照してレビューを実施。
- Copilot CLI：ターミナル環境での対話型コマンド生成。
インライン補完（ゴーストテキスト）との重要な違い
カスタム指示ファイルは、主にCopilot Chat、インラインリファクタリング（/fix や /explain）、自律エージェントセッション、PRコードレビューに適用されます。エディタ入力時にリアルタイムで表示されるミリ秒精度の「インライン補完（ゴーストテキスト）」は、超低レイテンシを維持するためにカーソル周辺のコードや開いているタブを優先して処理するため、長文のカスタム指示ファイルを即座にすべて読み込む設計にはなっていません。インライン補完での厳密なフォーマット（インデントやセミコロンなど）は、ESLint、Biome、Prettierなどの決定論的リンターに委ね、設計方針やアーキテクチャのガイドレールとしてカスタム指示を活用するのが実務上の定石です。
指示の優先順位（Precedence）
複数の指示が存在する場合、GitHub Copilotは以下の優先順位に従って指示を評価します（上位が優先）：
- 個人指示（Personal instructions）：ユーザー自身のCopilot個人設定。
- パス固有指示（Path-specific instructions）：
.github/instructions/**/*.instructions.mdでglobパターンに一致したファイル。 - リポジトリ全体指示（Repository-wide instructions）：プロジェクト直下の
.github/copilot-instructions.md。 - エージェント指示：
AGENTS.md、CLAUDE.md、GEMINI.mdなど。 - 組織レベル指示（Organization instructions）：GitHub Organizationの管理者が全社規模で設定した共通ルール。
ステップ1：リポジトリ共通指示を作成する（.github/copilot-instructions.md）
基本となる設定ファイルは、Gitリポジトリのルートに配置します：
mkdir -p .github
touch .github/copilot-instructions.md
AIの理解精度を高めるため、明確なMarkdown見出し、箇条書き、および肯定的な命令文（「〜を使用する」）を用いて簡潔に記述します。
記載すべき5つの主要項目
- プロジェクト概要とアーキテクチャ方針：アプリケーションの役割、採用パターン（クリーンアーキテクチャ、六角形アーキテクチャなど）、モジュール間の依存ルール（例：「Domain層からUIやインフラ層をインポートしてはならない」）。
- 言語バージョンと基盤ツール：Node.js 22 LTS、TypeScript 5.5、Next.js 15 App Routerなど、使用バージョンを明記。
- コーディング規約：命名規則、非同期処理とエラーハンドリング方針（例：「例外を無制限にスローせず、Result型を使用する」）。
- テスト方針：テストランナー（Vitest、Jest、PyTest）、テストの書き方（AAAパターン）、新規ロジックに対するテスト義務。
- セキュリティと検証：入力バリデーション（Zod、Pydantic）、パラメータ化クエリの強制、認証情報のハードコード禁止。
実践的なテンプレート例（TypeScript / Next.js サービス）
# リポジトリ設計方針およびコーディング規約
## プロジェクト概要
本リポジトリはコア請求管理サービス（Core Billing Service）です。Next.jsおよびNode.jsで構成され、PostgreSQLとStripe決済を連携しています。
## アーキテクチャ境界とレイヤリング
- 厳格なレイヤー分離：UIコンポーネント (`/app`, `/components`) -> アプリケーションサービス (`/src/services`) -> ドメインモデル (`/src/domain`) -> インフラリポジトリ (`/src/infrastructure`)。
- ドメイン層はフレームワーク非依存を徹底してください。`/src/domain` 内で `next/*` やデータベースクライアントをインポートすることは禁止です。
- DBアクセスは `/src/infrastructure/repositories` 配下のPrismaリポジトリを経由してください。マイグレーション以外で生SQLを直接実行してはなりません。
## TypeScript 実装基準
- TypeScript 5.x strict モードを適用。`any` は禁止し、`unknown` と型絞り込み、または明示的なZodスキーマを使用してください。
- オブジェクト定義には `type` エイリアスを優先し、拡張可能な契約にのみ `interface` を使用します。
- 非同期エラーは `Result<T, E>` 型または構造化エラークラスで処理し、未処理のPromise rejectionを発生させないでください。
- ネストした条件分岐を避け、ガード節（Guard Clauses）を用いた早期リターンを徹底してください。
## 状態管理およびデータフェッチ
- クライアント側のデータ取得には TanStack Query (`@tanstack/react-query`) を使用してください。キャッシュ制御を行わない `useEffect` でのAPI呼び出しは禁止です。
- Server Actions はドメインサービスを呼び出す前に、Zodスキーマで入力ペイロードを検証してください。
## テスト規約
- テストランナー：Vitest + React Testing Library。
- 単元テストは対象ソースコードと同じディレクトリに配置してください（`*.spec.ts` または `*.spec.tsx`）。
- すべてのテストケースは Arrange-Act-Assert (AAA) 構成に従ってください。
- 外部通信境界のモックには Mock Service Worker (MSW) を使用し、言語の標準機能や内部ヘルパーはモックしないでください。
## 主要コマンド
- テスト実行：`pnpm test`
- 型チェック：`pnpm typecheck`
- リント検証：`pnpm lint`
ステップ2：パス固有の指示を切り出す（.github/instructions/）
モノレポや大規模フルスタック開発では、すべての規則を1つのファイルに集約すると、トークン消費が増大し、AIの焦点がブレる恐れがあります。例えば、Goのバックエンドを開発しているエンジニアに対して、ReactコンポーネントのCSS記述ルールを常に提示する必要はありません。
パス固有指示（Path-specific instructions）を使用すると、ファイルパス（glob）に応じて最適なコンテキストを動的に付与できます。
ディレクトリ構成
.github/instructions/ ディレクトリ配下にモジュールごとのファイルを配置します：
.github/
├── copilot-instructions.md
└── instructions/
├── frontend.instructions.md
├── backend.instructions.md
└── migrations.instructions.md
ファイル命名とFrontmatter設定
パス固有ファイルは末尾を .instructions.md とし、ファイル先頭に applyTo を定義したYAML Frontmatterを記述します：
---
applyTo: "apps/web/**/*.{ts,tsx}"
---
# フロントエンド開発規約
- コンポーネントは名前付きエクスポートの関数コンポーネントとして定義してください。
- スタイルは Tailwind CSS のユーティリティクラスを使用し、インラインスタイルオブジェクトは避けてください。
- インタラクティブな要素には必ず適切な `aria-*` 属性を付与し、キーボード操作に対応させてください。
- アイコンは `lucide-react` のみからインポートしてください。
便利なGlobパターンの例
**/*.py：リポジトリ全体のすべてのPythonファイルに適用。services/billing/**/*.go：請求サービス配下のGoコードにのみ適用。**/*.test.ts,**/*.spec.ts：カンマ区切りで複数のテストファイル形式をまとめて指定。
特定エージェントの除外（excludeAgent）
クラウドエージェントの自律作業でのみ参照させ、PRコードレビュー時には適用したくない指示がある場合は、excludeAgent を指定します：
---
applyTo: "**"
excludeAgent: "code-review"
---
# 自律型エージェント用ビルド手順
- 統合テストを実行する前に、必ず `pnpm db:migrate` を実行してください。
- 新しい環境変数を追加した場合は、`.env.example` を更新してください。
ステップ3：GitHub PRコードレビューでの自動検証を有効化する
カスタム指示は、開発中の対話だけでなく、CopilotによるPRコードレビューの評価基準としても活用できます。
コードレビュー連携の有効化手順
- 対象のGitHubリポジトリを開き、Settings（リポジトリ設定）タブを選択します。
- 左サイドバーの Code, planning, and automation から Copilot -> Code review を選択します。
- Use custom instructions when reviewing pull requests（プルリクエストのレビュー時にカスタム指示を使用する）のトグルをオンにします。
ブランチ評価のメカニズム
CopilotがPRをレビューする際、カスタム指示はターゲットブランチ（main など）ではなく、変更元のPRブランチ（Head Branch） から読み込まれます。
この設計には大きなメリットがあります。アーキテクチャチームがコーディング規約を更新する際、新しい規約ファイルとそれに準拠した実装コードを同じPRに含めることができます。Copilotはマージ前のPRブランチ上の指示に基づいて即座にレビューを行うため、新ルールの実効性をマージ前に検証できます。
ステップ4：開発環境で指示の適用状況を確認する
チームメンバーの開発環境でカスタム指示が正常に読み込まれているかを検証します：
- IDE設定の確認：
- VS Code：設定（
Ctrl+,またはCmd+,）を開き、instruction fileを検索して、Code Generation: Use Instruction Files がオンになっていることを確認します（デフォルトでオン）。 - JetBrains IDE：Copilot Chatパネル右上の歯車アイコンから Customizations を選択し、リポジトリ指示が認識されているか確認します。
- VS Code：設定（
- チャットのReferences（参照情報）を確認：
- Copilot Chatでプロジェクトに関する質問（例：「認証ミドルウェアを作成して」）を送信します。
- 回答の最上部に表示される References を展開します。
- 設定が有効であれば、
.github/copilot-instructions.mdや該当する.instructions.mdへのリンクが表示され、AIがチーム規約を参照して回答したことが確認できます。
チーム運用のベストプラクティスと注意点
| 推奨される運用 | 避けるべきアンチパターン | チームへの影響 |
|---|---|---|
| プロジェクトの核心的な制約を端的にまとめる | 社内Wikiの規約書（数十ページ）を丸ごとコピーする | トークンを過度に消費し、肝心なルールが反映されない |
| 具体的で実行可能な指示を書く（「Zodで入力を検証する」） | 抽象的で精神論的な表現（「美しく拡張性の高いコードを書く」） | 指示の判断基準が曖昧になり、汎用的な提案にとどまる |
モノレポでは .instructions.md で関心を分離する | 全言語・全領域のルールを1つの巨大ファイルに混在させる | 異なる技術スタックの規則が干渉し、誤生成を招く |
| 決定論的CIツール（Linter/型チェック）と併用する | Copilotの指示だけに規約遵守を依存する | 生成AIは確率的推論のため、稀に規約違反をすり抜ける |
| Git管理し、PRレビューを通じてルールを継続更新する | 開発者各自がローカルに独自の指示ファイルを放置する | チーム全体の基準が乖離し、属人化が進む |
プロンプトファイル（.github/prompts/*.prompt.md）との使い分け
リポジトリカスタム指示が「常に守るべき共通制約」であるのに対し、新しいAPIルートの作成やマイグレーションの作成といった「定型タスク」には、公開プレビュー中のCopilot Promptファイル（.github/prompts/*.prompt.md）の併用が有効です。タスク固有の入力ひな形をプロンプトファイルで提供し、全体の設計制約を .github/copilot-instructions.md で縛ることで、品質と生産性を両立できます。
まとめ：導入チェックリスト
- リポジトリルートに
.github/copilot-instructions.mdを作成し、アーキテクチャ境界と主要規約を明記する。 - 必要に応じて
.github/instructions/配下にパス固有の指示を配置し、applyToで適用範囲を絞る。 - GitHubリポジトリ設定でPRコードレビューのカスタム指示トグルをオンにする。
- IDEのCopilot ChatでReferencesを確認し、指示ファイルが正常に参照されていることを検証する。
- フレームワークのアップデートや設計変更に合わせて、PR経由で指示ファイルを継続的に見直す。
参考文献
- Adding repository custom instructions for GitHub Copilot - GitHub Docs
- Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
- Support for different types of custom instructions - GitHub Docs
- About customizing GitHub Copilot responses - GitHub Docs
- 5 tips for writing better custom instructions for Copilot - The GitHub Blog