GitHub Copilotの設定 - パス固有カスタム指示

概要

.github/instructions/ ディレクトリは、GitHub Copilotに対してパス固有のカスタム指示を提供するための機能である。

GitHub Copilotは、AIペアプログラミングツールとして、コード補完、チャット応答、コード生成を提供する。
.github/instructions/ ディレクトリ内に配置された *.instructions.md ファイルを使用することにより、特定のファイルパターンやディレクトリに対してコンテキスト固有のガイダンスをCopilotに伝えることができる。

パス固有指示ファイルは、以下に示す特徴を持つ。

• 特定のファイルパターンやディレクトリに適用される指示
• YAMLフロントマターによるglobパターン指定
• Markdown形式での自然言語記述
• 複数のIDEで統一された動作
• エージェント別の除外設定が可能

パス固有指示ファイルを使用することにより、以下に示すメリットが得られる。

• コンテキストの最適化

  作業中のファイルに関連する指示のみが適用される。

• 言語別の規約管理

  TypeScript、Python、Java等の言語別にコーディング規約を定義する。

• 領域別のガイダンス

  フロントエンド、バックエンド、API、セキュリティ等の領域別に指示を分割する。

• チーム間の統一

  チーム全体で同じコーディングスタイルとベストプラクティスを共有する。

copilot-instructions.mdとの違い

GitHub Copilotには、2種類のカスタム指示ファイルが存在する。

copilot-instructions.md

.github/copilot-instructions.md は、リポジトリ全体に適用される汎用ガイダンスである。

• 配置場所

  .github/copilot-instructions.md

• 適用範囲

  リポジトリ全体

• ファイル数

  1ファイルのみ

• 用途

  プロジェクト全体の共通原則、組織全体のポリシー、一般的なコーディング規約

パス固有指示ファイル (*.instructions.md)

.github/instructions/*.instructions.md は、特定のパスやファイルパターンに適用される指示である。

• 配置場所

  .github/instructions/ ディレクトリ

• 適用範囲

  YAMLフロントマターの applyTo プロパティで指定されたパターン

• ファイル数

  複数ファイルを作成可能

• 用途

  言語別のコーディング規約、ディレクトリ別のルール、機能別のガイダンス

下表に、2種類のカスタム指示ファイルの比較を示す。

カスタム指示ファイルの比較

特徴	copilot-instructions.md	*.instructions.md
配置場所	.github/	.github/instructions/
適用範囲	リポジトリ全体	特定のパターン
ファイル数	1ファイル	複数ファイル可能
パターン指定	不要	YAMLフロントマター必須
用途	全体的な原則	言語別・領域別ルール

推奨される使い分けを以下に示す。

• copilot-instructions.md

  プロジェクトの概要、技術スタック、ビルドコマンド、全体的なコーディング規約

• *.instructions.md

  TypeScript固有のルール、フロントエンド専用の規約、APIルートの要件、セキュリティレビューガイドライン

Claude Codeとの比較

GitHub Copilot パス固有カスタム指示 と Claude Codeの比較

項目	GitHub Copilot	Claude Code
ファイル名	*.instructions.md	CLAUDE.md (ネスト配置)
配置場所	.github/instructions/	任意のディレクトリ (プロジェクトルートまたはサブディレクトリ)
適用範囲の指定方法	applyToプロパティでglobパターン指定	ディレクトリ階層による暗黙的適用 (そのディレクトリ以下に適用)
globパターン対応	対応 例: **/*.ts, src/**/*.py	非対応
複数ファイルの作成	可能 (用途別に複数ファイル)	ディレクトリごとに1ファイル
フロントマター	YAML形式で設定 applyTo, excludeAgent	なし
エージェント除外設定	excludeAgentプロパティで指定可能	非対応
継承・マージ	親ディレクトリの指示と併用	親ディレクトリのCLAUDE.mdと自動マージ
対応環境	VS Code Visual Studio JetBrains GitHub.com	Claude Code CLI 各種IDE拡張

ファイルの配置

パス固有指示ファイルは、.github/instructions/ ディレクトリに配置する。

• 配置場所

  .github/instructions/

• ファイル命名規則

  *.instructions.md 形式

  例: frontend.instructions.md、backend.instructions.md

• ファイル形式

  Markdown形式

• 記述言語

  自然言語 (英語推奨)

ディレクトリ構成の例を以下に示す。

project/
├── .github/
│   ├── copilot-instructions.md       # 全体的な指示
│   └── instructions/                 # パス固有指示ディレクトリ
│       ├── frontend.instructions.md  # フロントエンド向け
│       ├── backend.instructions.md   # バックエンド向け
│       ├── api.instructions.md       # APIルート向け
│       └── security.instructions.md  # セキュリティレビュー向け
├── src/
│   ├── frontend/
│   ├── backend/
│   └── api/
└── README.md

複数のファイルを作成することにより、以下に示すメリットが得られる。

• ルールの明確化

  各ディレクトリやファイルタイプに適用されるルールが明確になる。

• メンテナンス性の向上

  指示の修正が容易になる。

• コンテキストの最適化

  作業中のファイルに関連する指示のみが適用される。

YAMLフロントマターの設定

パス固有指示ファイルには、YAMLフロントマターによる設定が必須である。

基本的な構造

YAMLフロントマターは、ファイルの先頭に --- で区切られた形式で記載する。

基本的な構造を以下に示す。

 ---
 applyTo: "glob_pattern"
 excludeAgent: "agent_name"
 ---
 
 # 指示の内容
 
 指示の詳細をMarkdown形式で記述する。

applyToプロパティ

applyTo プロパティは、指示が適用されるファイルまたはディレクトリをglobシンタックスで指定する。

基本的なglobパターンの例を以下に示す。

• *.py

  カレントディレクトリのみのPythonファイル

• **/*.py

  全てのPythonファイル (再帰的)

• src/**/*.py

  src/ 以下のすべてのPythonファイル

• **/subdir/**/*.py

  あらゆる深さの subdir/ 以下のファイル

複数パターンの指定例を以下に示す。

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

excludeAgentプロパティ

excludeAgent プロパティは、特定のエージェントが指示を使用するのを防ぐ。

有効な値を以下に示す。

• code-review

  Copilot Code Reviewエージェントを除外する。

• coding-agent

  Copilot Coding Agentを除外する。

省略した場合、両方のエージェントが指示にアクセスできる。

Code Reviewエージェントのみを除外する例を以下に示す。

 ---
 applyTo: "**/*.ts,**/*.tsx"
 excludeAgent: "code-review"
 ---

Coding Agentのみを除外する例を以下に示す。

 ---
 applyTo: "**/*.ts,**/*.py,**/*.java"
 excludeAgent: "coding-agent"
 ---

対応環境

パス固有指示ファイルは、複数のIDEとプラットフォームで対応している。
対応環境を以下に示す。

VS Code

VS Codeでは、完全に対応している。

• 設定方法

  github.copilot.chat.codeGeneration.useInstructionFiles を有効化する。

• 適用範囲

  ワークスペース内の全てのチャットリクエストに自動適用される。

• パス固有指示

  対応している。

Visual Studio

Visual Studioでは、完全に対応している。

• 設定方法

  リポジトリの .github/instructions/ ディレクトリを自動検出

• 適用範囲

  全てのチャットリクエストに自動適用

• パス固有指示

  対応している。

JetBrains IDE

JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm等) では、部分的に対応している。

• 設定方法

  リポジトリの .github/copilot-instructions.md のみを自動検出する。

• 適用範囲

  全てのチャットリクエストに自動適用される。

• 制限事項

  パス固有の複数ファイル (.github/instructions/*.instructions.md) には未対応

GitHub.com

GitHub.comのWebインターフェースでは、完全に対応している。

• 対応ファイル
  • .github/copilot-instructions.md
  • .github/instructions/ ディレクトリ内の複数ファイル
• 適用範囲

  全てのチャットリクエストに自動適用される。

• パス固有指示

  対応している。

Copilot Code Review

Copilot Code Reviewでは、パス固有指示ファイルを使用できる。

• 対応ファイル

  .github/instructions/*.instructions.md

• excludeAgent プロパティ

  code-review を指定することにより、Code Reviewエージェントから除外可能

記述例

フロントエンド用指示ファイル

TypeScriptとReactを使用するフロントエンド向けの指示ファイルの例を以下に示す。

ファイル名: .github/instructions/frontend.instructions.md

 ---
 applyTo: "**/*.ts,**/*.tsx"
 ---
 
 # フロントエンドコーディング規約
 
 ## ファイル構成
 
 - コンポーネント毎のディレクトリ構成を使用
 - ファイル名はPascalCase (例: UserProfile.tsx)
 
 ## ネーミング規則
 
 - Reactコンポーネント: PascalCase
 - 関数・変数: camelCase
 - 定数: UPPER_SNAKE_CASE
 
 ## コードスタイル
 
 - インデント: 2スペース
 - セミコロン: 必須
 - 引用符: ダブルクォート推奨
 - 関数は50行以内に抑える
 - 最大行長: 100文字
 
 ## React規約
 
 - 関数コンポーネントのみを使用
 - Propsには必ずTypeScript型定義を記述
 - useEffectの依存配列を必ず記述
 - カスタムフックは use で始まる名前

バックエンド用指示ファイル

Pythonを使用するバックエンド向けの指示ファイルの例を以下に示す。

ファイル名: .github/instructions/backend.instructions.md

 ---
 applyTo: "**/*.py"
 ---
 
 # バックエンドコーディング規約
 
 ## ファイル構成
 
 - モジュール毎のディレクトリ構成を使用
 - ファイル名はsnake_case (例: user_service.py)
 
 ## ネーミング規則
 
 - クラス名: PascalCase
 - 関数・変数: snake_case
 - 定数: UPPER_SNAKE_CASE
 - プライベートメソッド: _で始まる名前
 
 ## コードスタイル
 
 - PEP 8に準拠
 - インデント: 4スペース
 - 最大行長: 88文字 (Black準拠)
 - docstringは必須
 
 ## エラーハンドリング
 
 - 全てのAPI関数はtry-exceptブロックを使用
 - カスタム例外クラスを定義
 - エラーログは適切なレベルで記録
 
 ## データベース
 
 - SQLインジェクション対策としてプリペアドステートメントを使用
 - トランザクションは明示的に管理

APIルート用指示ファイル

APIルート向けの指示ファイルの例を以下に示す。

ファイル名: .github/instructions/api.instructions.md

 ---
 applyTo: "src/api/**"
 ---
 
 # APIルート規約
 
 ## エンドポイント設計
 
 - RESTful APIの原則に従う
 - エンドポイントはリソース名を複数形で表現 (例: /users, /products)
 - HTTP動詞を正しく使用 (GET, POST, PUT, DELETE)
 
 ## バリデーション
 
 - 全てのエンドポイントで入力バリデーションを実施
 - リクエストボディのスキーマを定義
 - バリデーションエラーは400 Bad Requestで返す
 
 ## レスポンス形式
 
 - 一貫したエラーレスポンス形式を使用
 - HTTPステータスコードを正しく使用
 - JSON形式で返す
 
 ## ドキュメント
 
 - 全てのエンドポイントにOpenAPIコメントを記述
 - リクエスト・レスポンスの例を含める

セキュリティレビュー用指示ファイル

セキュリティレビュー向けの指示ファイルの例を以下に示す。

ファイル名: .github/instructions/security.instructions.md

 ---
 applyTo: "**/*.ts,**/*.py,**/*.java"
 excludeAgent: "coding-agent"
 ---
 
 # セキュリティレビューガイドライン
 
 ## 認証・認可
 
 - JWT、OAuth2等の標準認証方式を使用
 - パスワードはハッシュ化して保存 (bcrypt、Argon2等)
 - アクセストークンの有効期限を設定
 - リフレッシュトークンの適切な管理
 
 ## データ保護
 
 - 機密情報はログに記録しない
 - 外部通信はHTTPS必須
 - SQLインジェクション対策 (プリペアドステートメント)
 - XSS対策 (入力のサニタイズ)
 - CSRF対策 (CSRFトークン)
 
 ## 入力検証
 
 - 全てのユーザ入力を検証
 - ホワイトリスト方式で検証
 - ファイルアップロードは拡張子とMIMEタイプを検証
 
 ## アクセス制御
 
 - 最小権限の原則を適用
 - ロールベースアクセス制御 (RBAC) を使用
 - センシティブな操作はログに記録

指示ファイルの分割戦略

パス固有指示ファイルを効果的に分割するための戦略を以下に示す。

言語別分割

プログラミング言語別に指示ファイルを分割する方法である。

• frontend.instructions.md

  TypeScript、TSXファイル向け

• backend.instructions.md

  Python、Javaファイル向け

• sql.instructions.md

  SQLファイル向け

言語別分割のメリットを以下に示す。

• 言語固有のコーディング規約を明確に定義
• 各言語のベストプラクティスを反映
• チームメンバーが言語別にルールを理解しやすい

ディレクトリ別分割

ディレクトリ構造に基づいて指示ファイルを分割する方法である。

• api.instructions.md

  src/api/** ディレクトリ向け

• utils.instructions.md

  src/utils/** ディレクトリ向け

• components.instructions.md

  src/components/** ディレクトリ向け

ディレクトリ別分割のメリットを以下に示す。

• ディレクトリの役割に応じたルールを定義
• コードの配置場所とルールの対応が明確
• ディレクトリ構造の変更に柔軟に対応

機能別分割

機能やドメイン別に指示ファイルを分割する方法である。

• database.instructions.md

  データベース関連のコード向け

• auth.instructions.md

  認証・認可関連のコード向け

• testing.instructions.md

  テストファイル向け

機能別分割のメリットを以下に示す。

• ドメイン知識とルールの対応が明確
• 機能横断的なベストプラクティスを共有
• セキュリティやパフォーマンス等の非機能要件を明確化

エージェント別分割

GitHub CopilotのエージェントごとにCoding AgentとCode Reviewエージェントで異なる指示を定義する方法である。

• Coding Agent専用

  excludeAgent: "code-review" を指定

  コード生成時のルールを定義

• Code Review専用

  excludeAgent: "coding-agent" を指定

  コードレビュー時のチェック項目を定義

エージェント別分割のメリットを以下に示す。

• コード生成とレビューで異なる視点を提供
• レビュー時のチェック項目を明確化
• コード生成時の自動適用ルールとレビュー基準を分離

記述のベストプラクティス

効果的なパス固有指示ファイルを作成するためのベストプラクティスを以下に示す。

簡潔性を保つ

焦点を絞った短い指示で最も効果的である。

• 重要な情報のみを記載

  詳細すぎる指示は逆効果

• 1ファイルあたり1ページ以内

  長すぎる指示は分割する

構造化された記述

見出し、箇条書き、明確な構造でコンテンツを整理する。

• Markdownの見出しを使用

  セクションを明確に分割

• 箇条書きでポイントを整理

  読みやすさを向上

指示型言語を使用

直接的で命令的な言語を使用する。

良い例を以下に示す。

• Use TypeScript for all new code.
• All functions must have JSDoc comments.
• Prefer composition over inheritance.

悪い例を以下に示す。

• It would be nice to use TypeScript.
• Consider adding comments.
• Inheritance might not be the best choice.

コード例を含める

概念をコード例で実証する。

コード例の記述例を以下に示す。

 # 関数の命名規則
 
 関数名はcamelCaseを使用する。
 
 良い例:
 ```typescript
 function getUserById(id: string): User {
   // 実装
 }
 ```
 
 悪い例:
 ```typescript
 function GetUserById(id: string): User {
   // 実装
 }
 ```

避けるべき内容

パス固有指示ファイルに記述すべきでない内容を以下に示す。

• UI / UXの変更要求

  GitHub CopilotはUIを変更できない

• プルリクエスト概要コメントの変更要求

  PRの形式は別の設定で管理

• コードレビュー範囲外の機能実装要求

  Code Reviewエージェントは機能を実装しない

• 外部リンクの参照

  外部リンクはアクセスできない可能性がある

• 曖昧な改善要求

  より正確に、もっと良く などの曖昧な表現

具体的な悪い例を以下に示す。

 # 悪い例
 
 - より正確にコードを書くこと
 - UIを改善すること
 - PRのコメントをもっと詳しく書くこと
 - https://example.com/docs を参照すること

具体的な良い例を以下に示す。

 # 良い例
 
 - 関数は50行以内に抑える
 - 変数名はcamelCaseを使用
 - 全ての公開APIにJSDocコメントを記述
 - エラーハンドリングにはtry-catchブロックを使用

関連項目

• GitHub Copilotの設定 - カスタム指示

  リポジトリ全体に適用される汎用ガイダンス

• GitHub Copilotの設定 - AGENTS.md

  ベンダー中立の指示ファイル形式

• GitHub Copilotの設定 - サブエージェント

  カスタムエージェントの作成方法