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