GitHub Copilot Instructionsファイル完全ガイド - プロジェクトに最適化されたAI補助を実現

はじめに

GitHub Copilotを使っていて、「プロジェクトのコーディング規約に沿った提案をしてほしい」「特定のフレームワークの書き方に統一したい」と感じたことはないでしょうか。デフォルトのCopilotは汎用的な提案を行いますが、Instructionsファイルを活用することで、プロジェクト固有のルールやガイドラインをAIに伝え、より適切なコード提案を得られるようになります。

本記事では、GitHub CopilotのInstructionsファイル機能について、公式ドキュメントに基づいて詳しく解説します。この記事を読むことで、以下のことができるようになります：

• Instructionsファイルの種類と役割を理解する
• .github/copilot-instructions.mdを作成してリポジトリ全体に適用する
• パス別のInstructionsファイルで言語やフレームワークごとにルールを設定する
• 実践的な記述例を参考に、自分のプロジェクトに適した設定を行う

Instructionsファイルとは

Instructionsファイルは、GitHub Copilotに対してプロジェクト固有のガイドラインやルールを伝えるためのMarkdownファイルです。チャットでプロンプトを入力するたびに同じ指示を繰り返す必要がなくなり、一貫性のあるAI応答を得られるようになります。

Instructionsファイルが解決する課題

通常のCopilot利用では、以下のような課題が発生しがちです：

• 毎回「Pythonで書いて」「TypeScriptのベストプラクティスに従って」などの指示を繰り返す必要がある
• プロジェクトのコーディング規約を知らないため、スタイルが統一されない
• フレームワーク固有の書き方（例：React Hooksのルール）を都度伝える手間がかかる
• チームメンバー間でCopilotの活用方法にばらつきが生じる

Instructionsファイルを導入することで、これらの指示を一度書いておけば自動的に適用されるようになります。

Instructionsファイルの種類

GitHub Copilotは複数の種類のInstructionsファイルをサポートしています。それぞれの特徴を理解して、適切に使い分けましょう。

リポジトリ全体のInstructionsファイル

最も基本的なInstructionsファイルは、.github/copilot-instructions.mdです。このファイルに記述した内容は、リポジトリ内でのすべてのCopilot Chat会話に自動的に適用されます。

作成手順

1. リポジトリのルートに.githubディレクトリを作成する（既に存在する場合は不要）
2. .github/copilot-instructions.mdファイルを作成する
3. 自然言語でガイドラインを記述する

1
2
3
4
5
6

# ディレクトリ構造
your-project/
├── .github/
│   └── copilot-instructions.md  # Instructionsファイル
├── src/
└── README.md

記述例：基本的なプロジェクトガイドライン

以下は、一般的なWebアプリケーションプロジェクトでの記述例です：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# プロジェクトコーディングガイドライン

## 言語とフレームワーク
- このプロジェクトはTypeScriptで記述されています
- フロントエンドはReact 18を使用しています
- バックエンドはNode.js + Expressです
- データベースはPostgreSQLを使用しています

## コーディング規約
- 変数名と関数名はcamelCaseを使用してください
- コンポーネント名はPascalCaseを使用してください
- インデントは2スペースです
- 文字列はダブルクォートではなくシングルクォートを使用してください

## Reactコンポーネント
- 関数コンポーネントとHooksを使用してください（クラスコンポーネントは使用しない）
- Propsの型定義にはinterfaceを使用してください
- useEffectの依存配列は必ず適切に設定してください

## エラーハンドリング
- try-catchブロックを使用してエラーを適切に処理してください
- ユーザー向けのエラーメッセージは日本語で記述してください
- ログ出力にはconsole.errorではなくロガーライブラリを使用してください

VS Codeでの設定

VS Codeで.github/copilot-instructions.mdを使用するには、設定で機能を有効にする必要があります：

1. VS Codeの設定を開く（Ctrl + , または Cmd + ,）
2. 「github.copilot.chat.codeGeneration.useInstructionFiles」を検索
3. チェックボックスをオンにする

または、settings.jsonに以下を追加します：

1
2
3

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

Instructionsファイルの自動生成

VS Codeでは、ワークスペースを分析して適切なInstructionsファイルを自動生成する機能があります：

1. Chatビューを開く
2. 歯車アイコン（Configure Chat）をクリック
3. 「Generate Chat Instructions」を選択
4. 生成された内容を確認し、必要に応じて編集する

この機能を使うと、プロジェクトの構造やpackage.json、既存のコードから自動的にガイドラインを抽出してくれます。

パス別のInstructionsファイル

プロジェクト内で異なる言語やフレームワークを使用している場合、パス別のInstructionsファイルが有効です。.github/instructions/ディレクトリ内に*.instructions.md形式のファイルを作成し、applyToプロパティでどのファイルに適用するかを指定します。

作成手順

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# ディレクトリ構造
your-project/
├── .github/
│   ├── copilot-instructions.md      # リポジトリ全体の指示
│   └── instructions/
│       ├── python.instructions.md   # Pythonファイル向け
│       ├── react.instructions.md    # Reactコンポーネント向け
│       └── testing.instructions.md  # テストファイル向け
├── src/
└── tests/

ファイル形式

パス別Instructionsファイルは、YAMLフロントマターとMarkdown本文で構成されます：

1
2
3
4
5
6
7
8
9

---
applyTo: "**/*.py"
---
# Pythonコーディングガイドライン

- PEP 8スタイルガイドに従ってください
- 型ヒントを必ず使用してください
- docstringはGoogle形式で記述してください
- インデントは4スペースを使用してください

applyToパターンの書き方

applyToプロパティには、globパターンを使用してファイルを指定します：

記述例：言語別の設定

Pythonファイル向け（python.instructions.md）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
applyTo: "**/*.py"
---
# Python開発ガイドライン

## スタイル
- PEP 8に準拠してください
- 1行の最大文字数は88文字（Black準拠）
- インポートはisortの規則に従って並べてください

## 型ヒント
- すべての関数に型ヒントを付けてください
- Optional型は`X | None`形式で記述してください（Python 3.10+）
- 複雑な型はtypingモジュールを使用してください

## ドキュメント
- 公開関数にはdocstringを必ず記述してください
- docstringはGoogle形式を使用してください

Reactコンポーネント向け（react.instructions.md）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
applyTo: "src/components/**/*.tsx"
---
# Reactコンポーネントガイドライン

## コンポーネント設計
- 関数コンポーネントのみを使用してください
- Propsはinterfaceで定義し、コンポーネント名+Propsという命名にしてください
- デフォルトエクスポートではなく名前付きエクスポートを使用してください

## Hooks
- カスタムHooksは`use`プレフィックスを付けてください
- useEffectのクリーンアップ関数を適切に実装してください
- 状態管理にはuseStateまたはuseReducerを使用してください

## スタイリング
- CSS Modulesを使用してください
- クラス名はcamelCaseで記述してください

テストファイル向け（testing.instructions.md）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
applyTo: "**/*.test.ts,**/*.spec.ts,**/tests/**/*.ts"
---
# テストコードガイドライン

## テストフレームワーク
- Jestを使用しています
- React Testing Libraryを併用しています

## 命名規約
- テストファイルは対象ファイルと同じ名前に`.test.ts`を付けてください
- describeブロックにはテスト対象の関数名やコンポーネント名を記述してください
- itブロックは「should」で始まる説明を記述してください

## アサーション
- expect文は1テストケースにつき1つを原則としてください
- モックは必要最小限に抑えてください
- 非同期テストではasync/awaitを使用してください

VS Code固有の設定

VS Codeでは、Instructionsファイル以外にも、設定（settings.json）を通じて特定のシナリオ向けの指示を設定できます。

コードレビュー用の指示

1
2
3
4
5
6
7

{
  "github.copilot.chat.reviewSelection.instructions": [
    { "text": "セキュリティの脆弱性を重点的にチェックしてください" },
    { "text": "パフォーマンスの問題を指摘してください" },
    { "file": ".github/review-guidelines.md" }
  ]
}

コミットメッセージ生成用の指示

1
2
3
4
5
6
7

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "text": "Conventional Commits形式で記述してください" },
    { "text": "日本語で記述してください" },
    { "text": "変更の理由を含めてください" }
  ]
}

プルリクエスト説明生成用の指示

1
2
3
4
5
6
7

{
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    { "text": "変更内容の概要を最初に記述してください" },
    { "text": "テスト方法を含めてください" },
    { "text": "破壊的変更がある場合は明示してください" }
  ]
}

優先順位と組み合わせ

複数のInstructionsファイルが存在する場合、GitHub Copilotはそれらを組み合わせて使用します。優先順位は以下の通りです：

1. 個人カスタム指示（最優先）
2. リポジトリ指示（.github/copilot-instructions.md）
3. 組織指示

また、パス別Instructionsファイルとリポジトリ全体のInstructionsファイルが両方存在する場合、両方の指示が組み合わされて適用されます。

競合の回避

異なるInstructionsファイル間で矛盾する指示を書かないように注意しましょう。例えば：

悪い例：

• copilot-instructions.md：「インデントは2スペースを使用してください」
• python.instructions.md：「インデントは4スペースを使用してください」

このような競合がある場合、Copilotの応答品質が低下する可能性があります。

良い例：

• copilot-instructions.md：一般的なプロジェクト情報のみを記述
• python.instructions.md：Python固有のルール（インデント4スペースなど）を記述

実践的な活用パターン

パターン1：マルチ言語プロジェクト

フロントエンドとバックエンドで異なる言語を使用するプロジェクトでの設定例：

1
2
3
4
5
6

.github/
├── copilot-instructions.md           # 共通情報（プロジェクト概要、アーキテクチャ）
└── instructions/
    ├── frontend-react.instructions.md   # applyTo: "frontend/**/*.tsx"
    ├── backend-python.instructions.md   # applyTo: "backend/**/*.py"
    └── infrastructure.instructions.md   # applyTo: "infra/**/*.tf"

パターン2：テスト駆動開発

テストファイルとプロダクションコードで異なる規約を適用：

1
2
3
4
5
6

.github/
├── copilot-instructions.md
└── instructions/
    ├── production-code.instructions.md  # applyTo: "src/**/*.ts"
    ├── unit-tests.instructions.md       # applyTo: "**/*.test.ts"
    └── e2e-tests.instructions.md        # applyTo: "e2e/**/*.ts"

パターン3：ドキュメント生成

ドキュメントファイル向けの特別な指示：

1
2
3
4
5
6
7
8
9

---
applyTo: "docs/**/*.md,**/*.mdx"
---
# ドキュメント作成ガイドライン

- 技術用語には初出時に説明を付けてください
- コードブロックには言語を必ず指定してください
- 見出しは##から始めてください（#はタイトルのみ）
- 画像にはalt属性を必ず設定してください

Instructionsファイル記述のベストプラクティス

効果的な記述のコツ

1. 簡潔かつ具体的に書く

   • 抽象的な表現よりも具体的なルールを記述する
   • 「良いコードを書いてください」→「関数は20行以内に収めてください」

2. 優先度の高い指示を最初に書く

   • 重要なルールから順に記述する
   • Copilotはファイル全体を読みますが、最初の内容をより重視する傾向があります

3. 例を含める

   • 「こう書いてください」という指示だけでなく、具体例を示す
   • 良い例と悪い例の両方を示すとより効果的

4. 定期的に更新する

   • プロジェクトの進化に合わせてInstructionsも更新する
   • 新しいライブラリを導入した際は、その使い方も追記する

避けるべきパターン

1. 長すぎる指示

   • Instructionsファイルは2ページ程度に収める
   • 詳細すぎる指示はかえって混乱を招く

2. タスク固有の指示

   • 「この機能を実装して」のような具体的なタスクは書かない
   • Instructionsは汎用的なガイドラインに留める

3. 矛盾する指示

   • 複数のファイル間で矛盾しないよう注意する
   • 定期的にレビューして一貫性を確認する

注意点と制限事項

インライン補完には適用されない

Instructionsファイルの内容は、Copilot Chatには適用されますが、エディタ上でのインライン補完（グレーのゴーストテキスト）には適用されません。インライン補完の動作をカスタマイズするには、別のアプローチが必要です。

ファイルサイズの制限

Instructionsファイルが大きすぎると、コンテキストウィンドウを圧迫し、Copilotの応答品質に影響を与える可能性があります。目安として2ページ（約2000語）以内に収めることが推奨されています。

セキュリティ上の考慮

Instructionsファイルはリポジトリにコミットされるため、以下の点に注意してください：

• 機密情報（APIキー、パスワードなど）を含めない
• 社外秘のビジネスロジックの詳細を書かない
• 公開リポジトリでは特に注意する

まとめ

GitHub CopilotのInstructionsファイルは、プロジェクト固有のコーディング規約やガイドラインをAIに伝えるための機能です。適切に設定することで、以下のメリットが得られます：

• チャットで毎回同じ指示を繰り返す手間が省ける
• プロジェクト全体で一貫性のあるコード提案を得られる
• チームメンバー間でCopilotの活用方法を統一できる
• 言語やフレームワークごとに適切なルールを適用できる

まずは.github/copilot-instructions.mdにプロジェクトの基本情報を記述することから始め、必要に応じてパス別のInstructionsファイルを追加していくことをおすすめします。Copilotの提案品質が向上し、開発効率がさらに高まるはずです。

参考リンク

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Use custom instructions in VS Code - Visual Studio Code Docs
• Custom instructions - GitHub Copilot Customization Library
• Awesome Copilot Repository