GitHub Copilot 向けの指示を構造化して管理
GitHub Copilot や各種 AI コーディング支援ツールを使っていると、だんだんこんな悩みが出てきます。
- 同じ注意を毎回書いている
- プロジェクトごとのルールが AI にうまく伝わらない
- ドキュメント更新やテスト実行の方針が毎回ぶれる
- 指示ファイルが増えるほど、どれが優先なのか分からなくなる
そこで、AI に渡す指示を場当たり的な1ファイルのプロンプトではなく、構造化されたルールセットとして管理できるようにしたのがこのリポジトリです。
今回紹介するのは、以下のリポジトリです。
- Repository: https://github.com/h-nasu/copilot-instructions
copilot-instructions とは
このリポジトリは、Copilot 向けの instruction ファイルを「いろいろなプロジェクトで使い回し・保守しやすい形」で管理するためのボイラープレートです。
README では、このリポジトリは「任意のプロジェクトで利用・保守できる copilot instruction files のためのもの」と説明されています。
また、.ai-instructions/ 配下の説明では、この仕組みは次のような方針で設計されています。
- tool-agnostic
- model-agnostic
- editable by users and AI
- maintainable over time
つまり、特定の AI ツールに強く依存せず、プロジェクトごとのルールや運用フローを整理して AI に渡すための土台として使える構成になっています。
何がうれしいのか
AI コーディング支援で本当に困るのは、AI の性能そのものというより、毎回同じ前提を説明し直すことだと思っています。
たとえば実務では、次のような前提がよくあります。
- まず既存ドキュメントを読むこと
- 実装前後に守るべき作業順があること
- 実装だけで終わらず README や設計資料も更新すること
- feature ごとに別ルールがあること
- 過去の不具合や issue の対応パターンに従うこと
こうした内容を毎回チャットで説明するのは非効率です。
このリポジトリでは、それらをAI の実行ルールとしてファイル化し、順序付きで適用できるようにしているのが大きなポイントです。
プロジェクトの中心は .ai-instructions/
このプロジェクトの中核は .ai-instructions/ です。
ここには、AI がタスクを始める前に読むべきルールや、実行フロー、テンプレート、ドキュメント運用方針などを置く想定になっています。
公開されている説明では、.ai-instructions/ は AI が次のことを理解・実行するための基盤として扱われています。
- task の理解
- 計画
- 実行
- テスト
- ドキュメント作成・更新
さらに、各ファイルやディレクトリの役割もかなり明確に分けられています。
単なるメモ置き場ではなく、AI が従うべきルール群を整理するためのディレクトリとして設計されているのが特徴です。
読み込み順と上書きルールがある
このリポジトリで特に重要なのが、ルールに読み込み順と上書きの考え方があることです。
.ai-instructions/ の説明では、AI は以下の順序で読むことが想定されています。
overview.mdspecs.mdspecs/hooks/workflows/project-docs.mdtemplates/documents/
この順番があることで、まず全体ルールを読み、そのあとでプロジェクト固有・機能固有のルールを読み込む、という階層構造を作れます。
さらに、ファイル名に 00-, 01-, 02- のようなインデックスを付けることで、後ろのファイルが前のルールを拡張・上書きできるようになっています。たとえば次のようなイメージです。
00-default.md
01-project.md
02-feature-x.md
これにより、「全体共通の原則」と「例外的な個別ルール」を同じ仕組みの中で整理しやすくなります。
ディレクトリ構成を見ると思想が分かりやすい
公開されている構成を見ると、主に以下の要素で成り立っています。
.
├── .ai-instructions/
├── .github/
│ ├── copilot-instructions.md
│ └── prompts/
├── .vscode/
├── AGENTS.md
└── README.md
.ai-instructions/
AI が読むべきルールの本体です。
実行モデル、仕様、フック、ワークフロー、テンプレート、ドキュメント配置の考え方などを整理する前提のディレクトリです。
AGENTS.md
AI の実行契約のような位置づけです。
タスク開始前に .ai-instructions/ を順番に読むこと、hooks/before → workflows → hooks/after の流れに従うこと、コード・テスト・ドキュメントが揃うまで未完了扱いであること、などが定義されています。
.github/copilot-instructions.md
GitHub Copilot 向けの具体的な運用ルールです。
特に、無駄な問い合わせ回数を減らすこと、同じミスを繰り返さないこと、ドキュメント更新や検証を自動で行うことなど、かなり実務寄りの方針が見えます。
.github/prompts/
architect、debugger、developer、executor、producer など、役割別の prompt を置く場所です。
役割ごとに視点を切り替えて AI を使いたいときのベースとして活用しやすい構成です。
面白いのは「便利プロンプト集」で終わっていないこと
個人的に面白いと思ったのは、このリポジトリが単なる「便利な prompt 集」ではなく、AI に守らせる運用ルールのレイヤー設計になっていることです。
たとえば .github/copilot-instructions.md では、過去の課題として次のようなものが挙げられています。
- 同じミスの繰り返し
- instruction 文書がない
- ドキュメント管理が弱い
- 重複ドキュメントができる
- テストや検証が後回しになる
- コンテキスト管理が弱い
そして、それに対して「まず実装し、必要なら後で相談する」「ドキュメントは自動更新する」「lint や型チェックなどの必要な確認を自動実行する」といった思想がかなり強く打ち出されています。
つまり、AI を単なる補完ツールとしてではなく、プロジェクトの作業ルールの中で安定して動かすための存在として扱っているわけです。
ここがこのリポジトリのいちばん面白いところだと思います。
どういう人に向いているか
このプロジェクトは、特に次のような人に向いていると思います。
- GitHub Copilot を日常的に使っている
- プロジェクトごとのルールを AI にしっかり読ませたい
- ドキュメント更新漏れを減らしたい
- AI とのやりとりを毎回ゼロから始めたくない
- リポジトリ単位で instruction を育てていきたい
逆に、ちょっとした個人開発で「雑に聞いて雑に補完してくれればよい」というケースだと、ここまでの構造は少し重く感じるかもしれません。
ただ、チーム開発や中長期運用のリポジトリではかなり相性が良さそうです。
使い方のイメージ
このリポジトリは、そのまま完成品として使うというより、各プロジェクトに合わせてカスタマイズするベースとして使うのがよさそうです。
たとえば、次のような流れが考えられます。
-
.ai-instructions/specs.mdに共通ルールを書く -
specs/にプロジェクト固有や機能固有のルールを追加する -
hooks/にタスク前後で必ずやることを書く -
workflows/に実装・レビュー・調査などの流れを書く -
project-docs.mdにドキュメント配置ルールを書く -
.github/prompts/に役割別のプロンプトを整理する
こうしておくことで、AI に毎回「このプロジェクトではこうして」と長く説明しなくても、読み込ませる前提を作りやすくなります。
README を強化するとさらに伝わりやすい
現状の README はかなりシンプルで、「何のためのリポジトリか」は伝わる一方、初見の人が価値を理解するには少し情報が足りない印象があります。
ただ、中身を見ると実際にはかなり思想があります。
たとえば、以下の点はこのプロジェクトの魅力として前面に出せそうです。
- instruction の読み込み順が定義されている
- override の仕組みがある
- AI の実行契約が
AGENTS.mdに分離されている - Copilot 向けの運用ルールが
.github/copilot-instructions.mdに整理されている - 役割別 prompt の置き場がある
なので README や紹介記事では、**「単なる instruction 集ではなく、AI 運用のフレームワークである」**ことを前面に出すと魅力が伝わりやすいと思います。
まとめ
copilot-instructions は、AI 向けの指示を単発のプロンプトではなく、プロジェクトで継続的に育てるルール群として扱いたい人に向いたリポジトリです。
.ai-instructions/ を中心に、ルールの適用順序、上書き戦略、実行契約、Copilot 向け運用方針、役割別 prompt を整理できる構成になっており、AI 活用をより実務寄りに設計できるのが魅力です。
AI を「その場の相談相手」として使うだけでなく、プロジェクトルールの中で安定して働かせたいなら、こういう構造化された instruction boilerplate はかなり有効だと思います。
気になる方はぜひリポジトリを見てみてください。
- Repository: https://github.com/h-nasu/copilot-instructions