AIに最短で正しく実装してもらうには、まずAIが迷わない 最小限の高品質ドキュメント を用意するのが近道です。本記事は公開リポジトリ「ai-driven-design」の Quickstart をベースに、今日から回せる実務フローを簡潔にまとめた「まずやってみよう」版です。
- 公開リポジトリ: https://github.com/feel-flow/ai-driven-design
- 参考ドキュメント:
docs/GETTING_STARTED.md
一応、README読んでもらえたら嬉しいです！
ねらい（2時間で到達したい状態）
-
docs/MASTER.mdが最新で最初に読む統合ハブになっている - Single Source of Truth（SSOT）が決まり、重複と矛盾がない
- 直近の1機能で「要件→設計→テスト→実装」が1ループ回る
まずやること（15分チェックリスト）
-
docs/MASTER.mdを最低限アップデート
- プロジェクト識別（名前/バージョン/最終更新日/使用AI）
- 技術スタック要約（FE/BE/DB/Infra）
- 守るべきルール（命名/エラー/テスト/マジックナンバー禁止）
- 詳細ドキュメントへの索引（
PROJECT/ARCHITECTURE/DOMAIN/TESTING/DEPLOYMENT）
docs/06-reference/GLOSSARY.md
- 用語を1画面分で定義（同義語は排除し統一）
docs/06-reference/DECISIONS.md
- 直近の重要決定を1行で追記（履歴として残す）
新規で始める（~60分）
- 最小3ファイルだけ埋める（30分）
-
docs/MASTER.md… 上記4点＋「読ませる順序」を明記 -
docs/01-context/PROJECT.md… Why/Who/What/Success＋MVPの受け入れ基準 -
docs/02-design/ARCHITECTURE.md… レイヤ/依存/データフロー/例外/テスト層割合 - 余力:
docs/02-design/DOMAIN.mdに用語と主要エンティティを箇条書き
-
- 最初の1機能を要件化（15分）
-
PROJECT.mdにユーザーストーリー1件＋受け入れ基準（Given/When/Then） -
TESTING.mdにその機能のテスト観点（Unit中心、必要に応じてIntegration/E2E）
-
- AI初回同期（15分）
- 下の「AIに読ませる順序」で MASTER→PROJECT→ARCHITECTURE（→DOMAIN）だけ参照し実装指示
途中参加/既存を寄せる（~90分）
- ドキュメント棚卸し（20分）: 要件/設計/用語/決定/テスト/運用のSSOTを1ファイルずつ決める
- 統合と整流化（40分）: 重複はSSOTに集約、他は参照に置換。
MASTER.mdに読ませる順序と参照禁止/推奨を明記 - AIスモーク（30分）: 小タスクをAI実装し、不足ドキュメントを逆引きで補完
AIに読ませる順序と粒度（トークン最適化）
-
docs/MASTER.md（必須） -
docs/01-context/PROJECT.md（機能のWhy/受け入れ基準） -
docs/02-design/ARCHITECTURE.md（層/依存/エラー/データフロー） -
docs/02-design/DOMAIN.md（必要時のみ） docs/04-quality/TESTING.md-
docs/05-operations/DEPLOYMENT.md（必要時のみ） -
docs/06-reference/[GLOSSARY/DECISIONS]（曖昧さ解消）
ポイント
- 要約→必要に応じ詳細へ。全読みは避ける
- 情報が無い箇所はAIに「明示的に質問」させるルールを提示
すぐ貼って使えるプロンプト（新規機能）
目的: リポジトリのAI駆動ルールに従い、<機能名> を実装する。
参照順序（この順で読み、他は見ない）:
- docs/MASTER.md
- docs/01-context/PROJECT.md
- docs/02-design/ARCHITECTURE.md
- （必要時）docs/02-design/DOMAIN.md
要件: PROJECT.md の受け入れ基準を満たすこと。テストは TESTING.md のパターン・命名に従い同時生成。
制約: マジックナンバー/ハードコード禁止（定数or設定から注入）。型安全/エラーパターンは PATTERNS.md に準拠。
出力: 変更ファイル一覧→実装→テスト→要点サマリ。疑義は実装前に質問。
ドキュメント逆引き（不足抽出）
目的: 生成物から不足ドキュメントを特定し、追記案を作る。
入力: 直近の変更差分/テスト失敗内容
出力: 追記が必要なファイルと具体追記案（箇条書き）。SSOT原則に従い、重複は参照化する提案も含める。
最低限のDefinition of Done（AI駆動用）
- 受け入れ基準がテストで裏付け（Unit中心、必要に応じIntegration/E2E）
- マジックナンバー禁止・定数/設定化（単位/範囲の明示）
- 例外/エラーはResult等で一貫処理・ログ指針に準拠
-
MASTER.mdの方針と矛盾しない
1スプリント導入の例
- Day 1: MASTER/PROJECT/ARCHITECTURE の最小充足、GLOSSARY 着手
- Day 2: 代表機能をAI実装→テスト同時生成→不足ドキュメントを逆引きで補完
- Day 3: SSOT徹底（重複排除/参照化）→AIスモーク→CIで自動テスト常時化
よくある落とし穴
- ドキュメントは量より質：1枚要約→詳細は参照の多層化
- ファイル横断の矛盾：SSOT決定＋
DECISIONSで履歴化 - 用語ブレ：
GLOSSARYとコード命名を常に一致
おわりに（MCP対応準備中/Starのお願い）
このドキュメント群は、Model Context Protocol（MCP）から直接参照できるよう準備中です。対応が進み次第、リポジトリに手順と設定例を追加します。
本リポジトリはパブリックです。より良いAI駆動開発に育てていきたいので、参考になったらぜひ Star をお願いします！