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

概要

copilot-instructions.md は、GitHub Copilotに対して全体のカスタム指示を提供するための設定ファイルである。

GitHub Copilotは、AIペアプログラミングツールとして、コード補完、チャット応答、コード生成を提供する。
copilot-instructions.md ファイルを使用することにより、プロジェクト固有のルール、コーディング規約、技術スタック情報などをCopilotに伝え、全てのCopilotリクエストに自動的に適用させることができる。

copilot-instructions.md は、以下に示す特徴を持つ。

リポジトリ全体に適用されるカスタム指示
Markdown形式での自然言語記述
複数のIDEで統一された動作
最大2ページ程度の簡潔な記述
優先度階層による柔軟な設定管理

copilot-instructions.md を使用することにより、以下に示すメリットが得られる。

一貫性の向上
プロジェクト固有のコーディング規約を全てのチャットリクエストで適用
効率の向上
毎回同じ指示を繰り返す必要がなくなる
チーム間の統一
チーム全体で同じコーディングスタイルとベストプラクティスを共有
コンテキストの維持
プロジェクトの技術スタック、ビルド方法、テスト方法を常に保持

配置場所と基本構成

copilot-instructions.md ファイルは、リポジトリルートの .github ディレクトリ内に配置する。

配置場所
.github/copilot-instructions.md
ファイル形式
Markdown形式
記述言語
自然言語 (英語推奨)
サイズ制限
最大2ページ程度

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

<プロジェクトルート>/
├── .github/
│   ├── copilot-instructions.md  # カスタム指示ファイル
│   ├── instructions/            # パス固有指示ディレクトリ (オプション)
│   │   ├── typescript.instructions.md
│   │   └── api.instructions.md
│   └── workflows/               # GitHub Actions
├── src/
└── README.md

ファイルが正しい場所に配置されると、対応するIDEで自動的に検出され、全てのチャットリクエストに適用される。

記述方法

基本的な記述形式

copilot-instructions.md ファイルは、Markdown形式で自然言語により記述する。

記述形式の種類を以下に示す。

単一段落での記述
全ての指示を1つの段落にまとめる。
各行ごとの記述
1行に1つの指示を記述する。
空白行で区切った記述
複数の段落に分けて記述する。

いずれの形式でも対応可能であるが、1行1指示の簡潔な記述が推奨される。
空白行は処理時に無視される。

基本的な記述例を以下に示す。

 We use TypeScript for all new JavaScript code.
 Follow functional programming patterns.
 Prefer composition over inheritance.
 All public APIs must have comprehensive JSDoc comments.
 We use Jest for unit testing with 80%+ code coverage target.

記述のヒント

効果的な copilot-instructions.md を作成するための記述のヒントを以下に示す。

簡潔性を保つ
最大2ページ程度に抑える。

重要な情報のみを記載する。
具体性を重視する
抽象的な説明ではなく、具体的な指示を記述する。

例: コードは読みやすく書くこと ではなく 関数は50行以内に抑え、変数名はcamelCaseを使用すること
機密情報を含めない
パスワード、APIキー、シークレットトークンは記載しない。

機密情報は環境変数や設定ファイルで管理する。
優先度の高い情報から記述する
リポジトリの概要、技術スタック、コーディング規約の順に記述する。

記述例

シンプルな例

最小限の構成で copilot-instructions.md を作成する例を以下に示す。

 We use TypeScript for all new JavaScript code.
 Follow functional programming patterns.
 Prefer composition over inheritance.
 All public APIs must have comprehensive JSDoc comments.
 We use Jest for unit testing with 80%+ code coverage target.

言語固有の例

TypeScriptプロジェクト向けの詳細な記述例を以下に示す。

 Use double quotes for JavaScript strings, never single quotes.
 Use tabs for indentation (not spaces).
 Always use optional chaining (?.) and null coalescing (??) operators.
 Components should use PascalCase naming.
 Variables and functions should use camelCase naming.

プロジェクト設定の例

包括的な copilot-instructions.md の記述例を以下に示す。

 # Project Overview
 
 This is a React-based web application for e-commerce.
 
 # Tech Stack
 
 - Frontend: React 18 + TypeScript 5.0
 - State Management: Zustand
 - Styling: Tailwind CSS
 - Testing: Jest + React Testing Library
 - Build Tool: Vite
 
 # Build and Test Commands
 
 - Development server: npm run dev
 - Build: npm run build
 - Test: npm test
 - Lint: npm run lint
 
 # Project Layout
 
 - src/components/: React components
 - src/pages/: Page components
 - src/hooks/: Custom hooks
 - src/store/: Zustand stores
 - src/utils/: Utility functions
 
 # Coding Standards
 
 - Use functional components only
 - Props must have TypeScript type definitions
 - Functions should be under 50 lines
 - Variables and functions: camelCase
 - Components: PascalCase
 - Constants: UPPER_SNAKE_CASE
 - Indentation: 2 spaces
 - Max line length: 100 characters
 - Always use semicolons
 
 # Error Handling
 
 - All async functions must have try-catch blocks
 - Error messages should be user-friendly
 - Log errors to console in development mode
 
 # Testing Requirements
 
 - All new features require unit tests
 - Maintain 80%+ code coverage
 - Test edge cases and error conditions
 
 # Security
 
 - Never log passwords or API keys
 - Validate all user inputs
 - Use environment variables for sensitive data

対応IDE

copilot-instructions.md は、複数のIDEで対応している。
IDE別の対応状況と設定方法を以下に示す。

VS Code

VS Codeでは、設定の有効化が必要である。

設定方法
github.copilot.chat.codeGeneration.useInstructionFiles を有効化する。
適用範囲
ワークスペース内の全てのチャットリクエストに自動適用される。
制限事項
インライン提案 (Copilot Completions) には適用されない。
確認方法
Command Paletteから Chat: Configure Instructions を実行する。

VS Codeでの設定例を以下に示す。

 {
   "github.copilot.chat.codeGeneration.useInstructionFiles": true
 }

設定ファイルの場所
設定範囲	ファイルパス
ワークスペース設定	.vscode/settings.json (プロジェクトルート)
ユーザ設定 (Linux)	~/.config/Code/User/settings.json
ユーザ設定 (Windows)	%APPDATA%\Code\User\settings.json
ユーザ設定 (MacOS)	~/Library/Application Support/Code/User/settings.json

Visual Studio

Visual Studioでは、自動検出により設定が適用される。

設定方法
リポジトリの .github/copilot-instructions.md を自動検出
適用範囲
全てのチャットリクエストに自動適用
パス固有指示
対応している

JetBrains IDE

JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm等) では、基本的な対応がされている。

設定方法
リポジトリの .github/copilot-instructions.md を自動検出
適用範囲
全てのチャットリクエストに自動適用
グローバル設定
ホームディレクトリに global-copilot-instructions.md を配置可能
制限事項
パス固有の複数ファイル (.github/instructions/*.instructions.md) には未対応

Xcode

Xcodeでは、基本的な対応のみサポートされている。

設定方法
リポジトリの .github/copilot-instructions.md を自動検出
適用範囲
リポジトリカスタム指示のみ
制限事項
パス固有の指示には未対応

GitHub.com

GitHub.comのWebインターフェースでは、複数のファイル形式に対応している。

対応ファイル
- .github/copilot-instructions.md
- .github/instructions/ ディレクトリ内の複数ファイル
適用範囲
全てのチャットリクエストに自動適用される。
パス固有指示
対応している。

Copilot CLI

Copilot CLIでは、コマンドラインからの使用時にカスタム指示が適用される。

対応ファイル
.github/copilot-instructions.md

.github/instructions/*.instructions.md
適用範囲
全てのCopilot CLIコマンドに自動適用

優先度の階層

GitHub Copilotは、3層の優先度階層を持つカスタム指示システムを使用する。
優先度の高い順に以下に示す。

個人設定 (最高優先度)
ユーザ個人の設定

IDEの設定画面で定義する。
リポジトリ設定 (中程度優先度)
.github/copilot-instructions.md

プロジェクト全体に適用される。
組織設定 (最低優先度)
GitHub組織レベルの設定

これは、組織管理者が定義する。

重要な動作特性を以下に示す。

全ての適用可能な指示が組み合わされる
完全には置き換わらない。
優先度が高い指示が同じ領域をカバーしている場合、高優先度が優先される
例: 個人設定でインデントを4スペースに指定した場合、リポジトリ設定の2スペースは上書きされる。
矛盾しない指示は累積される
例: リポジトリ設定でコーディング規約を定義し、個人設定でエディタ設定を定義した場合、両方が適用される。

下表に、優先度の例を示す。

優先度の比較
設定レベル	定義場所	適用範囲	優先度
個人設定	IDE設定画面	ユーザ個人の全てのプロジェクト	最高
リポジトリ設定	.github/copilot-instructions.md	現在のリポジトリのみ	中程度
組織設定	GitHub組織設定	組織内の全てのリポジトリ	最低

競合が発生した場合の対処法を以下に示す。

優先度の高い設定を確認
どのルールが適用されているか確認する。
不要なルールを削除
競合するルールを削除または修正する。
個人設定で上書き
リポジトリ設定を変更できない場合、個人設定で一時的に上書きする。

適用の確認方法

VS Codeでの確認

VS Codeでは、以下に示す方法で copilot-instructions.md が適用されているか確認できる。

方法1 : Configure Instructions コマンド

Command Paletteから Chat: Configure Instructions を実行する。

[Ctrl] + [Shift] + [P]キー (Windows / Linux) または [Cmd] + [Shift] + [P]キー (MacOS) で Command Paletteを開く。
Chat: Configure Instructions を検索して実行する。
現在適用されているカスタム指示ファイルのリストが表示される。
.github/copilot-instructions.md がリストに含まれていれば、適用されている。

方法2 : チャット応答のReferencesセクション

GitHub Copilot Chatの応答には、使用されたファイルがReferencesセクションに表示される。

GitHub Copilot Chatを開く。
任意の質問を入力する。
応答の下部にある[References]セクションを確認する。
.github/copilot-instructions.md がリストに含まれていれば、適用されている。

確認時のチェックリスト

copilot-instructions.md が正しく適用されない場合、以下に示すチェックリストを確認する。

ファイルが正確なパスに存在するか
.github/copilot-instructions.md (大文字小文字の区別あり)
ファイル名に誤字がないか
copilot-instructions.md (ハイフンの位置、複数形のsに注意)
VS Codeの設定が有効になっているか
github.copilot.chat.codeGeneration.useInstructionFiles を確認する。
Markdown形式として有効か
構文エラーがないか確認する。
IDEを再起動したか
ファイル作成後、IDEを再起動する。

トラブルシューティングの手順を以下に示す。

ファイルパスを確認する。
ファイル名の誤字を確認する。
VS Code設定を確認する。
Markdown構文を確認する。
IDEを再起動する。
それでも問題が解決しない場合、GitHub Copilotの公式ドキュメントを参照する。

推奨される方法

効果的な copilot-instructions.md を作成するための推奨される方法を以下に示す。

リポジトリの概要を最初に記載

ファイルの冒頭には、リポジトリの目的、主要な機能、プロジェクトの背景を記述する。

記述例を以下に示す。

 # Project Overview
 
 This is a React-based e-commerce web application.
 It provides user authentication, product management, and payment features.

技術スタックを明示

使用している言語、フレームワーク、ライブラリ、ランタイムバージョンを明示する。

記述例を以下に示す。

 # Tech Stack
 
 - Language: TypeScript 5.0
 - Frontend: React 18.2
 - State Management: Zustand
 - Styling: Tailwind CSS
 - Testing: Jest + React Testing Library
 - Build Tool: Vite
 - Runtime: Node.js 20

ビルド、テスト、実行、lintコマンドを記載

頻繁に使用するコマンドを記録する。

記述例を以下に示す。

 # Commands
 
 - Development server: npm run dev
 - Build: npm run build
 - Test: npm test
 - Lint: npm run lint
 - Format: npm run format

プロジェクトレイアウトと主要ファイルの位置を説明

ディレクトリ構成と各ディレクトリの役割を説明する。

記述例を以下に示す。

 # Project Layout
 
 - src/components/: React components
 - src/pages/: Page components
 - src/hooks/: Custom hooks
 - src/store/: Zustand stores
 - src/utils/: Utility functions
 - tests/: Test files

コーディング規約を定義

命名規則、インデント、括弧、セミコロン、行の最大文字数などを定義する。

記述例を以下に示す。

 # Coding Standards
 
 - Variables and functions: camelCase
 - Components: PascalCase
 - Constants: UPPER_SNAKE_CASE
 - Indentation: 2 spaces
 - Max line length: 100 characters
 - Always use semicolons
 - Use single quotes for strings

エラーハンドリング要件を指定

エラー処理の方針、ログ出力、ユーザへのフィードバック方法を指定する。

記述例を以下に示す。

 # Error Handling
 
 - All async functions must have try-catch blocks
 - Error messages should be user-friendly
 - Log errors to console in development mode
 - Never expose sensitive information in error messages

テストカバレッジ目標を指定

テストの要件、カバレッジ目標、テストフレームワークを指定する。

記述例を以下に示す。

 # Testing Requirements
 
 - All new features require unit tests
 - Maintain 80%+ code coverage
 - Test edge cases and error conditions
 - Use Jest for unit testing
 - Use React Testing Library for component testing

機密情報を含めない

copilot-instructions.md ファイルには、機密情報を記載しない。

記載禁止の情報例を以下に示す。

パスワード
APIキー
シークレットトークン
データベース接続文字列
プライベートなIPアドレス
個人情報

機密情報は、以下のように管理する。

環境変数で管理
.env ファイルに記載する。
.gitignore に含めるする。
バージョン管理から除外する。
セキュリティのガイドラインのみを記載
具体的な値ではなく、管理方針を記載する。

セキュリティのガイドライン記述例を以下に示す。

 # Security
 
 - Never log passwords or API keys
 - Use environment variables for sensitive data
 - Validate all user inputs
 - Sanitize data before displaying to users

参考リンク