3つの基本思想
関心の分離
「なぜ (Vision)」「何を (Requirements)」「どうやって (Specifications)」を明確に分離し、複雑さを管理します。
階層的ナビゲーション
全てのディレクトリに `index.md` を配置。そのディレクトリの「目次」兼「要約」として機能し、全体像の把握を容易にします。
LLMへの最適化
タスクに関連するファイルをピンポイントでLLMに与え、コンテキスト精度を高め、生成品質を最大化します。
ディレクトリ構成詳解
この構成の鍵は、各ディレクトリに配置された `index.md` です。
これは、そのディレクトリ内のドキュメントの「目次」と「要約」の役割を果たし、
人間とAIが全体像を素早く理解するための入り口となります。
📁 docs/
├── 📄 index.md # プロジェクト全体のポータル
│
├── 📁 00_vision/ # なぜ作るのか (目的、全体像)
│ ├── 📄 index.md # このディレクトリの概要
│ ├── 📄 01_project_vision.md # ビジネスゴール、KPI、解決する課題、目指す姿
│ ├── 📄 02_architecture.md # 全体のシステム構成図、技術選定理由
│ └── 📄 03_glossary.md # プロジェクト固有の用語を定義
│
├── 📁 01_requirements/ #【非エンジニア層】何を要求するか
│ ├── 📄 index.md
│ └── 📁 features/ #【機能テストの元】機能中心の要求管理
│ ├── 📄 index.md # 全機能の目次とステータス一覧
│ └── 📁 001_dashboard/ # ダッシュボード機能
│ ├── 📄 overview.md # 機能の目的、ユーザーストーリー
│ ├── 📄 use_cases.md # 具体的な利用シナリオ
│ ├── 📄 screen_specs.md # 画面仕様 (Figmaリンク等を推奨)
│ └── 📄 non_functional.md # 非機能要件 (オプション)
│
├── 📁 02_specifications/ #【エンジニア/AI層】どうやって作るか
│ ├── 📄 index.md
│ ├── 📁 backend/ # MVCアーキテクチャ
│ │ ├── 📄 index.md
│ │ ├── 📁 models/ # データとビジネスロジック
│ │ │ ├── 📄 user_model.md
│ │ │ └── 📄 role_model.md
│ │ ├── 📁 views/ # データの出力・表示 (APIレスポンス定義など)
│ │ │ └── 📄 user_view.md
│ │ └── 📁 controllers/ # リクエストを処理し、ModelとViewを連携
│ │ └── 📄 user_controller.md
│ │
│ └── 📁 frontend/ # Featureベースのアーキテクチャ
│ ├── 📄 index.md
│ ├── 📁 features/ # 機能ごとのコンポーネント群
│ │ ├── 📁 dashboard/
│ │ │ ├── 📄 index.md
│ │ │ └── 📁 components/
│ │ │ └── 📄 sales_chart.md
│ │ └── 📁 profile/
│ │ ├── 📄 index.md
│ │ └── 📁 components/
│ │ └── 📄 edit_form.md
│ └── 📁 shared/ # 共通コンポーネント
│ └── 📄 button.md
│
└── 📁 03_guides/ # 開発を円滑に進めるための情報
├── 📄 index.md
├── 📄 01_development_setup.md # 開発環境の構築手順
├── 📄 02_coding_standards.md # コーディング規約
└── 📄 03_branch_strategy.md # Gitのブランチ運用ルール
ワークフロー・シナリオ
「要望」から「機能」、そして「実装」へと至るVモデル開発プロセスを体験します。
要望の発生と機能定義
PMがAIに「プロフィール編集機能が欲しい」と伝えます。AIは対話し要求を具体化、overview.md を作成します。
実践例：要求仕様作成プロンプトの活用
使用プロンプト：
📥 ユーザー入力
"ユーザーが自分のプロフィール情報を編集できる機能が欲しい"
📤 AI出力
docs/01_requirements/features/003_profile_edit/overview.md を生成
機能の詳細設計
PMはAIと協業し、use_cases.md や screen_specs.md を作成。機能の具体的な振る舞いを定義します。
01_requirements ディレクトリ完成プロセス
🎯 同じプロンプトで追加作成
追加指示： "さらに利用シナリオと画面仕様も作成してください"
🔄 index.md の自動更新
AIが新機能を docs/01_requirements/index.md に自動追加し、機能一覧を最新状態に保持
AIによる技術仕様への翻訳
確定した要求を基に、AI AgentがバックエンドAPIやフロントエンドコンポーネントの技術仕様書を自動生成します。
技術仕様翻訳プロンプトの実行
📤 出力：02_specifications への自動生成
エンジニアによる技術レビュー
エンジニアはAIが生成した技術仕様書をレビューし、設計の妥当性を迅速に確認・承認します。
AIによるコード生成とマージ
承認された仕様書に基づき、AIがコードとテストを生成。最終レビューを経てマージし、開発プロセスが完了します。
コード生成プロンプトの実行
承認された技術仕様書を基に、実装コード・テストコード・ドキュメントを一括生成
共同作業モデル
非エンジニアとエンジニア/AIがスムーズに連携するために、ドキュメントを「要求レイヤー」と「技術レイヤー」の2層に分けます。
👤 非エンジニア層（要求レイヤー）
関心事：「何が見えるか」「何ができるか」
📁 01_requirements/
└── 📁 features/
└── 📁 001_dashboard/
├── 📄 overview.md
└── 📄 screen_specs.mdPMや企画担当者は、これらのファイルに、機能の目的や画面の振る舞いを自然言語で記述・修正します。
役割：「要求」を「技術仕様」に翻訳し、コードを生成する
🛠️ エンジニア層（技術レイヤー）
関心事：「どうやって作るか」「どう動くか」
📁 02_specifications/
├── 📁 backend/
└── 📁 frontend/AIが生成した技術仕様書やソースコードをレビューし、品質を担保します。複雑なロジックの設計や最終的な意思決定に集中します。
ドキュメントとコードの連携方法
AI Agentが変更の影響範囲を正確に把握できるよう、各技術仕様書ファイルにメタデータを記述し、仕様書とソースコードを紐付けます。
メタデータ仕様の例
---
# この仕様が依存する他の仕様書
depends_on:
- "docs/specifications/backend/data_models/user_model.md"
- "docs/specifications/backend/data_models/role_model.md"
# この仕様に対応するソースコード
target_files:
- "src/backend/app/api/v1/endpoints/users.py"
- "tests/backend/api/v1/test_users.py"
---
# ユーザーAPI仕様
...📎 depends_on
この仕様が依存する他の技術仕様書のパスを記述。AIが依存関係を理解するのに役立ちます。
🎯 target_files
この仕様に基づいて生成・修正されるソースコードファイルのパスを記述。仕様とコードを直接紐付けます。
プロンプト活用
AIエージェントへの指示は、システムプロンプトとタスクプロンプトを組み合わせて行います。
これにより、一貫性と精度の高い出力を得ることができます。
AI開発エージェント指示プロンプト体系
システムプロンプト
基盤となる行動原則とドキュメント規約
AIエージェントの基本的な役割、行動原則、ドキュメント規約を定義します。全ての判断と行動の基盤となる主たる指示プロンプトです。
📄 システムプロンプトを確認タスク専用プロンプト
投入方法
# AIエージェントの基本設定
<SystemPrompt>...</SystemPrompt>
# 実行したいタスクの指示
<TaskPrompt>...</TaskPrompt>
# ユーザーからの具体的な入力
<UserInput>...</UserInput>