Document Development Guide

本ガイドは、aidev-template における開発アプローチである ドキュメント駆動開発（Document Driven Development） 、およびその中核となる 仕様駆動開発（Spec Driven Development: SDD） の原則、設計・開発フェーズの全体プロセス、縦切り開発（slice）と実装ロードマップの運用規約を定義するものです。

1. 開発基本方針（DDD & SDD 原則）

aidev-template は、ドキュメント駆動開発、とくに 仕様駆動開発（Spec Driven Development: SDD） を採用しています。 ユースケースと動作する最小機能単位（feature）に基づく縦切り開発と、仕様を定義して設計書に取り込み開発を繰り返す反復開発手法です。

• 仕様ファーストの徹底: コードを書き始める前に、対象機能の目的や入出力・振る舞い（仕様）を定義します。

• 設計書への取り込み: 定義された仕様をアーキテクチャ設計やコンポーネント詳細設計に取り込み、実装の基盤とします。

• ユースケース・feature 主導: ユーザー目的や価値シナリオをユースケース（usecase）として整理し、コンポーネントを縦切りした動作可能な最小機能単位（feature）ごとに開発を進めます。

• 仕様と設計の反復・継続的同期: 実装中やテスト中に発生した変更や気づきは、速やかに仕様書および設計書にフィードバックし、常にドキュメントとコードの整合性を維持します。

2. 全体開発プロセス (Overall Development Process)

開発プロセスは「設計フェーズ」と「開発フェーズ」の2つの相から構成され、これらを交互に繰り返し行いながらアジャイルに推進します。

設計フェーズ (Design Phase)

1. 最上位設計の策定:

   • 最初に concept.md（概要・目的）および architecture.md（全体構成・技術選定・コンポーネント定義）を作成し、これらに基づいて独立した計画文書である plan.md（全体計画: マイルストーン・フェーズ）を策定します。

2. ユースケース・feature定義:

   • 全体設計に基づき、ユーザー価値やシナリオを定義するユースケース（docs/usecases/USECASE-XXX.md）および動作する最小機能単位（feature）を策定します。

3. 仕様・詳細設計の作成:

   • ユースケースおよび最上位設計に基づき、各ソフトウェアコンポーネントの具体的な機能仕様書（specs/SPEC-XXX.md）と詳細設計書（design.md）を作成します。

開発フェーズ (Development Phase)

1. 実装ロードマップ・実装計画の策定:

   • 縦切り開発 (slice): 複数コンポーネントにまたがる feature の場合は、実装ロードマップ（docs/backlog/roadmaps/<feature-name>.md）を作成し、完了条件および各コンポーネントの依存関係と実装順序を整理します（必要に応じて feature を track に分割）。
   • コンポーネント実装計画: 設計フェーズで作成された specification（機能仕様書）を対象として、docs/backlog/implementations/ 配下に完了条件を含む実装計画（<AppID>-<SPEC-ID>.md 等）を作成します（詳細は backlog-implementation-guide.md および document-implementation-guide.md を参照）。

2. 実装の推進と完了評価の連鎖:

   • 実装計画の遂行と完了: 分割された実装タスクを順次実装・テストし、全実装タスク完了後に実装計画の完了条件を評価・検証します。
   • 実装ロードマップ（slice）の完了: 関連コンポーネントの実装計画がすべて完了した時点で、feature 全体の完了条件を総合検証します。
   • ユースケースの実現確認: 実装ロードマップの完了を受け、親ユースケースの実現条件（シナリオ・受入条件）が充足されたかを最終評価します。

反復開発と仕様・設計の継続的更新 (Iterative Development & Continuous Updates)

• スピード優先アプローチ: 本プロセスでは開発速度を優先し、先行して実装を行い後から仕様を追加・拡充していくアプローチをサポートします。
• 継続的更新原則: 開発フェーズでの気づきや実装結果を反映するため、specification（機能仕様書）および design.md（詳細設計書）は固定化せず、常に更新・同期されていく前提とします。

3. ユースケースと縦切り開発 (Usecase & Slice Development)

複数のソフトウェアコンポーネントが連携する縦切り開発（slice 単位での実装）を行います。

1. ユースケース (docs/usecases/USECASE-XXX.md):

   • ユーザー目的やシナリオを定義し、配下の動作する機能単位（F-<no>: <feature-name>）や実現条件（論理式等）、仕様依存関係（<AppID>:<SpecID>）、シーケンス図等を記録する永続文書です。

2. 実装単位 (feature) と slice:

   • 動作する機能単位（F-<no>: <feature-name>）ごとに一時的な計画情報として実装ロードマップ（docs/backlog/roadmaps/<feature-name>.md）を作成します（ 非追跡対象 ）。
   • 1つの feature（slice）の推奨粒度は「関連する各ソフトウェアコンポーネントの仕様（SPEC）が1つずつ程度」とします。feature を分割して管理する場合は track を使用します。
   • feature の進捗・実装状況は docs/backlog/usecase.md で管理します。

4. 実装ロードマップ (Implementation Roadmap)

実際の開発において複数のソフトウェアコンポーネントが相互に関連・連携して機能開発を進める場合は、各コンポーネントの実装計画や依存関係を整理した実装ロードマップ（docs/backlog/roadmaps/<feature-name>.md）を作成・運用します。

具体的な配置場所、必須セクション構成、ステータス定義、およびMarkdownテンプレートについては、backlog-roadmap-guide.md を参照してください。

5. 共通 ID 形式定義 (Common ID Format Definition)

プロジェクト全体で各種成果物・ドキュメント・要素を識別するために、統一の ID 形式を採用します。

• 基本構文: XXX-YYY[-ZZZ...]
  • XXX: 大文字英字（例: SPEC, DR, USECASE, F, ISSUE, TODO）。HOGE-FOO のようなハイフンによる複合表記も可能です。
  • YYY 以降（ZZZ...）: 数字（連番・サブ番号）。
• 記述表記と桁数指定書式: <XXX-ID> / <XXX-ID(...)>（例: <SPEC-ID>, <DR-ID>）
  • 既定桁数: 既定では 0 埋め 3 桁（<XXX-ID> = <XXX-ID(3)>、例: SPEC-001）。
  • 単一セグメント桁数指定: 括弧内に初期桁数を指定（値の増加に応じて桁拡張）。
    • <XXX-ID(3)>: 0 埋め 3 桁（例: 001）
    • <XXX-ID(2)>: 0 埋め 2 桁（例: 01）
    • <XXX-ID(1)>: 1 桁連番（例: 1）
  • 複数セグメント桁数指定: 複数セグメント（XXX-YYY-ZZZ 等）の場合は各桁数を - で区切って指定。
    • <XXX-ID(3-1)>: YYY が 0 埋め 3 桁、ZZZ が 1 桁（例: XXX-001-1）
    • <XXX-ID(-1)>: YYY が既定（0 埋め 3 桁）、ZZZ が 1 桁（例: XXX-001-1）
• 主要な ID 種別:
  • ユースケース: USECASE-YYY
  • マイルストーン: <M-ID(1)> (M-Y)
  • フェーズ: PHASE-YYY
  • 機能 (feature): <F-ID(1)> (F-Y)
  • 機能仕様書: SPEC-YYY
  • 増分機能仕様書 (feature specification): <SPEC-F-ID(-1)> (SPEC-F-YYY-Z、例: SPEC-F-001-1)
  • 実装タスク詳細 (<TaskID(-1)>): (<SPEC-ID>|<ISSUE-ID>)-Y（<TaskID> のとりうる値は <SPEC-ID> または <ISSUE-ID>、例: SPEC-001-1, ISSUE-001-1）
  • 意思決定記録: DR-YYY
  • 課題・不具合: ISSUE-YYY
  • TODO: TODO-YYY

6. 設計ドキュメント体系（必須・任意）

設計ドキュメントは、プロジェクトおよびコンポーネント開発において必須となるコア設計ドキュメントと、必要に応じて導入する任意ドキュメントに分類されます（※ 詳細な作成基準・記述順序は document-design-guide.md を参照）。また、全体計画を管理する plan.md は設計ドキュメント群とは独立した計画文書として位置づけられます。

必須設計ドキュメント (Required Design Documents)

開発において必ず作成・維持する主要な 5 つの設計ドキュメントです。

1. concept.md (コンセプト): 「何を作るのか（What）」と「なぜ作るのか（Why）」、開発背景やゴールを定義（concept-guide.md 参照）。

2. architecture.md (基本設計・アーキテクチャ): システム全体の構成、ディレクトリ構造、コンポーネント役割、技術スタック、依存関係を定義（architecture-guide.md 参照）。

3. usecases/ (ユースケース・feature定義): ユーザー価値・目的シナリオ、動作する最小機能単位（feature）、実現条件（論理式等）、仕様依存関係を定義（usecase-guide.md 参照）。

4. specs/ (機能仕様書): 各機能・画面ごとの具体的な入出力、画面表示ロジック、ViewModel/Service仕様、受入条件を定義（specification-guide.md 参照）。

5. design.md (詳細設計書): コンポーネント構造、モジュール設計、内部処理ロジック、全仕様書（specs/）のL1/L2マッピングを定義（design-guide.md 参照）。

計画ドキュメント (Planning Document)

• plan.md (全体計画): マイルストーン（重要目標時点）と開発フェーズ（戦略的大日程）を定義する独立した文書です（plan-guide.md 参照）。concept.md および architecture.md を入力として作成されます。

任意設計ドキュメント (Optional Design Documents)

プロジェクトの規模や要件、データベースの有無に応じて追加・導入するドキュメントです。

1. requirements.md (要件定義書): 機能一覧および画面一覧の整理。

2. security.md (セキュリティ定義・ポリシー): セキュリティ基本方針、認証・認可、データ保護、脆弱性対策、シークレット管理。

3. schema.md (データベース設計方針): データベース概要、命名規則、全体ER図、マイグレーション方針。

4. models/ (物理モデル定義): テーブルモデル概要、物理/論理カラム定義、インデックス、アソシエーション。

5. specs/services/ (共通サービス・DTO仕様): 共通サービス概要、インターフェース定義、DTO仕様。

6. その他 (test-spec.md 等): テスト仕様書、各種確認チェックリスト。

7. ドキュメント関係図

必須ドキュメントを軸として、任意ドキュメントがどのように補完・連携されるかの構成図です。

NOTE

線の意味と配色:

• 🟧 実線（橙色）: 必須 INPUTS
• 🟧 破線（橙色）: 任意 INPUTS
• 🟩 実線（ライム色）: 成果物
• 🟩 破線（ライム色）: フィードバック
• 🟦 実線（シアン色）: 参照（ビューから対象への参照）
• 🟦 破線（シアン色）: 関連

ドキュメント別 入力・出力・成果物・参照一覧

ドキュメント / 要素	INPUTS	OUTPUTS	成果物	参照
concept.md	-	plan.md、architecture.md	-	-
plan.md	concept.md、architecture.md	-	-	-
architecture.md	concept.md、requirements.md、security.md	usecases/、design.md、plan.md	-	-
usecases/	architecture.md	specs/、docs/backlog/roadmaps/	-	docs/backlog/usecase.md
specs/	usecases/、specs/services/	design.md、docs/backlog/implementations/	-	backlog/spec.md
design.md	architecture.md、specs/、models/	docs/backlog/implementations/	-	-
requirements.md	-	architecture.md	-	-
security.md	-	architecture.md	-	-
schema.md	-	models/	-	-
models/	schema.md	design.md	-	-
specs/services/	-	specs/	-	-
docs/backlog/roadmaps/	usecases/	-	docs/backlog/implementations/	-
docs/backlog/implementations/	specs/、design.md	-	backlog/tasks/	-
backlog/tasks/	-	実装・自動テスト実行	-	backlog/wbs.md
backlog/issues/	-	-	-	backlog/wbs.md
backlog/todos/	-	-	-	backlog/wbs.md
実装・自動テスト実行	backlog/tasks/	-	specs/、design.md	-
backlog/wbs.md	-	-	-	backlog/tasks/、backlog/issues/、backlog/todos/、docs/backlog/phase.md
backlog/spec.md	-	-	-	specs/、docs/backlog/phase.md
docs/backlog/usecase.md	-	-	-	usecases/、docs/backlog/phase.md
docs/backlog/phase.md	-	-	-	plan.md、backlog/wbs.md、backlog/spec.md、docs/backlog/usecase.md

8. ステータス管理・レビュー連携規約への委譲

各ドキュメント（ユースケース、機能仕様書、実装ロードマップ、実装計画、タスク詳細、課題、TODO、意思決定記録等）のステータス定義、正本管理場所、ライフサイクル遷移、フロントマター規則、および review-document スキルとの連携ルールについては、すべて document-status-guide.md に定義されています。ステータス管理およびレビュー運用時は同ガイドを参照してください。