AI用ドキュメントと開発者用ドキュメントの混在問題を解決する — copilot-instructions 導入時の課題と段階的な運用開始方法

前回の記事「GitHub Copilot 向けの指示を構造化して管理」では、h-nasu/copilot-instructions というボイラープレートの全体像を紹介しました。

今回はその続編として、実際に導入しようとしたときにぶつかる課題と、段階的に運用を始める方法をまとめます。

特に、Copilot などの生成AIを使い始めると必ず直面する、

AI専用の開発ドキュメントと、アプリの使用者（開発者・クライアント）が読むドキュメント類が混在する
同じ内容が複数の場所に重複して書かれ、二重メンテナンスになる
結果としてドキュメント運用が破綻する

という問題を、このフレームワークが**責務分離（Separation of Concerns）**でどう解決するかを中心に解説します。

1. 導入時にぶつかる課題

課題1: AI用と開発者用のドキュメントが混在する

Copilot に「ドキュメントを更新して」と頼むと、AI は自分が読むためのメモを勝手な場所に作ります。一方で、人間の開発者が読む README や設計書も同じリポジトリにあります。

すると、次のような状態になります。

docs/
├── README.md              # 開発者向け？ AI 向け？ どっち？
├── architecture.md         # 開発者向けだけど AI も読む
├── setup.md
├── deployment.md
├── ai-notes.md             # AI が勝手に作ったメモ（どこに置く？）
├── 2024-05-01-task.md      # AI が作ったタスクメモが混ざる
├── 2024-05-02-issue.md     # issue 分析もここに…
└── requirements/           # クライアント要件（AI が上書きしてしまう危険）

「どのファイルが誰向けなのか」が分からなくなり、運用が破綻します。

課題2: ドキュメントが重複して二重メンテになる

典型的なのが、同じ情報が複数箇所に書かれるケースです。

セットアップ手順が README.md にも docs/setup.md にも書いてある
アーキテクチャ説明が architecture.md と AI 用メモの両方にある
同じ情報を2箇所でメンテする → 片方の更新を忘れる → 情報が食い違う

これは「ドキュメントを増やせば増やすほど壊れる」状態です。

課題3: 「どこに何を書くか」のルールがない

AI に「ドキュメントを作って」と言っても、配置場所のルールがなければ AI は毎回違う場所に作ります。結果、ドキュメントの置き場所がバラバラになり、探すコストが増えます。

課題4: ルールの優先順位が不明

指示ファイルが増えるほど、「どれが優先されるのか」が分からなくなります。AGENTS.md にも .github/copilot-instructions.md にも .ai-instructions/ にも似たようなことが書いてあると、AI はどれを信じればいいのか迷います。

課題5: いきなりフル導入すると運用が回らない

最初から全ディレクトリを完璧に作ろうとすると、メンテが重くなって続きません。小さく始めて、段階的に育てるのが重要です。

2. 本フレームワークがどう解決するか — 責務分離

このボイラープレートの中核は、「誰が読むドキュメントか」で置き場所を完全に分離することです。

責務分離後のディレクトリ構成

# 開発者・クライアント向け（人間が読む）
docs/
├── overview.md
├── specifications/
│   ├── architecture.md
│   └── setup.md
├── deployment.md
├── api/
│   └── endpoints.md
├── components/
└── state/
    └── state-management.md

# AI 内部用（AI が読む・書く）
.ai-instructions/
├── overview.md
├── specs.md
├── specs/
│   └── 02-confidence-level.md   # 自信度スコアリングのルール
├── hooks/
├── workflows/
├── templates/
├── ai-docs.md                   # AI ドキュメントの定義
├── documents/                   # AI が実装に使うドキュメントの置き場
│   ├── 01-plans/
│   ├── 02-specifications/
│   ├── 03-designs/
│   ├── 04-tasks/
│   ├── 05-developments/
│   ├── 06-tests/
│   ├── 07-changes/
│   └── 08-issues/
└── project-docs.md

# クライアント・開発者からの要求（読み取り専用）
client-requirements/             # AI は絶対に触らない

分離を強制する仕組み

この分離は「お願い」ではなく、project-docs.md にルールとして明記されています。

ドキュメントの配置場所: プロジェクトが許可したディレクトリ（docs/ など）にのみ作成。AI が勝手に新しいドキュメントルートを作ってはいけない
責務分離: docs/ はクライアント・チーム向け、.ai-instructions/documents/ は AI 内部用
読み取り専用: client-requirements/ はクライアント提供物専用。AI は生成・移動・変更してはいけない

これにより、「AI の作業メモ」と「人間が読むドキュメント」が物理的に混ざらない構造になります。

3. `.ai-instructions/documents/` とは — AI が実装に使うドキュメントの集約場所

このフレームワークで特に重要なのが、.ai-instructions/documents/ です。
ここは単なる「AI のメモ置き場」ではなく、AI が実装に使用するドキュメント類を、フェーズごとに体系的にまとめる場所です。

.ai-instructions/ai-docs.md では、このディレクトリのルールが明確に定義されています。

AI が生成するドキュメントは、必ず .ai-instructions/documents/ 配下に作る
各ディレクトリはタスク実行の「フェーズ」を表す
インデックス接頭辞（01-, 02- …）は必須で、実行順を定義する
ドキュメントは反復的に更新してよい
後のフェーズは前のフェーズを参照してよい

フェーズごとのドキュメント

ai-docs.md では、次の8つのフェーズが定義されています。

フェーズ	役割
`01-plans/`	依頼の理解・方針・前提・制約を記録（設計・実装の前段階で必須）
`02-specifications/`	必要な UI・API・挙動・制約を定義
`03-designs/`	アーキテクチャと実装詳細（ファイル構成・クラス設計・データフロー・技術スタック）
`04-tasks/`	実行可能なタスクへ分解（各タスクは検証可能であること）
`05-developments/`	実行結果の記録・完了サマリ
`06-tests/`	テスト計画・結果・失敗・修正の記録
`07-changes/`	初期計画後の変更と、その理由の追跡
`08-issues/`	バグ・問題・対策・学びの記録

なぜここが重要か

この構造があることで、次のことが保証されます。

実装の履歴が一箇所に揃う: 計画 → 仕様 → 設計 → タスク → 実装 → テスト → 変更 → 課題、という流れがすべて .ai-instructions/documents/ に残る
開発者向けドキュメントと混ざらない: 人間が読む docs/ には AI の作業メモが入らず、逆に AI の実装ドキュメントにも人間向けの説明が混ざらない
次のタスクの文脈になる: ai-docs.md にある通り、これらのドキュメントは「以降のタスク実行に影響を与えうる」ため、AI は過去の設計・課題を踏まえて実装を続けられる

つまり .ai-instructions/documents/ は、AI が「考えたこと・決めたこと・やったこと」を資産として蓄積する、AI 専用のナレッジベースです。ここが整備されることで、AI は毎回ゼロから考えるのではなく、過去の文脈を引き継いで作業できます。

4. クライアント要件は完全に分離する — `client-requirements/`

もう1つ強調したいのが、クライアント・開発者からの要求（要件）を、他のドキュメントと混ざらないように分離するための client-requirements/ ディレクトリです。

なぜ必要か

クライアントや開発者から渡される「仕様要求・要件」は、プロジェクトの基準となる元の事実です。これが他のドキュメントと混ざると、次のような問題が起きます。

どれが「要件」で、どれが「AI のメモ」なのか分からなくなる
AI が要件を誤って書き換えてしまい、実装の基準が壊れる
要件の変更履歴が追えなくなる

このフレームワークでの扱い

project-docs.md では、client-requirements/ について次のように明記されています。

読み取り専用: AI は client-requirements/ 配下のファイルを生成・移動・変更してはいけない
専用領域: このディレクトリはクライアント提供の生の材料（raw client-provided materials）専用
混在防止: 要件は常にここに固定され、他のドキュメントと混ざらない

つまり、要件は「触ってはいけない基準」として隔離し、AI はそれを読んで実装するだけで、書き換えることはできません。これにより、要件と AI の作業ドキュメントが混在して破綻する、という事故を構造的に防ぎます。

重複問題の解決

重複の原因は「同じ情報を2つの文脈で書いている」ことでした。責務分離すると、次のように整理できます。

情報	置き場所	誰が読む/書く
クライアント・開発者の要求	`client-requirements/`	読み取り専用（AI は触らない）
タスクの計画・進捗・設計・実装記録	`.ai-instructions/documents/`	AI が書く・読む
アーキテクチャ・セットアップ・API 仕様	`docs/`	人間が読む

「どこに何を書くか」が一意に決まるので、同じ内容を2箇所でメンテする必要がなくなります。

5. 段階的な運用開始方法（Step 0〜N）

Step 0: 現状を棚卸しする

まず、リポジトリ内のドキュメントがどこに散らばっているかを確認します。

README や docs/ に何があるか
AI が勝手に作ったメモがどこにあるか
同じ内容が複数箇所にないか
クライアント要件がどこに置かれているか

この棚卸しが、導入後の「差分」を測る基準になります。

Step 1: 最小構成から始める（1ファイル）

最初から全部を作らない。まずは AGENTS.md と .ai-instructions/overview.md の2つだけから始めます。

AGENTS.md に、タスク完了の定義だけを書きます。

# 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.

この1ファイルだけで、「ドキュメントはタスクの一部」という規律が生まれます。

Step 2: 共通ルールと個別ルールを分ける

運用に慣れてきたら、specs.md（共通ルール）と specs/（個別ルール）に分割します。

.ai-instructions/
├── specs.md               # 全プロジェクト共通のルール
└── specs/
    ├── 00-default.md      # デフォルト
    ├── 01-project.md      # このプロジェクト固有
    └── 02-confidence-level.md  # 自信度スコアリング（例）

後ろのファイルほど前のルールを上書きできるので、「共通の原則」と「例外的な個別ルール」を両立できます。

Step 3: ドキュメント配置ルールを固定する

ここで project-docs.md と ai-docs.md を追加し、責務分離をルール化します。

開発者向けは docs/ に固定
AI 内部用は .ai-instructions/documents/ に固定（フェーズごとに 01-plans/ 〜 08-issues/）
クライアント要件は client-requirements/ に固定（読み取り専用）

このステップが、冒頭の「混在・重複問題」を解決する肝になります。

Step 4: hooks と workflows で運用を固定する

hooks/before/ に「タスク開始前に必ずやること」、hooks/after/ に「タスク完了後に必ずやること」を書きます。

.ai-instructions/
├── hooks/
│   ├── before/            # 例: 既存ドキュメントの確認、計画の作成
│   └── after/             # 例: テスト実行、ドキュメント更新、コミットメッセージ生成
└── workflows/             # 実装・レビュー・調査などの流れ

これで「実装前に計画」「実装後にテストとドキュメント更新」が AI の標準動作になります。

Step 5: 改善サイクルを回す

失敗パターンは documents/08-issues/ に蓄積し、新しいパターンは specs/ にフィードバックします。

タスク実行 → パターン発見 → ドキュメント化 → 次回は自動化 → （ループ）

これにより、同じミスを繰り返さない仕組みが育ちます。

Step 6: チーム展開・CI 化

チームメンバーに読み込み順と責務分離を共有する
テンプレート（templates/documents/）を整備して出力を統一する
必要に応じて CI でドキュメントの存在やフォーマットを検証する

6. 導入時の注意点・失敗しがちなこと

AI にルールを勝手に変えさせない

このフレームワークでは、AI は明示的に頼まれたときだけ instruction ファイルを編集できるというルールがあります。AI が自分でルールを書き換えてしまうと、運用が崩れます。

ドキュメントを増やしすぎない

「ドキュメントを自動生成する」と聞くと、AI が大量にファイルを作りがちです。配置ルール（project-docs.md / ai-docs.md）を先に固定してから自動生成を許可するのが安全です。

要件を AI に触らせない

client-requirements/ は読み取り専用です。要件は常に人間側が管理し、AI は読むだけ、という線引きを守りましょう。

完璧を目指さない

Step 1 の最小構成だけで十分効果があります。**フレームワークは「育てるもの」**であり、最初から完成形を目指す必要はありません。

7. まとめ

Copilot などの生成AIを導入すると、AI用ドキュメントと開発者向けドキュメントの混在・重複・二重メンテという問題に必ずぶつかります。

copilot-instructions は、これを責務分離で解決します。

docs/ = 人間が読むドキュメント
.ai-instructions/documents/ = AI が実装に使うドキュメント（01-plans/ 〜 08-issues/ のフェーズ構造）
client-requirements/ = クライアント・開発者からの要求（読み取り専用）

そして、導入は一気にやらずに、Step 0 の棚卸し → 最小構成 → ルール分割 → 配置固定 → hooks/workflows → 改善サイクル → チーム展開と段階的に進めるのが現実的です。

AI を「その場の相談相手」ではなく、プロジェクトのドキュメント運用ルールの中で安定して働かせる存在にしたいなら、このフレームワークはかなり有効だと思います。

Repository: https://github.com/h-nasu/copilot-instructions/tree/main
前回記事: https://qiita.com/h-nasu/items/d0b2601bb179a6cdd5eb