1. なぜmdファイルが重要か
AI開発ツール（Copilot / Claude Code / Amazon Q）は、プロジェクト内のファイルを参照して動作します。 つまり、プロジェクトに存在する情報の質がそのままAgentの出力品質を決めます。
❌ mdファイルなし
Agentはコードだけを手がかりに推測する。業務ルール・制約・設計意図が伝わらず表面的な実装になる。
レビューで大量の手戻りが発生する。
✅ mdファイルあり
要件・設計・DB定義・既存仕様を参照しながら実装できる。業務ルールを踏まえた実装になり、
テスト観点も充実する。手戻りが大幅に減る。
原則： 「Agentに動かせる前に、まず人間が読んで理解できるドキュメントを整備する」。
これがAgent開発の品質を左右する最重要ポイントです。
2. 推奨ディレクトリ構成
以下の構成を推奨します。プロジェクトの規模に応じて調整してください。
project-root/
├── rules/ # Agentが必ず読むルール群
│ ├── project_info.md # プロジェクト概要・技術スタック・制約
│ ├── coding_rules.md # コーディング規約
│ ├── architecture_rules.md # アーキテクチャ方針・責務分離
│ ├── document_rules.md # ドキュメント管理ルール
│ └── agent_operation_rules.md # Agent運用ルール
│
├── docs/
│ ├── dbinfo/ # テーブル定義・ビュー定義
│ │ └── tables/
│ │ └── TABLE_NAME.md # テーブルごとに1ファイル
│ │
│ ├── official/
│ │ ├── analysis/ # 分析フェーズの成果物
│ │ │ ├── screen_list.md # 画面一覧
│ │ │ ├── function_list.md # 機能一覧
│ │ │ └── table_usage_matrix.md # テーブル利用対応表
│ │ │
│ │ ├── design/ # 設計フェーズの成果物
│ │ │ ├── basic_design.md # 基本設計
│ │ │ ├── api_list.md # API一覧
│ │ │ ├── screen_design/ # 画面設計書（画面ごと）
│ │ │ └── api_detail/ # API詳細設計書（API ごと）
│ │ │
│ │ └── test/ # テスト仕様書
│ │ └── unit_test_spec.md
│ │
│ └── wip/ # 作業中・引き継ぎ
│ ├── session_handoff.md # セッション引き継ぎ
│ ├── agent_task_board.md # タスク管理ボード
│ └── review_queue.md # レビュー待ちキュー
│
└── src/ # ソースコード
rules/ の役割
Agentへの作業依頼時に必ず読み込ませるルール群です。セッション開始時のプロンプトで「rules/配下を全て読んでください」と指示します。
| ファイル | 記載内容 |
|---|---|
project_info.md | プロジェクト名・目的・技術スタック・言語バージョン・フレームワーク・DB種別・制約事項 |
coding_rules.md | 命名規則・責務分離方針・エラーハンドリング・コメント方針・禁止事項 |
architecture_rules.md | レイヤー構成・依存方向・共通処理の配置・ファイル配置ルール |
document_rules.md | ドキュメントの配置場所・命名規則・更新ルール・ステータス管理 |
agent_operation_rules.md | Agent役割分担・並行化ルール・成果物ステータス・禁止事項 |
docs/ の役割
Agentが参照する設計情報・DB情報・作業状況を格納します。
| ディレクトリ | 役割 | 更新タイミング |
|---|---|---|
dbinfo/tables/ | テーブル定義（カラム名・型・制約・説明） | DB変更時に随時更新 |
official/analysis/ | 分析フェーズの成果物（画面一覧・機能一覧・リスク一覧） | 分析完了後に確定 |
official/design/ | 設計フェーズの成果物（基本設計・API設計・画面設計） | 設計完了後に確定 |
official/test/ | テスト仕様書・テスト観点一覧 | テスト設計完了後に確定 |
wip/ | 作業中の草案・セッション引き継ぎ・タスクボード | 随時更新 |
3. 要件定義フェーズ
要件定義では、Agentが後続フェーズで参照できる形に情報を整理します。
1
project_info.md を作成する
プロジェクト概要・目的・技術スタック・制約をまとめます。Agentが最初に読む最重要ファイルです。
2
要件をmdファイルに落とし込む
機能要件・非機能要件・業務ルール・制約を構造化して記述します。箇条書きより表形式の方がAgentが参照しやすいです。
3
テーブル定義をmdファイルに整備する
既存DBがある場合はテーブル定義をmdファイルに変換します。Agentはコードよりmdファイルの方が確実に参照します。
4
Agentに分析を依頼する
整備したmdファイルを参照させて、機能一覧・画面一覧・リスク一覧の草案を生成させます。
テーブル定義mdファイルの例：
カラム名・データ型・NULL可否・デフォルト値・説明・インデックス情報を含めてください。 Agentはこれを参照してSQL・モデルクラス・バリデーションを生成します。
カラム名・データ型・NULL可否・デフォルト値・説明・インデックス情報を含めてください。 Agentはこれを参照してSQL・モデルクラス・バリデーションを生成します。
4. 基本設計フェーズ
基本設計では、実装に先立つ構造整理を行います。基本設計が固まる前に実装を始めてはいけません。
| 成果物 | 内容 | Agentへの指示例 |
|---|---|---|
| API一覧 | エンドポイント・HTTPメソッド・概要・認証要否 | 「機能一覧を元にREST API一覧を作成してください」 |
| 認証・認可設計 | 認証方式・権限モデル・ロール定義 | 「要件定義を元に認証設計を作成してください」 |
| エラーコード一覧 | エラーコード・メッセージ・HTTPステータス | 「プロジェクト方針に沿ったエラーコード一覧を作成してください」 |
| 画面設計方針 | 画面遷移・共通コンポーネント・UIガイドライン | 「画面一覧を元に画面設計方針を整理してください」 |
並行化前に固定すべき事項： ディレクトリ構成・命名規則・認証方式・API共通仕様・エラーコード方針。
これらが固まる前に複数のAgentを並行稼働させると、成果物が矛盾します。
5. 詳細設計フェーズ
詳細設計では、実装可能な粒度まで設計を詳細化します。この粒度が実装品質を直接左右します。
1
API詳細設計書を作成する
リクエスト/レスポンスの型・バリデーションルール・業務ロジック・エラーケース・使用テーブルを明記します。
2
画面設計書を作成する
画面項目・入力制約・表示条件・イベント処理・API呼び出しタイミングを明記します。
3
テスト観点を整理する
詳細設計の段階でテスト観点を洗い出しておきます。設計と同時に観点を整理することで漏れを防ぎます。
4
Agentにレビューを依頼する
詳細設計書をAgentにレビューさせ、考慮漏れ・矛盾・曖昧点を指摘させます。セッションを変えて俯瞰的に確認させます。
詳細設計書の品質チェックリスト：
- 業務ルールが具体的に記述されているか（「適切に処理する」ではなく「〇〇の場合は△△する」）
- エラーケースが網羅されているか
- 使用するテーブル・カラムが明示されているか
- 他機能との依存関係が明示されているか
- テスト観点が記述されているか
6. 実装フェーズ
詳細設計が確定してからAgentに実装を依頼します。
| 指示のポイント | 内容 |
|---|---|
| 参照ファイルを明示する | 「rules/配下・docs/dbinfo/・docs/official/design/XXX.md を参照してください」 |
| 対象範囲を明示する | 「今回実装するのは〇〇APIのみです。他のファイルは変更しないでください」 |
| 既存コードの方針を伝える | 「既存の〇〇クラスと同じパターンで実装してください」 |
| 不明点の扱いを指示する | 「不明点は推測で実装せず、選択肢を提示して確認を求めてください」 |
| 実装前にプランを提示させる | 「実装前に変更するファイルと変更内容の概要を提示し、承認を得てから実装してください」 |
注意： Agentが「設計と異なる判断が必要」と判断した場合は、独断で実装せず設計へ差し戻させてください。
設計逸脱を検出したら報告させる指示を含めることが重要です。
7. テストフェーズ
テストは設計・実装の妥当性を収束させる工程です。詳細設計書とテスト観点を参照させてテストを生成させます。
単体テスト
詳細設計書の業務ロジック・バリデーション・エラーケースを網羅するテストを生成させる
結合テスト観点
API一覧・画面設計書を参照させて、エンドツーエンドの観点を整理させる
テスト結果レポート
観点・入力・期待値・実測値・判定・備考を含むレポートを生成させる
テスト観点の補完： 境界値・分岐の真偽両側・0件/1件/複数件・最大値/最小値・NULL/空文字・
権限なしユーザー・同一キーの重複データ など、Agentに観点の漏れを確認させてください。
8. Agent並行運用（GitHub Copilot実態ベース）
GitHub Copilot は「1チャット = 1作業コンテキスト」です。完全同時実行のマルチエージェントではなく、 複数セッションを人が交通整理して回す疑似並行運用が現実解です。
まず押さえる実態
| 観点 | 実際 | 運用方針 |
|---|---|---|
| 同一セッション内での同時実行 | 不可（1本の対話で順番実行） | 1セッション1タスクを徹底する |
| 複数セッションの同時運用 | 可能（チャット分割・ウィンドウ分割） | タスクボードで担当と対象ファイルを明示する |
| 同一ファイルの同時編集 | 競合しやすい | ファイルロック（担当固定）を必須にする |
| 設計未確定のまま並行実装 | 高確率で矛盾が発生 | 基盤方針確定後に並行化する |
役割分担（レーン分割）
| レーン | 担当範囲 | 成果物 | 次レーンへ渡す条件 |
|---|---|---|---|
| 分析レーン | 現行調査・影響範囲・リスク整理 | docs/official/analysis/ 配下 | 仕様の未確定事項が明示されていること |
| 設計レーン | API/画面/テスト観点の詳細化 | docs/official/design/ 配下 | レビュー待ち以上であること |
| 実装レーン | 確定設計に基づく実装・単体テスト | src/ 配下 + テストコード | 変更点がレビューキューに登録済みであること |
| レビューレーン | 成果物の妥当性確認・差戻し判断 | docs/wip/review_queue.md | 指摘の反映方針が決まっていること |
疑似並行運用の手順
- 並行化前に固定する: 命名規則、API共通仕様、認証方式、ディレクトリ構成、変更禁止領域。
- タスクを 30-90 分の粒度に分割し、1タスク1セッションに割り当てる。
- 着手前に docs/wip/agent_task_board.md へ「担当」「対象ファイル」「依存」「着手条件」を記入する。
- 同一ファイルは同時編集しない。必要な場合は先に担当調整し、先行担当が完了後に引き継ぐ。
- 区切りごとに docs/wip/session_handoff.md と docs/wip/review_queue.md を更新し、次レーンへ渡す。
- レビュー完了前の成果物は正本扱いしない。必ず差戻し可否を明示する。
並行化してはいけない対象： 同一ファイルへの無調整同時編集・未確定基盤を前提にした大量実装・
レビュー未了成果物を正本として次工程へ流すこと。
実務のコツ： 「完全同時実行」を目指すより、短いタイムボックスでの高頻度同期を優先してください。
Copilot運用では、タスクの独立性と引き継ぎmdの品質が速度を決めます。
9. セッション管理とAgent用mdファイル
Copilotはセッションをまたぐと文脈が弱くなるため、mdファイルを「外部メモリ」として運用します。
最低でも agent_task_board.md / session_handoff.md / review_queue.md の3点を運用してください。
必須（最小セット）
agent_task_board.md / session_handoff.md / review_queue.md
推奨（安定運用）
file_lock.md / agent_briefs/TASK-xxx.md を追加し、競合と認識ズレを減らす
| ファイル | 記載内容 | 更新タイミング | 運用ポイント |
|---|---|---|---|
docs/wip/agent_task_board.md | タスク一覧・担当・依存・対象ファイル・着手条件 | 着手前とステータス変化時 | 「誰が何を触るか」を最初に固定する |
docs/wip/session_handoff.md | 今回の完了事項・未完了事項・次回開始手順・判断待ち | セッション終了時 | 次の担当が10分で再開できる粒度で書く |
docs/wip/review_queue.md | レビュー対象・観点・判定・差戻し内容・再レビュー期限 | レビュー依頼・完了時 | レビュー待ちと修正中を分離して管理する |
docs/wip/file_lock.md（推奨） | 編集中ファイルの担当・開始時刻・解除条件 | 編集開始/終了時 | 同一ファイル競合を予防する |
docs/wip/agent_briefs/TASK-ANA/DSN/IMP-xxx.md（推奨） | タスク単位の前提・入力資料・完了条件・禁止事項（分析/設計/実装で分離） | タスク作成時 | フェーズごとの観点漏れとプロンプト揺れを抑える |
最小テンプレート例（コピーベース）
# docs/wip/agent_task_board.md
最終更新: YYYY-MM-DD HH:MM
| タスクID | 状態 | 担当 | 対象ファイル | 依存 | 着手条件 |
|---|---|---|---|---|---|
| TASK-101 | 進行中 | 設計レーン | docs/official/design/api_xxx.md | TASK-100 | 要件確定 |
状態: 未着手 / 進行中 / レビュー待ち / 完了 / 保留
# docs/wip/session_handoff.md
最終更新: YYYY-MM-DD HH:MM
## 今回完了
- TASK-101 設計草案をレビュー待ちへ変更
## 継続タスク
- TASK-102 実装レーンは TASK-101 承認後に着手
## 次回開始手順
1. rules/ 配下を再読
2. agent_task_board.md で進行中を確認
3. review_queue.md で差戻し有無を確認
# docs/wip/review_queue.md
最終更新: YYYY-MM-DD HH:MM
| 対象ID | 対象ファイル | 判定 | 指摘概要 | 対応担当 | 期限 |
|---|---|---|---|---|---|
| RV-301 | docs/official/design/api_xxx.md | 差戻し | 例外ケース不足 | 設計レーン | YYYY-MM-DD |
判定: 承認 / 条件付き承認 / 差戻し
# docs/wip/agent_briefs/TASK-DSN-101.md
最終更新: YYYY-MM-DD HH:MM
## 目的
- API 例外ケースの設計不足を解消する
## 完了条件
- 例外ケースを3分類で設計書へ反映
- review_queue に再レビュー依頼を登録
## 対象ファイル
- docs/official/design/api_xxx.md
## 変更禁止
- rules/ 配下
- src/ 配下
セッション開始時のプロンプト例：
「rules/配下を全て読んでください。次に docs/wip/session_handoff.md、 docs/wip/agent_task_board.md、docs/wip/review_queue.md、docs/wip/agent_briefs/ の順で確認し、 進行中タスク・依存タスク・レビュー待ちを一覧化してください。 自分が編集可能なファイルを明示し、作業計画を提示してください。承認を得るまで実装を開始しないでください。」
「rules/配下を全て読んでください。次に docs/wip/session_handoff.md、 docs/wip/agent_task_board.md、docs/wip/review_queue.md、docs/wip/agent_briefs/ の順で確認し、 進行中タスク・依存タスク・レビュー待ちを一覧化してください。 自分が編集可能なファイルを明示し、作業計画を提示してください。承認を得るまで実装を開始しないでください。」