copilot-instructions の複雑な概念を具体例で理解する — 読み込み順・上書き・フック・実行契約・テンプレート・自信度・学習ループ
前回記事「GitHub Copilot 向けの指示を構造化して管理」では、h-nasu/copilot-instructions の全体像を紹介しました。
今回は、このフレームワークを構成する仕組みの概念を、1つずつ具体例で掘り下げます。
各概念を次の4点セットで解説します。
- 概念（何か）
- なぜ必要か（課題）
- 実際の instruction 抜粋（どう書くか）
- Copilot の出力がどう変わるか（効果）
※ ドキュメントの配置・責務分離については、前回記事「AI用ドキュメントと開発者用ドキュメントの混在問題を解決する」で詳しく解説しているので、そちらを参照してください。本記事では「仕組み」そのものに集中します。
概念1: 読み込み順（エントリーポイント）
概念
AI がタスクを始める前に、.ai-instructions/ 配下のファイルを決まった順番で読むという仕組みです。
なぜ必要か
「どのファイルを読めばいいか」を AI に委ねると、読むファイルが毎回変わって前提がぶれます。読み込み順を固定すれば、常に同じ文脈でタスクを開始できます。
実際の instruction 抜粋
.ai-instructions/ の README では、AI が必ず読む順序が定義されています。
AI must always read:
1. overview.md
2. specs.md
3. specs/
4. hooks/
5. workflows/
6. project-docs.md
7. templates/
8. documents/
Copilot の出力がどう変わるか
Before（読み込み順なし）
ユーザー: ログイン機能を実装して
Copilot: 了解、実装します（→ 既存ルールを読ずにいきなりコードを書き始める）
After（読み込み順あり）
ユーザー: ログイン機能を実装して
Copilot: まず .ai-instructions/ を読み込みました。
- overview.md: 実行モデル確認
- specs.md: 共通ルール確認
- specs/: プロジェクト固有ルール確認
- project-docs.md: ドキュメント配置ルール確認
以上の前提で実装を開始します。
毎回同じ前提で始まるので、説明の繰り返しが減り、ぶれがなくなります。
概念2: インデックスによる上書き（override）
概念
ファイル名の 00-, 01-, 02- というインデックス順にルールが適用され、後ろのファイルほど前のルールを拡張・上書きできる仕組みです。
なぜ必要か
「全体共通の原則」と「プロジェクト固有の例外」「機能固有の例外」を、同じ仕組みの中で両立させるためです。1つのファイルに全部書くと、例外が増えるたびに壊れます。
実際の instruction 抜粋
specs/
├── 00-default.md # 全プロジェクト共通のデフォルト
├── 01-project.md # このプロジェクト固有のルール（00を上書き）
└── 02-feature-x.md # 特定機能の例外（00, 01を上書き）
.ai-instructions/ の説明では、後ろのファイルは「新しいルールの追加」「既存ルールの上書き」「スコープの絞り込み・拡大」ができると定義されています。
Copilot の出力がどう変わるか
Before（上書きなし）
プロジェクトAでは「テスト必須」、機能Xでは「テスト省略可」という例外を
どう表現すればいいか分からず、指示が矛盾する。
After（上書きあり）
機能Xのタスクでは、02-feature-x.md が 00-default.md より優先されるため、
「Xではテスト省略可」を正しく適用しつつ、他の機能では「テスト必須」を守る。
例外を安全に積み重ねられるのがこの仕組みの強みです。
概念3: hooks / workflows パイプライン
概念
タスクの前後で必ず実行する処理（hooks）と、タスクの実行手順（workflows）を分離して定義する仕組みです。
なぜ必要か
「実装前に計画する」「実装後にテストしてドキュメントを更新する」といった規律を、AI の標準動作として強制するためです。お願いではなくルールにします。
実際の instruction 抜粋
AGENTS.md には、このパイプラインが明記されています。
Follow hooks/before/ → workflows/ → hooks/after/ pipeline
ディレクトリ構成は次のようになります。
.ai-instructions/
├── hooks/
│ ├── before/ # 例: 既存ドキュメントの確認、計画の作成
│ └── after/ # 例: テスト実行、ドキュメント更新、コミットメッセージ生成
└── workflows/ # 実装・レビュー・調査などの実行フロー
Copilot の出力がどう変わるか
Before（フックなし）
実装 → 終了（テストもドキュメントも後回し、ユーザーが指摘して初めて対応）
After（フックあり）
hooks/before → 既存ドキュメント確認・計画作成
workflows → 実装
hooks/after → テスト実行 → ドキュメント更新 → コミットメッセージ生成
→ 「コード・テスト・ドキュメントが揃って完了」と報告
「コードを直して終わり」を構造的に防げます。
概念4: AGENTS.md 実行契約
概念
AI が守るべきタスク完了の定義を、リポジトリ直下の AGENTS.md に宣言する仕組みです。
なぜ必要か
AI は「コードを直したら完了」と思いがちです。完了の定義を先に固定しておかないと、ドキュメント更新やテストが毎回漏れます。
実際の instruction 抜粋
# AGENTS.md — AI Execution Contract
Before beginning ANY task:
- Read all .ai-instructions/ files in index order
- Follow hooks/before/ → workflows/ → hooks/after/ pipeline
- Never skip documentation steps
A task is INCOMPLETE until code + tests + documentation are all done.
Copilot の出力がどう変わるか
Before（契約なし）
ユーザー: バグを直して
Copilot: 修正しました（→ テストもドキュメントも更新せず完了と報告）
After（契約あり）
ユーザー: バグを直して
Copilot: 修正しました。ただし AGENTS.md の契約に基づき、
テスト実行とドキュメント更新が未完了のため、タスクは未完了として報告します。
続けてテストとドキュメントを更新します。
「完了」の定義を AI と人間で共有できるのがポイントです。
概念5: templates（テンプレート）
概念
AI が生成する出力の構造（フォーマット）を固定する仕組みです。テンプレートは「ロジックではなくフォーマット」をガイドします。
なぜ必要か
AI にドキュメントを生成させると、毎回フォーマットが違って読みにくくなります。テンプレートで構造を固定すれば、出力が安定します。
実際の instruction 抜粋
project-docs.md には、テンプレートの利用が明記されています。
## Templates
- Templates under .ai-instructions/templates/documents/ must be used
- New templates must be referenced in this file
Copilot の出力がどう変わるか
Before（テンプレートなし）
ドキュメントの見出し構成が毎回バラバラ
→ 読むたびに構造を把握し直すコストが発生
After（テンプレートあり）
毎回同じ見出し構成で生成される
→ どこに何が書いてあるか、すぐ分かる
チームで読むコストを下げる効果があります。
概念6: documents/ のフィードバックループ（学習サイクル）
概念
失敗パターンや issue 分析を documents/ に蓄積し、次回のタスクに自動的に活かす仕組みです。
なぜ必要か
「同じミスを繰り返す」のが AI 運用の最大の無駄です。失敗を記録として資産化して、次回から自動対応できるようにします。
実際の instruction 抜粋
.github/copilot-instructions.md には、エラー処理の手順が定義されています。
## Error Response Procedure
1. Analyze error — ログ/エラーから原因を特定
2. Check known patterns — documents/08-issues/*.md を検索
3. Implement fix — 修正 + 予防策を追加
4. Create instruction doc — 新パターンなら specs/ に追加
5. Verify — lint + 型チェックで影響範囲を確認
Put any bugs, issues and incident inside documents/08-issues/*.md
改善サイクルは次のように定義されています。
Task Execution → Pattern Discovery → Documentation
→ Next Time Automation → (Loop)
Copilot の出力がどう変わるか
Before（フィードバックなし）
同じバグの直し方を毎回ゼロから考える
同じ失敗を繰り返し、クエリを無駄に消費
After（フィードバックあり）
エラー発生時 → documents/08-issues/ を検索 → 既知パターンを適用
→ 新パターンなら specs/ に記録 → 次回から自動対応
「同じミスを1回で直す」状態に近づきます。
概念7: confidence-level（自信度スコアリング）
概念
AI が自分の出力に対する自信度を 0.0〜1.0 の数値で明示する仕組みです。これは specs/02-confidence-level.md で定義されています。
なぜ必要か
AI の出力には「確実に正しいもの」と「推測で書いたもの」が混在しています。自信度を数値化しておくと、人間が「どこを重点的にレビューすべきか」を判断できます。特に、要件を推測して実装した場合に、その危険性を可視化できます。
実際の instruction 抜粋
Confidence guidelines:
- 0.95–1.00 → Trivial or purely mechanical change
- 0.85–0.94 → Well-defined task, low ambiguity
- 0.70–0.84 → Some assumptions or unclear edges
- 0.50–0.69 → Significant ambiguity or missing context
- < 0.50 → High uncertainty or speculative output
さらに、自信度とリスクの組み合わせルールも定義されています。
If Confidence < 0.8 AND Risk level is medium or high
AI SHOULD:
- Explicitly warn before continuing
- Suggest review or clarification
つまり、自信度が低い（0.8未満）かつリスクが中〜高の場合は、AI は続行前に警告し、レビューや確認を提案しなければなりません。
Copilot の出力がどう変わるか
Before（自信度なし）
ユーザー: この画面を実装して
Copilot: 実装しました。（→ 実は仕様を推測していたが、それが伝わらない）
After（自信度あり）
ユーザー: この画面を実装して
Copilot: 実装しました。ただし confidence は 0.55 です。
要件が推測ベースで、リスクが中程度のため、レビューを推奨します。
特に「ログイン後の遷移先」の仕様確認をお願いします。
「どこが怪しいか」が人間に伝わるので、レビューの質が上がり、推測実装による事故を防げます。
まとめ
copilot-instructions の複雑な概念は、どれも「AI の動作をぶれさせない」ための仕組みです。
| 概念 | 役割 |
|---|---|
| 読み込み順 | 毎回同じ文脈でタスクを開始する |
| インデックス上書き | 共通ルールと例外を安全に両立する |
| hooks / workflows | 規律を標準動作として強制する |
| AGENTS.md 実行契約 | 完了の定義を AI と共有する |
| templates | 出力フォーマットを固定する |
| documents/ ループ | 失敗パターンを資産化して繰り返しを防ぐ |
| confidence-level | 自信度を数値化し、レビュー箇所を可視化する |
これらの概念は、どれも単体でも使えますが、組み合わせることで「指示を読む → 例外を適用 → 規律を守る → 完了を定義する → 出力を統一する → 自信度を示す → 失敗を学ぶ」という一連の流れになります。
ドキュメントの配置・責務分離の詳しい話は、前回記事「AI用ドキュメントと開発者用ドキュメントの混在問題を解決する」を参照してください。
- Repository: https://github.com/h-nasu/copilot-instructions/tree/main
- 前回記事: https://qiita.com/h-nasu/items/d0b2601bb179a6cdd5eb