Copilot Instructions mdの書き方とは？正しい導入と設定方法を徹底解説！

2026年9月26日

GitHub Copilotを導入してみたものの、「生成されるコードの書き方が自分のチームのコーディング規約とちょっと違っている…」「質問をした時の返答が英語で返ってきてしまって戸惑った…」という苦い経験はありませんか。開発作業をスムーズに進めるためには、自分たちが所属するプロジェクトのルールや開発環境に合わせたコードを、AIに的確に出力してほしいなと感じるシーンも多いかなと思います。

そんな時に大活躍してくれるのが、リポジトリ全体の開発ルールやコンテキスト設定を一括して記述できる指示ファイルです。この記事を最後まで読めば、設定ファイルの基本的な役割から正確な保存ディレクトリの配置ルール、VS Codeでの設定有効化手順まで、迷わずに実践できるようになりますよ。

設定ファイルの概要と正しいディレクトリ配置ルール
Chat機能やインライン補完における適用範囲の明確な違い
AIの精度を極限まで高めるための効果的なプロンプトと記述の工夫
実際のチーム開発でそのまま役立つ具体的で実践的なテンプレート例

初心者でもわかるCopilot Instructions mdの基本的な書き方

GitHub Copilotに対して、自分たちのプロジェクト固有のルールやコーディング規約をスムーズに伝えるための基本的な仕組みと、最初に押さえておきたい設定の基礎知識についてわかりやすく丁寧に解説していきます。

設定ファイルの正しい保存場所と配置パスのルール

GitHub Copilotに対してリポジトリ独自の実装指示やコンテキスト情報を自動的に読み込ませるためには、設定ファイルの設置場所（ディレクトリ構造）を正確に指定してあげる必要があります。設定ファイル名は必ず copilot-instructions.md とし、プロジェクトの最上位層であるルートディレクトリ直下に作成した .github フォルダの内部に配置しなければなりません。

開発現場で初心者が非常によくハマってしまう間違えやすいポイントとして、設定フォルダ名をエディタ関連の「.vscode」フォルダにしてしまったり、ファイル名の末尾にある複数形の「s」をうっかり忘れて「copilot-instruction.md」と命名してしまうケースが後を絶ちません。AIツールはこれらのパス名を厳密に判別しているため、フォルダ名やファイル名が1文字でも異なっていると、Copilotが設定の存在を全く認識できなくなってしまいますので十分注意してくださいね。

正しい配置パスの構造：

[リポジトリのルートディレクトリ]/.github/copilot-instructions.md

このファイル配置を一度正しく完了させておけば、リポジトリを開いてCopilot Chatを利用する際に、バックグラウンドで自動的にファイルの内容が読み込まれるようになります。チーム開発においては、このファイルをGitの管理対象に含めてコミット・プッシュしておくことで、プロジェクトに参加するメンバー全員が全く同じCopilotの設定環境やレスポンス品質を共有できるようになるのも大きなメリットですね。

基本的な記述形式とMarkdownを活用した構文

カスタム指示ファイルの記述フォーマットには、エンジニアにとって馴染み深い標準的な Markdown（マークダウン） 形式を使用します。見出しタグ（#や##）やリスト項目（- や *）を適切に活用しながら、AIが指示の全体像や論理構造をコンテキストとして理解しやすいように整理して記述するのが重要なコツになります。

文章を書く際は、「なるべく綺麗に書いてください」といったあいまいなニュアンス表現を避け、具体的かつシンプルな短い文章で条件を提示することが大切になります。見出しを使ってカテゴリごとにセクションを明確に分けておくことで、どのルールが言語設定に関するもので、どのルールがセキュリティ規約に関するものなのかをAIが正確に識別できるようになります。

基本的な記述例：

対話言語と基本スタイル

Copilot Chatからの返答はすべて「日本語」で行ってください。
解説は専門用語を噛み砕き、初心者にもわかりやすい丁寧なトーンを維持してください。

コーディング規約と型定義

変数名および関数名には camelCase を使用してください。
TypeScript の any 型の使用は原則禁止とします。不明な型には unknown またはジェネリクスを使用してください。

このように見出しと箇条書きをセットで構成することによって、LLM（大規模言語モデル）のトークン解析時における関連性が強化され、指示の読み飛ばしや解釈のブレを大幅に減らすことが可能になります。Markdownの記法をフルに活かして視認性の高いドキュメント作成を意識してみましょう。

インライン補完とChat機能における反映範囲の明確な違い

設定ファイルを作成・運用していく上で、開発者が一番誤解しやすくトラブルの原因になりやすいのが「Copilotのどの機能にこのルールが適用されるのか」という適用範囲の問題です。結論から言うと、カスタム指示が適用されるのは、主に Copilot Chat Panel や インラインチャット（Cmd+I / Ctrl+I）、各種 Agent Mode（Copilotエージェントの機能と活用例）といった対話型のワークフロー機能に限られます。

一方で、コードエディタ上でソースコードをタイピングしている最中に自動的にグレーの薄い文字で提案表示される「インラインコード補完」には、この copilot-instructions.md の設定内容は直接反映されません。これはインライン補完機能がキー入力ごとに数百ミリ秒というミリ秒単位の超高速なレスポンス（ローレイテンシ）を要求されるため、重いシステムプロンプトやMarkdownファイルのリアルタイム読み込み処理が意図的にスキップされる設計仕様になっているからです。

エディタ上のリアルタイピング補完で指示が反映されないのはGitHub Copilotの正常な仕様です。作成したルールの動作テストを行う際は、エディタ上の補完ではなく、必ず Copilot Chat のサイドバーウィンドウやインラインチャット画面にプロンプトを送信して確認を行うようにしましょう。

もしインライン補完の精度自体をコントロールしたい場合は、指示ファイルに頼るのではなく、開いているタブの周辺コードやコメント文（JSDocやDocstringなど）を充実させることが有効なアプローチとなります。機能ごとの役割と仕組みの違いをしっかり把握しておくと、無駄な試行錯誤を減らせますね。

指示が効かない・反映されない場合の解決手順と設定確認

指示ファイルを正しく配置して内容を記述したはずなのに、「Chatの返答が英語のままになってしまう」「指定した命名規則と異なるコードが提案される」といった問題が発生した場合は、焦らずに以下のステップで原因を特定・解消していきましょう。

最初に絶対確認したいのが、Copilot Chatで質問メッセージを送信した際のレスポンス画面です。AIが生成した回答文のすぐ上部に表示されている「Used references（参照されたコンテキスト）」というアコーディオン要素を展開し、その一覧の中に .github/copilot-instructions.md が含まれているかどうかをチェックしてください。ここにファイル名が表示されていれば、 Copilotはファイルを正しく認識・読み込みできています。

もし参照一覧にファイルが表示されているにもかかわらず指示に従ってくれない場合は、記述されているプロンプトの量が多すぎて重要度の高い制約が埋もれてしまっている（いわゆる指示の希薄化が起きている）可能性が高いです。ダラダラとした長文エッセイのような記述をやめ、短文の箇条書きに整理し直したり、制約条件の前に「MUST」などの強い強調メッセージを添えるといった改善を試してみてください。

トークン数を削減し精度を落とさない記述の工夫

AIに対して「完璧なコードを出力させたい」という思いから、指示ファイルの中に大量のルールや長大なコード例を詰め込みすぎてしまうケースがよくあります。しかし、入力するトークン数が無駄に増えてしまうと、AIのコンテキスト処理における「注意（Attention）」の意識が分散してしまい、結果として重要なルールを守らなくなってしまう現像が起こります。

このような精度低下を防ぎ、応答速度と生成クオリティを両立させるためには、ファイル全体としての記述量を 500〜600トークン程度（日本語換算で約1,000文字前後）のスリムなボリュームに収めるのがベストな設計とされています。

トークン効率と理解精度を高める3つの工夫：

視覚的な装飾用の絵文字や装飾用のアスキーアート、無駄な挨拶文はすべて削ぎ落とす
外部WebサイトのURLをそのまま記載するのではなく、必要なルールの核心だけを1〜2行の文章に要約して書く
「〜は使わないこと」というネガティブな禁止形だけで終わらせず、「〜を避け、代わりに…を使用すること」と具体的な代替案をセットで提示する

AIへの指示は、人間に対する指示書と同様に「簡潔・明瞭・具象的」であることが何より重要です。無駄な文脈を徹底的に削ぎ落とすチューニングを行って、常に高い精度でレスポンスを返してくれるスマートな指示ファイルを目指しましょう。

現場で役立つCopilot Instructions mdの実践的な書き方

ここからは、実際のソフトウェア開発現場ですぐに導入・活用できる実践的な設定テンプレートや、規模の大きなチーム開発でスムーズに運用していくための発展テクニックについて深掘りして解説していきます。

コーディング規約や命名ルールを明確に定義する方法

Copilotにプロジェクト全体の統一感や一貫性を持った高品質なコードを生成させるためには、チーム内で採用している命名規則（ネーミングコンベンション）やファイル構成の規約を明確に指示文として宣言しておくことが非常に効果的です。

クラス名、関数名、変数名、定数名といった各種識別子の記法スタイルがあらかじめ細かく指定されていれば、AIが生成したソースコードを手動でリファクタリングして修整する無駄な手間を最小限に抑えられます。（出典：デジタル庁『標準ガイドライン』）

命名ルールの実践的な記述テンプレート：

命名規約の定義

クラス名、インターフェース名、型定義（type）：PascalCase を使用してください。（例: UserProfile, PaymentGateway）
関数名、変数名、メソッド名：camelCase を使用してください。（例: fetchUserData, isApproved）
定数、環境変数、列挙型（Enum）：UPPER_SNAKE_CASE を使用してください。（例: MAX_RETRY_COUNT, API_BASE_URL）
コンポーネントファイル名：kebab-case または PascalCase をプロジェクト構造に合わせて統一してください。

さらに、単なる命名規則だけでなく「省略形（例えば user ではなく u と書くなど）の短縮変数は避け、意図が伝わる説明的な変数名をつけること」といった品質面の補足ルールを追加しておくと、読者やチームメンバーにとって保守しやすい綺麗で洗練されたコードが自動生成されるようになりますよ。

使用する言語やフレームワークのバージョンを指定する手順

GitHub CopilotなどのLLMは、インターネット上の広大な学習データに基づいて一般的なコードを生成するのが得意な反面、ライブラリや言語の「バージョンアップに伴う仕様変更・非推奨化（Deprecation）」には注意が必要です。古いバージョンの構文や、現在では非推奨となった記法をAIが無自覚に出力してしまうケースも少なくありません。

これを未然に防ぐためには、プロジェクトで現在使用しているプログラミング言語やフレームワーク、ツールチェーンの具体的なバージョン情報を指示ファイル内でハッキリと明記しておく必要があります。

<tr>

  <th>管理対象</th>

  <th>指示ファイルでの設定記述例</th>

  <th>得られる具体的な導入効果</th>

</tr>

<tr>

  <td><strong>プログラミング言語</strong></td>

  <td>TypeScript 5.x / Python 3.11+</td>

  <td>最新の型判定処理やパイプライン演算子など、パフォーマンスに優れた現代的な構文を出力させることができます。</td>

</tr>

<tr>

  <td><strong>Webフレームワーク</strong></td>

  <td>Next.js 15+ (App Router前提)</td>

  <td>Pages Routerなどの古いディレクトリ構造や、非推奨となったレガシーなデータ取得フックの出力を強力に防止します。</td>

</tr>

<tr>

  <td><strong>パッケージマネージャー</strong></td>

  <td>pnpm / uv / yarn (v4)</td>

  <td>一般的な npm install や pip install ではなく、プロジェクトで推奨されているパッケージ管理コマンドを提案させます。</td>

</tr>

<tr>

  <td><strong>UIライブラリ</strong></td>

  <td>Tailwind CSS v3.4 / React 19</td>

  <td>最新のユーティリティクラスやフック（useActionState等）を考慮した、最新トレンドに準拠したコンポーネントコードが生成されます。</td>

</tr>

上記のようにバージョンと合わせて「〇〇機能（App Routerなど）を優先的に使用すること」という方向性まで示しておくことで、コード生成のミスマッチを大幅に軽減でき、手戻りのないスムーズな開発が実現できます。

MustやShouldの条件指定で指示の優先度を高める技法

指示ファイルに複数のルールを並べて記載する際、すべての指示を同じ強さで書いていると、AIがどのルールを最優先で遵守すべきなのか判断に迷ってしまうことがあります。そこで活用したいのが、RFC 2119などの標準仕様でも用いられている優先度指定キーワードを取り入れた記述アプローチです。

プロジェクトにおいて「絶対に違反してはならないセキュリティルールや必須規約（MUST）」と、「可能であれば遵守してほしい推奨マナー（SHOULD）」を論理的に区別して提示してあげましょう。

MUST（必須要件）： 絶対に例外を認めない最優先ルール。「〜しなければならない」「〜である必要がある」という強固な制約。（例: 公開するすべての関数には戻り値の型アノテーションをMUSTで付与すること）
SHOULD（推奨要件）： 特別な事情がない限り原則として守るべきルール。（例: 1つの関数内の行数はSHOULDで40行以内に収めること）
MUST NOT（絶対禁止要件）： システムの脆弱性や致命的なバグに繋がる明確なアンチパターン。（例: any型の使用、eval()の実行、パスワードのハードコーディングはMUST NOTとする）

このように英語の優先度記号を文頭に付与したり、意味合いを強調して記載することで、AIモデル内部の評価スコアが補正され、重大なルール違反を劇的に減らすことが可能になります。

モジュールや用途別にファイルを複数分割して管理する手法

フロントエンド（React/Vue）とバックエンド（Node.js/Go）が単一のソースコードリポジトリに同居しているモノレポ構成などのプロジェクトでは、すべての領域のルールを1つの copilot-instructions.md に詰め込んでしまうと、コンテキストの混乱やトークン上限オーバーの原因になってしまいます。そのようなケースでは、特定ディレクトリ配下のファイルにのみ適用される個別ルールファイルを別に作成・分割管理する手法が推奨されます。

ファイルの配置場所は .github/instructions/ ディレクトリ内とし、ファイル名の末尾を .instructions.md という形式にするのが規約です。さらに、分割ファイルの冒頭部分（フロントマター）に対して、ルールを適用したい対象のファイルパスをGlob（グロブ）パターンで指定するのが大きな特徴となります。

.github/instructions/react.instructions.md の具体的な記述例：

—

applyTo: ‘src/components/**/*.{ts,tsx}’

—

Reactコンポーネント固有ルール

コンポーネントはすべてアロー関数（const ComponentName = () => {}）形式で定義してください。
Propsの型定義には type ではなく interface を使用し、Exportを行ってください。
スタイリングにはインラインスタイルを使用せず、Tailwind CSSのクラスのみを使用してください。

この高度な分割機能を活用することで、開発者が「コンポーネント用のファイル」を編集してCopilot Chatと会話している時だけReact専用ルールが自動的に読み込まれるようになり、トークン消費を最小限に抑えながら極めて精度の高いコンテキスト応答を実現できます。

VS Codeの設定画面から機能を有効化する手順

どれだけ素晴らしい copilot-instructions.md ファイルを作成・配置したとしても、開発環境であるエディタ（VS Code）側で「カスタム指示ファイルの読み込み機能」が有効化されていなければ、設定は一切反映されません。必ず開発を始める前にエディタ側の設定状態を確認しておきましょう。

作業手順としては、まずVS Codeの環境設定画面（ショートカットキー: Windows/Linuxは Ctrl + ,、macOSは Cmd + ,）を開き、上部の検索バーに github.copilot.chat.codeGeneration.useInstructionFiles という設定キーを入力します。表示された項目のチェックボックスが「オン（有効）」になっていることを確認してください（VS CodeでのAI連携設定ガイドも併せて参照してみてください）。

チーム全員の設定を強制的に統一したい場合や、リポジトリ単位でこの機能を確実にONにしておきたい場合は、プロジェクト直下の .vscode/settings.json ファイルに対して以下の設定JSONコードを直接追記しておくのが最も確実で安全な方法になります。

{

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

}

この設定がコードベースに含まれていれば、新しいエンジニアがプロジェクトをクローンしてVS Codeで開いた瞬間に、自動的に指示ファイルの読み込み機能が有効になり、環境構築の手間を大きく削減することができますね。

初心者でも簡単に行えるCopilot Instructions mdの書き方まとめ

今回の記事では、GitHub Copilotの出力結果やレスポンス品質を劇的に向上させるための copilot-instructions.md の正しい配置ルール、効果的なMarkdownの書き方、そして実務で使える実践テクニックについて詳しく解説してきました。

最初から完璧なルール集を作ろうと気負う必要はありません。まずは「AIからの回答を日本語にする」「主要な命名規則（camelCaseなど）を指定する」といったシンプルな3〜4行程度の記述からスタートしてみるのがおすすめです。使いながらチーム内で違和感のあった部分を追加・アップデートしていき、慣れてきたらモジュールごとのファイル分割や詳細な規約定義にチャレンジしてみてくださいね。

プロジェクトの特性にしっかりとマッチしたカスタム指示ファイルを育て上げて、ストレスのない快適で生産性の高いAIコーディング環境を構築していきましょう！

この記事を書いた人

ai-master

エンジニア歴 12 年・Web マーケター歴 4 年・ブログライター歴9年。エンジニア兼マーケターの視点から AI ツール活用に取り組んでいます。
AI-Rise では、NotebookLM・Claude Code・Google AI Studio・Gamma などの主要 AI ツールについて、機能・料金・使い方・エラー解決といった実用情報を整理して発信。新しいツールが登場するたびに調べ、初心者がつまずきやすいポイントを噛み砕いて記事にすることを意識しています。