GitHubでCopilotのinstructionsを使いこなす実務設計ガイド

GitHub Copilotを1年使っても「結局すべて自分でレビューし直している」なら、その原因の大半はCopilotの能力ではなく、copilot-instructions.md と .instructions.md の設計ミスにあります。精度が安定しないチームほど、instructionsを「プロジェクト紹介文」と「スローガン」の寄せ集めにしており、現場で本当に守ってほしいルールがCopilotに届いていません。

同じリポジトリでも、開発者によってCopilotの提案がまったく違うのはなぜか。レガシーとモダンが混在しているのに「このプロジェクトはReactとTypeScriptです」とだけ書いているせいで、jQuery画面にまでReact化提案が飛んでくるのはなぜか。VS CodeのUser Data側の設定と、リポジトリ配下のinstructionsが衝突して、誰の指示が優先されているのか分からなくなるのはなぜか。これらはすべて、instructionsの構造設計を間違えた結果として必然的に起きています。

この記事は、「github copilot instructions」の一般的な解説ではなく、実務で成果が出る設計と運用だけを扱います。
抽象論ではなく、次のような具体を扱います。

• copilot-instructions.md と複数の .instructions.md をどう分担させるか
• applyToやパス設計をどこまで細かく切るか、その境界線
• VS Codeのchat.instructionsFilesLocationsをどう設定すればノイズを抑えられるか
• PRレビューでinstructionsをどう扱えば、チーム全体で精度を底上げできるか
• あえて「レガシー置き場をCopilot非対象にする」など、instructionsを減らした方が安全な条件

最終的に、あなたが得るのは「Copilotを信用して任せられる領域がどこまでか」と「その前提として必要なinstructions設計の型」です。レビュー工数を減らしつつ、テスト生成や定型実装をほぼ自動化するための、現場レベルの設計指針をまとめています。

この記事全体のロードマップは次の通りです。

Copilotの賢さを上げることはできませんが、「どの状況でどう振る舞うか」はinstructions設計でかなりの範囲まで制御できます。この記事を読み進めれば、「Copilotに任せられる行単価」が一段階上がり、チーム全体の開発フローが静かに楽になります。

「Copilotが使えない」の9割は instructions 設計ミス：まず何が起きているか見抜く

「Copilot入れたのに、むしろレビュー工数が増えた」。
その違和感のほぼ全ては、「エディタの設定」ではなくinstructionsの設計と運用に原因がある。
ツールの出来を疑う前に、まず「何が起きているのか」を分解してみる。

同じプロジェクトなのに人によってCopilotの回答がバラバラになる理由

同じリポジトリなのに、メンバーごとに出てくる提案が違うのは、次の3層がバラバラに効いているからだ。

テックリードが「Reactで書いて」と思っていても、個人のUser Dataに「Vueが好き」「プロトタイピングはjQueryでも可」と書かれていれば、Copilotは“どちらも正しい”と判断して揺れる。
さらに、リポジトリ自体のコードスタイルがディレクトリごとにバラバラだと、Copilotは「どれが正だろう？」と迷い、無難な汎用コードを出しやすくなる。

ポイントは、instructionsの矛盾＋既存コードの一貫性不足がセットになると、回答が人ごとに分裂するという構造だ。

ありがちな現場トラブル3選（別フレームワーク提案・規約無視・テスト忘れ）

Copilotを1年ほど使っているチームで、ほぼ必ず出るトラブルを3つに絞るとこうなる。

• 別フレームワーク提案地獄

  copilot-instructions.md には「このプロジェクトはモダンなWebアプリです。TypeScriptとReactを使います。」とだけ書いてある一方、実リポジトリにはjQueryベースのレガシー画面が大量に残っているケース。
  Copilotは「モダン＝React」が正と学習し、レガシー画面の軽修正にも毎回React化やSPA化を提案してくる。

• コーディング規約ガン無視問題

  instructionsに「Airbnbスタイルを参考」とだけ書いて、チームの例外ルール（命名規則、DTOの置き場、エラーハンドリング方針）がどこにも明文化されていない状態。
  Copilotは公式例に寄せるが、リポジトリに混在した古い書き方も参照するため、PRごとにスタイルが微妙に違うコードを量産する。

• テスト忘れを助長する補完

  テスト戦略をinstructionsに一切書いていないと、「テストを書かないチーム」と誤認されがちだ。
  結果として、Copilotは実装コードだけを厚く提案し、テストコードは「コメントだけ生成」レベルに留まりやすい。

どれも、「Copilotの出来が悪い」というより、チームがCopilotに渡した“設計メモ”が薄いか矛盾しているだけのパターンが多い。

公式ドキュメントだけでは埋まらない“設計のグレーゾーン”とは

GitHub公式ドキュメントは、ファイル名や配置場所、applyToの仕様までは丁寧に書いてある。
ただ、現場で一番悩むのは、次のような「設計のグレーゾーン」だ。

• レガシーとモダンが混在するとき

  • どこまでを「モダン化対象」としてCopilotに任せるか
  • 「ここから下は触るな」と線を引くか

• 個人のUser Dataとリポジトリのinstructionsの優先度

  • どこまで個人の好みを許容し、どこからチーム規約で上書きするか

• .instructions.md をどれくらい分割するか

  • パスごとに細かく分けるか
  • 「コア1枚＋例外だけ分割」にするか

ここを決めないまま書き始めると、“なんでも書いてあるけど、何も決まっていないinstructions”が量産される。
実務で成果を出しているチームは、まず最初に軽い「リポジトリ診断」を入れている。ディレクトリ構成の癖やコードスタイルのバラつきをざっと洗い出し、「Copilotにどの層まで任せるか」「どこは人間のレビューで絶対見るか」を線引きしたうえでinstructionsを書き始める。

この一手間を挟むだけで、「Copilotが敵に見える状態」から、「チームの意思決定をなぞってくれる相棒」に一段階引き上がる。

copilot-instructions.md と .instructions.md の本当の役割分担を整理する

「Copilotに“プロジェクトの常識”を叩き込むか、“このフォルダの流儀”を教えるか」。ここを混ぜると、一気にカオスになります。この章では、テックリードが設計判断に迷わないための境界線をはっきり引きます。

GitHubリポジトリ全体に効く「copilot-instructions.md」の守備範囲

copilot-instructions.md は、リポジトリの憲法と考えると分かりやすいです。ここには「例外のないルール」だけを書くのが鉄則です。

書くべき内容を、実務寄りに整理すると次の通りです。

• 技術スタックの前提（例: backendはPython、frontendはReact＋TypeScript）

• コード規約と命名戦略（例: APIレスポンスはCamelCase、DBカラムはsnake_case）

• テスト方針（例: backendはpytest必須、ReactはTesting Library推奨）

• 禁止事項（例: 新規コードでjQuery禁止、認証まわりの独自実装禁止）

逆に、パス依存の話や例外ルールは書かない方が安定します。ここに「/legacy 以下だけPHP 5系」「/admin はBlade」といった情報まで詰め込むと、Copilotが「どの指示が優先か」を判断しづらくなり、補完がブレやすくなります。

パス別・レイヤ別に効かせる .instructions.md の設計思想

.instructions.md は、ディレクトリ単位のローカルルールを教えるための仕組みです。テックリード視点で押さえたいポイントは3つあります。

• 責務は“このフォルダの世界観”に限定する

• applyToで適用範囲を狭く切る

• 1パス1コンテキストに絞る

よくある失敗は、src/ 直下に1枚だけ置いて「フロントもバックもテストも全部そこに書く」パターンです。これをやると、Reactコンポーネントを書いているのにpytestの話が混じる、といったノイズが増えます。

理想は、次のような分割です。

• src/frontend/.instructions.md

  → UIコンポーネント設計、React Hooksの方針、UIテストの書き方

• src/backend/.instructions.md

  → ドメイン層とAPI層の分離、例外処理、ログの出し方

• tests/.instructions.md

  → テストデータの生成ルール、モック方針、カバレッジの目標

パス設計を変える前に、既存ディレクトリ構成の癖を診断する“リポジトリ健康診断”を一度挟むと、instructionsの粒度を決めやすくなります。

.agent.md や AGENTS.md との関係を「現場目線」でどう切り分けるか

ここを曖昧にすると、「Copilotはコードを書くAIなのか、タスク管理をするAIなのか」がボヤけます。現場での切り分けは次のテーブルが分かりやすいです。

実務上は、コードの“どう書くか”は instructions、タスクの“何をさせるか”は agentと分けるのが扱いやすいです。

例えば、PRレビューエージェントなら .agent.md に次のような方針だけを書くとシンプルです。

• 参照すべき instructions ファイルのパス

• レビューの観点（型安全性、パフォーマンス、セキュリティなど）

• コメントスタイル（指摘だけか、修正案コードも含めるか）

この分離を徹底すると、「Copilotに書かせるコードの質」と「Copilotに任せるタスクの質」を別々にチューニングできるようになり、テックリードがレビューで抱えている「全部自分で見直している感」をかなり減らせます。

ダメな instructions テンプレに共通する3つの罠と、その直し方

Copilotが「賢くない」のではなく、こちらが“読めない仕様書”を渡しているだけのケースが多い。特にテンプレをコピペして作った instructions は、ほぼ例外なく次の3パターンにハマる。

抽象論だらけで「このプロジェクト固有の情報」がほぼ書かれていない

「高品質なコードを書いてください」「クリーンアーキテクチャを意識してください」──この種の文言だけ並んだ instructions は、Copilotから見るとどのリポジトリにも当てはまる“凡庸なノイズ”に近い。

Copilotが本当に欲しがっているのは、次のようなリポジトリ固有の“現場ルール”だ。

• 使用フレームワークのバージョンと混在状況

  例: React 18＋旧jQuery画面が /legacy 配下に残っている

• コーディング規約の差分情報

  例: ESLintはAirbnbベースだが、import順だけ独自ルール

• 「このディレクトリだけは例外」情報

  例: /experimental は型安全よりスピード優先でよい

修正のコツは、「このリポジトリを他人に引き継ぐときに、最初の30分で必ず口頭で伝えること」をすべて instructions 側に書き出すこと。抽象論を削り、“このプロジェクトならでは”しか残さないのが設計のスタートラインになる。

リンクとスローガンだらけで、Copilotからすると何を守ればいいか分からない

よくあるのが、次のようなテンプレ化パターン。

• 社内コーディング規約のURLだけ羅列

• 「ドメイン駆動設計を意識する」「テストファーストを徹底する」といったスローガンの連打

• 「詳細は Confluence を参照」のような丸投げ

LLMはリンク先を勝手に開けないため、URLだけでは“中身ゼロ”とほぼ同義になる。さらにスローガンが多いほど、Copilotは解釈の余地が大きい曖昧なルールを優先してしまい、「テストファーストっぽく見えるが、実プロジェクトとはズレた提案」を返しがちだ。

リンク主体テンプレを直すときは、URLを「要約付きアンカー」に変換するイメージを持つと整理しやすい。

Copilotにとって重要なのは「何を」「どのパスで」「どう振る舞わせたいか」であり、スローガンや素のURLではそこに到達できない。

パス指定・applyToの設計ミスで、意図しないディレクトリまでルールが漏れ出す

Copilot instructionsの運用で、一番レビュー工数を溶かすのがこの罠だ。

• backend向けのルールが、frontendの /src/components にも適用される

• レガシーな /legacy 配下にも最新アーキテクチャの提案が入り込む

• 一部の .instructions.md が階層構造的に想定より広いdirectoryにマッチしてしまう

原因はシンプルで、applyToやpathマッチの設計が雑なことが多い。

頻出ミスと直し方をまとめるとこうなる。

設計の目安として、「この instructions は、最終的にどの directory に作用するか」をホワイトボードに書き出してからファイルを分割すると、漏れ出し事故が激減する。

Copilotに渡しているのは“設定ファイル”ではなく、レイヤ別の「役割定義書」だと捉えると、applyToの粒度をどこまで削るべきか判断しやすくなる。

現場で実際に起きうるケーススタディ：失敗→修正で Copilot の挙動はこう変わる

「Copilotのせいでレビュー工数が増えた」か、「Copilotのおかげでレビューが楽になった」かを分けるのは、スキルではなく instructions の設計と運用だ。ここでは、テックリードが実際にハマりやすい3パターンを、ビフォー/アフターで解像度高く切り分ける。

フロントはReact、管理画面はBlade――混在環境でinstructionsを一枚岩にした失敗例

よくあるのが、次のような copilot-instructions.md をリポジトリ直下に1枚だけ置いたケース。

• 「本プロジェクトはモダンなWebアプリです。TypeScript + Reactで実装してください」

• 実際の構成は src/frontend/ が React、src/admin/ は jQuery + Blade テンプレート

この状態だと、src/admin/ で Blade を触っていても、Copilotはひたすら Reactコンポーネント化の提案を返してくる。開発者側は「いや、ここはLaravelのBladeなんだけど…」と毎回打ち消す羽目になり、Copilotの信頼度が一気に落ちる。

ここでは instructions の粒度と適用範囲を分解すると一気に楽になる。

修正後のイメージはこうなる。

• copilot-instructions.md

  • 「本リポジトリには React/TypeScript と Laravel/Blade が混在する」
  • 「src/frontend/ はReact、src/admin/ はBladeベースを維持する」

• src/frontend/.instructions.md

  • 「React + TypeScriptで実装」
  • 「UIコンポーネントは /src/frontend/components を再利用」
  • 「テストは React Testing Libraryで」

• src/admin/.instructions.md

  • 「Bladeテンプレートと既存のjQueryプラグインを優先」
  • 「Reactへの書き換え提案は行わない」

このレベルまで書き分けると、Copilotは 同じリポジトリ内でもパスに応じてモードを切り替える。
「モダンにしたい理想」を書くのではなく、「今このディレクトリでやってほしい現実」を書くのがポイントになる。

テストコードの自動生成が“ほぼ当たり”になった instructions の書き換えポイント

テスト自動生成でハマるパターンは、「テストを書け」と書いているだけで テストの“型”を指定していない状態だ。

ありがちな失敗は次のような記述。

• 「テストコードも必ず生成してください」

• 「ユニットテストを忘れないこと」

これだとCopilot側は、Jestなのか PHPUnitなのか、テストディレクトリ構成はどうなっているのかを推測するしかない。その結果、プロジェクトの実態と違うテストランナーや import パスが紛れ込み、結局テックリードが直すことになる。

改善のコツは、テストだけは 「コンパイルが通る最低限のスケルトン」を明文化すること。

特に効きやすいのは次の3点。

1. テストファイルのパスと命名規則

   • 例: src/components/Button.tsx に対して tests/components/Button.test.tsx を生成する、のように「対応関係」を書く。

2. 利用するテストランナー・アサーションライブラリ

   • Jest / Vitest / PHPUnit のどれかを、1つに固定して明記。

3. モック方針

   • 「外部API呼び出しは __mocks__ ディレクトリの共通モックを使う」など、既存のモック戦略を指定。

instructionsをここまで具体化すると、Copilotの提案は テストレビューの足がかりとして“ほぼ当たり”になり、「ゼロから書く」から「肉付けする」作業に変わる。

User Dataの個人設定とリポジトリ命令が衝突したときの典型パターン

Copilotを1年ほど使っているテックリードほどハマりやすいのが、User Data 配下の instructions とリポジトリ内 instructions の衝突だ。

例えば、個人側の User Data に次のような設定を入れているケース。

• 「バックエンドは基本的にPython + FastAPIで提案する」

• 「テストはpytestで生成する」

一方、チームのリポジトリは Laravel + PHPUnit が標準。copilot-instructions.md ではLaravel前提でルールを書いているのに、個人設定が強く効きすぎてPython提案が混ざる、という現象が起きる。

現場で見分けるサインはシンプルだ。

• そのリポジトリに存在しない言語・フレームワークの提案が頻出する

• composer.json があるのに requirements.txt を作ろうとする

• ほかのメンバーでは再現しない提案が、自分の環境だけで出る

この状態を放置すると、「Copilotの挙動が人によってバラバラ」になり、レビュー基準も揺れる。

対処の順番は次のとおり。

1. User Data側を「好み」ではなく「超ミニマルな汎用ルール」に縮小

   • 例: 「コメントは日本語」「関数名はスネークケース」など、技術スタックに依存しないものだけにする。

2. 技術選定・フレームワーク・テスト戦略は、リポジトリ側 instructions に一本化

   • copilot-instructions.md と、必要に応じてパス別 .instructions.md で統一。

3. PRレビューで“instructionsのどちらを直すべきか”を明示的に議論する

   • 「これは個人のUser Dataを削るべき」「これはリポジトリのルールを更新すべき」と切り分ける。

User Dataは「開発者のクセ」を、リポジトリ側 instructions は「チームとしての約束事」を担う。
この役割分担を守ると、Copilotの提案は「個人差のあるAI」から「チーム標準を守る補佐役」に変わっていく。

1リポジトリに複数 .instructions.md をどう割り振るか：プロが使う3つの型

Copilotを“賢い新人エンジニア”にするか、“暴走ロボ”にするかは、.instructions.md の割り方でほぼ決まります。1リポジトリ1枚では足りないが、闇雲に増やすと矛盾だらけになる。その境界線を、現場で本当に機能している3パターンで整理します。

技術スタック別（backend/frontend/test）で割るパターンの設計と落とし穴

まず一番やりがちな型が、src/backend/.instructions.md、src/frontend/.instructions.md、tests/.instructions.md のような技術スタック別分割です。
TypeScript＋React、PHP＋Laravel、Playwrightテストのように、ディレクトリ＝技術レイヤがきれいに分かれているリポジトリでは、これが最も扱いやすい型になります。

ポイントは3つだけ押さえるとぶれません。

• backend側には「DBアクセス規約」「トランザクション境界」「APIレスポンスのshape」

• frontend側には「UIコンポーネント構成」「状態管理ルール」「i18nの扱い」

• tests側には「テストフレームワーク」「モック戦略」「テストデータ生成ポリシー」

このとき、Copilotの適用範囲を曖昧にしないことが重要です。applyTo を雑に /src に切ってしまうと、Reactコンポーネントにもバックエンド用のルールが混入し、レビューの手戻りが一気に増えます。

失敗しがちなパターンは、「共通ロジック用のsharedディレクトリ」の扱いです。src/shared をどの instructions にも明示せず放置すると、Copilotは「抽象的でどのパスにも当てはまりそうな指示」を優先しがちになり、型ガードやユーティリティ関数の実装がプロジェクト方針からズレます。shared配下だけは専用の .instructions.md を置くか、core側に「sharedに関する明示ルール」を一段上の階層で定義しておくと安定します。

業務ドメイン別（請求/在庫/ユーザー）で割るパターンが向いているプロジェクト条件

「請求」「在庫」「ユーザー管理」のように、業務ドメインごとにディレクトリが分かれているシステムでは、技術スタック別より「ドメイン別 .instructions.md」の方がCopilotの真価を引き出せます。

Copilotは、同じdirectory内のコードから文脈を強く学習するAIです。billing/.instructions.md に課金ロジックの制約や締め日ロジック、税率の扱いを具体的に書いておくと、テックリードが毎回口頭で伝えていた“その現場ならではの注意点”を、Copilotが自然に提案し始めます。

この型がハマる条件は次の通りです。

• ドメインごとに責任チームが分かれている

• 同じReactやLaravelでも、ドメインごとに用語や制約が大きく違う

• 「ビジネスロジックのバグ」が致命傷になりやすい

一方で落とし穴は、共通技術ルールが分散しやすいことです。各ドメインの .instructions.md に、それぞれ独自のコーディングスタイルやテスト方針を書き始めると、数スプリント後には「どの書き方が正解か分からない状態」が生まれます。
これを防ぐには、技術ルールはリポジトリ直下の copilot-instructions.md に集約し、ドメイン側には「用語定義」「ドメインルール」「禁止事項」だけを書く構造にすると整流化できます。

小規模チームなら「コア1枚＋例外1枚」に絞った方がうまくいく理由

メンバー5〜8人程度のプロダクトでありがちなのが、細かく分けすぎて誰も中身を把握していない .instructions.md 群です。/frontend /backend /tests /scripts と4〜5枚に増やしたはいいものの、「どこに何を書けばいいか分からない」状態になり、結果としてCopilotが矛盾した提示をする原因になります。

こうしたチームでは、「コア1枚＋例外1枚」のミニマル構成が最も回りやすくなります。

• copilot-instructions.md（コア）

  • リポジトリ共通の言語・フレームワーク・Lint/Formatter・テスト方針
  • ディレクトリ構成と、どこをCopilot対象外にするかの明示

• legacy/.instructions.md（例外）やadmin/.instructions.md（例外）

  • レガシーコードや特殊な技術制約がある部分への限定ルール

ここで効いてくるのが、「レガシー置き場はCopilotを積極活用しない」という割り切りです。レガシー配下の .instructions.md に「このディレクトリでは新しいフレームワーク提案をしない」「既存関数を必ず再利用する」と明記しておくと、Copilotが勝手にReact化や最新API置き換えを提案する頻度が下がり、レビュー工数も安定してきます。

小規模チームにとって一番のボトルネックは、「Copilotの挙動そのものより、instructionsのメンテナンスコスト」です。PRレビューで毎回チェックできるのは2枚が限界という前提で、「コア1枚＋例外1枚」に絞る。結果として、テックリードが全体の設計意図を頭の中で保持でき、Copilotの誤提案も“意図を持って調整できる範囲”に収まります。

VS Code と GitHub の設定を“いい感じ”に連携させる実務テクニック

Copilotそのものより「VS Code設定 × リポジトリ側 instructions の噛み合わせ」でハマっているチームが多い。ここを外すと、テックリードが毎回「誰かのローカル設定に足を引っ張られる」状態になる。

chat.instructionsFilesLocations を雑に設定すると起きるノイズと、その防ぎ方

VS Code の github.copilot.chat.instructionsFilesLocations をなんとなく ["**/.instructions.md"] だけにしていると、次のようなノイズが一気に増える。

• レガシー置き場の .instructions.md まで読み込まれ、モダン側の開発でも古い規約が顔を出す

• サンプル用ディレクトリや playground/ のルールが、本番コードの補完にも混ざる

• 個人検証用ブランチの instructions が、他メンバーのコンテキストに紛れ込む

よくある失敗は、「再帰的に全部拾う」設定にしつつ、exclude設計をしていないこと。

おすすめは、「includeをざっくり、excludeを具体的に」の順で決めること。
特にレガシーをCopilot非対象にしたい場合は、instructionsファイルごと legacy/ 配下を除外すると、補完の“若返り度”が一段変わる。

ローカルの .instructions.md とリポジトリ内 instructions をどう優先させるか

User Data配下のカスタム instructions と、リポジトリ内 .instructions.md が衝突すると、

• 個人設定で「関数は必ず関数型コンポーネント」と書いてある

• プロジェクト規約では「一部の画面はクラスコンポーネント維持」と定義されている

という状況で、Copilotが中途半端に両方を守ろうとして“どちらにも寄せきれないコード”を出してくる。

現場での感触として、長期的なバグ削減に効くのは「リポジトリ優先」運用だ。

実務では、テックリードが最初にやるべきは次の2つ。

• チームに対して「個人 instructions では“文体”だけ触り、技術スタックやフレームワークは書かない」ガイドラインを共有

• リポジトリ側 instructions で、迷いがちな部分ほど明示的に書き切る（例: 管理画面はBlade固定、APIはFastAPIなど）

PRレビューで instructions の差分を必ずチェックする運用ルール

Copilotの精度は「何を書いたか」より「何をいつ変えたか」に強く依存する。
それなのに、PRレビューで .instructions.md の変更がノーチェックになっているチームは多い。

推奨しているのは、「コードレビュー」と「instructionsレビュー」を分けて見る運用だ。

• PRテンプレに項目を追加

  • - [ ] このPRで instructions ファイルを変更した場合、レビュアーと内容を口頭/チャットで共有した
  • - [ ] 変更対象ディレクトリと applyTo の範囲を確認した

• レビュー時のチェック観点

  • applyTo のパスが広すぎないか（src/** と書いているのに実際は src/admin/** だけでよい等）
  • 「スローガン」ばかり増えていないか（例: “高品質なテストを書きましょう”だけ増えて具体ルールがない）
  • テスト・型・ログ出力など、Copilotに自動化させたいタスクが“機械に伝わる文脈”になっているか

特に効き目が大きいのは、PRで instructions を触ったときは必ずそのディレクトリでCopilotに1回コードを書かせてみるという簡易リグレッション。
その場で「テストを書かない」「別フレームワークを提案する」といった挙動が出れば、instructionsの設計ミスを即座に炙り出せる。

VS Code設定とGitHubリポジトリ instructions をこのレベルで連携させると、「Copilotが暴走している」のか「チームの設計があいまいなのか」がはっきり見えてくる。ここまで整えると、テックリードが“Copilotの後処理係”から“Copilotの設計者”に立ち位置を変えられる。

「書いたら終わり」にしない：Copilot instructions のメンテナンス戦略

「copilot-instructions.md書いたし仕事完了」になった瞬間から、Copilotは徐々に“仕様書の亡霊”に引きずられ始めます。
ポイントは、コードと同じ粒度・同じリズムで instructions を更新する運用ラインを引くことです。

リポジトリのどの変化をトリガーに instructions を見直すべきか

現場で事故が増えるのは、「リポジトリ構成と instructions が半年ズレている」状態です。まずは見直しトリガーを明文化します。

代表的なトリガーを整理すると次の通りです。

テックリード視点では、アーキ変更PRをマージするタイミングで「関連 instructions どれ？」を必ず確認する運用が効きます。
リポジトリ直下と主要サブディレクトリの .instructions.md をざっくりマッピングした表を持っておくと、誰でもトリガー→対象ファイルを追えるようになります。

スプリントレトロで“Copilotの挙動”を振り返り項目に入れる理由

Copilotの失敗は、バグ票に上がりづらいのに開発速度をじわじわ削る隠れ負債になりがちです。
そこでスプリントレトロに、次のような軽量フォーマットを1スロットだけ差し込むと効果が出ます。

• 今スプリントで「Copilotの提案を毎回直していた」場面があったか

• その場面はどのディレクトリ/ファイル種別か（例: src/components/ui, tests/）

• 「Copilotに事前に伝わっていたら楽だった情報」は何か

ここで出てきた内容は、すぐ直す必要はなく「次スプリントで直す instructions の backlog」としてチケット化します。
重要なのは、「Copilotの挙動レビュー」を個人の感想ではなく、パス単位の傾向として棚卸しすることです。
この粒度で溜めると、どこに .instructions.md を増やすか/減らすかの判断材料になります。

CIやレビューに組み込める「instructions品質チェック」の考え方

instructionsはコードほど静的解析が効かないので、チェックポイントを絞った“人力＋軽量スクリプト”のハイブリッドが現実的です。

レビュー時に最低限見るべき観点を整理するとこうなります。

• applyTo/match が、実際のディレクトリ構成と合っているか

• 「このリポジトリならでは」の情報（使用フレームワーク、例外ルール）が増えているか

• スローガン的な抽象表現（「きれいなコードを」「モダンに」など）が増えすぎていないか

• User Data の個人設定と真逆のことを書いていないか

CIでは、「instructions差分が出たら必ずレビュー必須ラベルを付ける」程度でも効果があります。
さらに一歩踏み込むなら、次のような簡単なチェックは自動化しやすいです。

ここまで仕込んでおくと、Copilotは「最初だけ賢いツール」から、プロジェクトの成長に追随するチームメンバーに変わります。

他の記事が触れていない“逆張り”視点：あえて instructions を減らした方がうまくいく場面

「Copilotを賢くするぞ」と張り切って instructions を盛り込み過ぎた結果、プロジェクト全体が“AI仕様書地獄”になっていないだろうか。実務では、削った瞬間にバグが減る instructionsがはっきり存在する。

レガシー置き場を「Copilot非対象」にしたことでバグが減った事例パターン

レガシーコードを温存しているプロジェクトで起きがちなのが、「github copilot instructions がレガシーまで面倒を見る前提」になっているパターンだ。結果として:

• jQuery時代の画面に、毎回 React + TypeScript のリファクタ提案

• 古い命名規則を“最新の規約違反”として書き換えようとする

• テストもインフラも存在しないディレクトリに、最新スタック前提のテスト生成

ここでは「触らない領域を明示的に外す」方が勝つケースが多い。

レガシー置き場を Copilot 非対象にする時、現場でよく使われる切り分けは次の通り。

ポイントは、「Copilotで触ってよい領域」と「静観すべき領域」を instructions 側で線引きすること。全部を賢くしようとすると、レガシー側の誤提案レビューがボトルネックになる。

「全部Copilotに任せる」より「静的分析＋Copilot」の役割分担が効く領域

instructions を肥大化させて「Lintも設計レビューも Copilot が全部やってくれるはず」と期待すると、すぐに破綻する。Copilot は「文脈を踏まえた提案」「補完」には強いが、「プロジェクト全体を網羅した検査」は静的解析の方が圧倒的に得意だ。

特に、次のような領域は「静的分析ツール + 最小限の instructions」が最もコスパが良い。

• 型安全(TypeScript, pyright, mypy)

• コーディング規約(ESLint, Stylelint, PHP-CS-Fixer)

• セキュリティの基本チェック(依存ライブラリの脆弱性、SQL直書き検出など)

この組み合わせが効く理由は単純で、「機械的に判定できるものはツールに任せ、Copilot instructions は“どのように修正してほしいか”だけに絞る」からだ。

例:

• ESLintがエラーを出す → Copilotには「ESLintのエラーをゼロにする修正案を優先して提案せよ」とだけ書く

• セキュリティポリシーは社内ドキュメントに集約 → instructions には「このURLのガイドラインに反するコードは提案しない」と一行添える

Copilot に「判定＋修正＋設計判断」を丸ごとやらせないことで、instructions の行数もレビューコストも一気に下がる。

instructionsを細かく書かない方が良い、急成長中プロジェクトの条件

プロダクトが急成長しているフェーズほど、「完璧な instructions を作り込みたい」という誘惑が強い。だが、仕様とディレクトリ構成が毎スプリントひっくり返る状態で細かい .instructions.md を量産すると、二週間でほぼ全てが“嘘のルール”になる。

急成長中で「instructionsをあえて薄く保つ」方がうまく回りやすい条件は、概ね次の通り。

このフェーズでやるべきは、“薄いが絶対に守るべきコア”だけを instructions に昇格させ、それ以外は README や設計ドキュメントに逃がすことだ。Copilot instructions を仕様書の代わりにしない方が、結果としてバグもコンフリクトも減る。

github copilot instructions を「書き足すツール」ではなく、「どこまでを Copilot の担当にするかを絞り込むスイッチ」として扱うと、チーム全体のノイズが一段下がる。

これから書くべき instructions 雛形チェックリスト：今日から使える叩き台

最低限入れるべき“このリポジトリならでは”の7項目

同じCopilotでも、「このrepoでだけ刺さる文脈」をどれだけ渡せるかで、提案精度は露骨に変わります。まずは次の7項目だけに絞って書き出すと、ノイズなく効き始めます。

• 1. 技術スタックの“実態”

  例: 「新規はReact/TypeScript、/legacy配下はjQueryを維持」

• 2. ディレクトリごとの役割

  例: 「src/appはUIコンポーネント、src/coreはドメインロジック」

• 3. 命名規則とコードスタイルの“例外”

  通常のESLint/Prettierでは拾えないプロジェクト固有ルール

• 4. テスト方針と必須パターン

  例: 「新規APIにはtests/api配下に統合テストを必ず追加」

• 5. 使ってほしい/避けたいライブラリ

  例: 「日付はluxonのみ使用。momentは提案しない」

• 6. 認証・権限の扱い方の型

  例: 「認証情報は必ずgetCurrentUser()経由で取得」

• 7. 非対象エリアの明示

  例: 「/sandboxはPoC。Copilotは積極提案不要」

この7つをベースに、copilot-instructions.mdと各.instructions.mdで粒度を変えて書き分けると、「どのディレクトリで何を守るか」をAIに伝えやすくなります。

簡易チェック表は次の通りです。

書きすぎ防止のための「削るべき表現」チェックリスト

Copilotは“なんとなく良さそうなスローガン”が大好物です。その結果、抽象論が具体ルールを飲み込む現象がよく起きます。次のような表現は、見つけたら削るか、具体例に置き換えます。

• 「クリーンなコードを書くことを心がける」

• 「最新のベストプラクティスに従う」

• 「高い可読性を維持する」

• 「パフォーマンスを意識した実装にする」

• 「セキュアなコーディングを行う」

代わりに、Copilotが判定可能な“if/then”に落とすのがポイントです。

「Copilotが判定できない価値観ワード」は削る、これだけでノイズがかなり減ります。

チームメンバーに共有するときのREADMEへの組み込みパターン

instructionsは、書くより「読ませ続ける」方が難しい領域です。READMEに次の3点を組み込むと、運用が一気に回り始めます。

• 1. 参照場所の一覧

例:

• copilot-instructions.md: リポジトリ共通ルール

• src/.instructions.md: フロントエンド（React/TypeScript）

• tests/.instructions.md: テストコード方針

• 2. 更新ルールの明文化

例:

• 新しいディレクトリを切ったら、.instructions.mdを作るかどうか必ず検討する

• PRで規約を変更した場合、同じPR内でinstructionsも更新する

• 3. 開発者向け“使い方クイックリファレンス”

例:

• VS Codeのchat.instructionsFilesLocationsに、このリポジトリのパスを追加する手順

• User Data側の個人設定で、プロジェクト方針と衝突しそうな項目（例: テスト自動生成ポリシー）をオフにする手順

READMEにここまで書いておくと、「テックリードだけがCopilotを制御している状態」から、チーム全員で instructions を育てる状態へ移行しやすくなります。

執筆者紹介

主要領域はGitHub Copilotのinstructions設計と開発プロセス設計です。本記事では、仕様紹介にとどまらず、失敗パターン→構造→運用ルールの順に分解し、現場で再現しやすい判断軸として整理することを重視しています。抽象論よりも「どの設定をどう変えると挙動がどう変わるか」という因果関係にフォーカスした執筆スタイルで、チーム開発でそのまま流用できる設計指針の提示を目的としています。