Document Development Guide

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

1. 開発基本方針（DDD × SDD × インクリメンタル開発）

aidev-template は、ドキュメント駆動開発（DDD）を基盤とし、仕様駆動開発（SDD）による「仕様ファースト」、およびインクリメンタル開発による「増分仕様主導の実装」を融合した3層構成を採用しています。

• ドキュメント駆動開発 (DDD: Document Driven Development):

  • コード先行ではなく、要件・アーキテクチャ・設計・計画をドキュメントとして可視化し、ドキュメントをプロジェクトの正本（Single Source of Truth）として開発を推進します。

• 仕様駆動開発 (SDD: Spec Driven Development):

  • 仕様ファーストの徹底: コードを書き始める前に、必ず対象機能の入出力、画面表示ロジック、ViewModel/Service仕様、受入条件などの「仕様」を明確に定義します。
  • ユースケース・feature 主導: ユーザー目的や価値シナリオをユースケース（usecase）として定義し、コンポーネントを縦切りした動作可能な最小機能単位（feature）ごとに仕様を導出します。
  • 詳細設計への取り込み: 定義された仕様をコンポーネント詳細設計（design.md）に取り込み、実装の構造的基盤とします。

• インクリメンタル開発 (Incremental Development):

  • 常に増分仕様で実装を推進: 実装（コード作成・修正）を行う際は、常に増分機能仕様書（Incremental Specification: specs/incremental/<SPEC-I-ID>.md）を起点 とします。新機能開発はもちろん、既存機能の拡張、仕様改修、バグ修正（ISSUE対応）であっても、必ず自己完結した増分仕様を作成（または既存仕様を直接更新）して実装に臨みます。
  • 1:1:1 の直結構造: 増分仕様（<SPEC-I-ID>）、実装計画（<component>/backlog/implementations/<SPEC-I-ID>.md）、タスク詳細（<component>/backlog/tasks/<SPEC-I-ID>.md）を 1:1:1 で対応付け、小さく安全な反復サイクルで実装・検証を完結させます。

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

開発プロセスは、上位の構造や方針を定義する「設計フェーズ」と、増分仕様を起点として反復実装を行う「インクリメンタル実装フェーズ」の2相で構成されます。これらを交互に繰り返しながらアジャイルに推進します。

設計フェーズ (Design Phase)

1. 最上位設計の策定:

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

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

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

3. 機能仕様・共通仕様・詳細設計の作成:

   • ユースケースおよび全体設計に基づき、各ソフトウェアコンポーネントの機能仕様書（specs/[<category>/]<SPEC-ID>.md）、共通仕様書（SPEC-C-<name>.md）、および詳細設計書（design.md）を作成します。

インクリメンタル実装フェーズ (Incremental Implementation Phase)

1. 増分仕様の策定（仕様ファーストの徹底）:

   • 実装（コード変更）を行う前に、必ず specs/incremental/ 配下に自己完結した増分機能仕様書（specs/incremental/<SPEC-I-ID>.md）を作成します。
   • 対象の機能仕様書（<SPEC-ID>.md）に増分仕様をマウントし、仕様台帳（specs/index.md, specs/index.link.tsv）を同期します。

2. 実装計画・タスク詳細の策定 (1:1:1 原則):

   • 縦切り開発 (slice): 複数コンポーネントにまたがる feature の場合は、実装スライス（docs/backlog/slices/<slice-name>.md）を作成し、各コンポーネントの依存関係と実装順序を整理します。
   • コンポーネント実装計画とタスク詳細: 増分仕様（<SPEC-I-ID>）に対して、1つの実装計画（<component>/backlog/implementations/<SPEC-I-ID>.md）と1つのタスク詳細ファイル（<component>/backlog/tasks/<SPEC-I-ID>.md）を作成します（詳細は backlog-implementation-guide.md および backlog-task-guide.md を参照）。

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

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

インクリメンタル開発のケース別フロー (Case-by-Case Development Flow)

インクリメンタル開発における作業着手時は、変更の性質および規模に応じて以下の3つのケースに分類して運用します。

1. ケース 1: 新規機能の開発 (New Feature):
   • 新規に増分機能仕様書（specs/incremental/<SPEC-I-ID>.md）を作成します。
   • 対応するコンポーネント実装計画（<component>/backlog/implementations/<SPEC-I-ID>.md）および実装タスク詳細ファイル（<component>/backlog/tasks/<SPEC-I-ID>.md）を作成（1:1:1 原則）し、通常フローで実装・テストを遂行します。
2. ケース 2: 契約に変更のある仕様変更 (Breaking / Contract Spec Change):
   • API入出力、外部インターフェース、データモデル構造、公開振る舞い契約等に変更が及ぶ仕様変更の場合、新規に増分機能仕様書（specs/incremental/<SPEC-I-ID>.md）を作成 します。
   • 親機能仕様書（<SPEC-ID>.md）にマウントし、ケース1と同様に実装計画および実装タスク詳細ファイルを新規作成して実装・検証を遂行します。
3. ケース 3: 契約に変更のない仕様変更・不具合修正・脆弱性修正・リファクタリング・パフォーマンス改善 (Non-Contract Change / Bugfix / Refactor / Performance):
   • 外部契約に変更のない仕様修正（誤字・表現の軽微な修正等）、不具合修正（バグ修正）、脆弱性修正、内部リファクタリング、およびパフォーマンス改善の場合は、既存の増分仕様書を直接更新 します。
   • その上で、コード変更対象の規模に応じて以下のいずれかで進めます：
     • 超軽量変更（1ファイルかつ10行以下）:
       • 実装計画は作成せず に直接作業を実施します。
       • 作業完了後、対象の既存実装タスク詳細ファイル（<component>/backlog/tasks/<SPEC-I-ID>.md）の「実装メモ」セクションに作業内容・修正理由を記録します。
     • 通常変更（複数ファイル、または11行以上）:
       • 既存の実装タスク詳細ファイル（<component>/backlog/tasks/<SPEC-I-ID>.md）を WIP ステータス に戻します。
       • 変更内容・追加タスクを実装タスク詳細ファイルに反映して実装・検証を遂行します。
       • 上位ステータスの非変更ルール: この際、実装計画（Implementation Plan）や実装スライス（Slice）など上位ドキュメントのステータスは変更しません。

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

• スピード優先アプローチ: 本プロセスでは開発速度を優先し、先行して最小限の増分仕様で実装を行い、後から仕様を追加・拡充していくアプローチをサポートします。
• 継続的同期原則: 実装中の気づきや変更は、即座に増分仕様、機能仕様、および詳細設計書（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/slices/<slice-name>.md）を作成します（ 追跡対象 ）。
   • 1つの feature（slice）の推奨粒度は「関連する各ソフトウェアコンポーネントの仕様（SPEC）が1つずつ程度」とします。feature を分割して管理する場合は track を使用します。
   • feature の進捗・実装状況は docs/backlog/usecase.md で管理します。

4. 実装スライス (Implementation Slice)

実際の開発において複数のソフトウェアコンポーネントが相互に関連・連携して機能開発を進める場合は、各コンポーネントの機能仕様や実装計画、依存関係を整理した実装スライス（docs/backlog/slices/<slice-name>.md）を作成・運用します（ 追跡対象 ）。基本として追跡対象から非追跡対象へのリンクは禁止されていますが、実装スライスから実装計画（非追跡対象）へのリンクは特別に許可されます（実装計画が完了した際は、リンクを - に更新します）。

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

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

設計ドキュメントは、プロジェクトおよびコンポーネント開発において必須となるコア設計ドキュメントと、必要に応じて導入する任意ドキュメントに分類されます（※ 詳細な作成基準・記述順序は 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/ (機能仕様書・増分仕様書・共通仕様書): 各機能ごとの機能仕様書（<SPEC-ID>.md）、実装の起点となる増分機能仕様書（incremental/<SPEC-I-ID>.md）、および共通仕様書（SPEC-C-<name>.md）を定義（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/ (物理モデル定義): テーブルモデル概要、物理/論理カラム定義、インデックス、アソシエーション。

6. 文書レイヤーとリンク制限規則 (Document Layers & Link Rules)

ドキュメント間の疎結合性と抽象度の一貫性を保つため、docs/ 配下の主要ドキュメントを 5 つのレイヤー（L1〜L5）で管理し、リンク可能範囲を自レイヤーおよび上下1層（±1層: $L_{n-1} \sim L_{n+1}$）までに制限します。

• 上下1層（±1層）制限: 所属レイヤーの同一階層および上下1層（$L_{n-1} \sim L_{n+1}$）以外のレイヤーへのリンクは不適合（禁止）とします。
• 対象の限定: レイヤーに定義された文書間のみを対象とし、ガイドライン（docs/guide/）、ツール定義（docs/tools.md）、意思決定記録（docs/decision-records/）などは本制約の対象外（自由参照可）とします。

7. ドキュメント関係図

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

Note

線の意味と配色:

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

flowchart TD
    subgraph CoreRequired ["必須設計ドキュメント (Required)"]
        CONCEPT["concept.md"] --> ARCHITECTURE["architecture.md"]
        ARCHITECTURE --> USECASES["usecases/"]
        USECASES --> SPECS["specs/<br/>(機能仕様: SPEC-XXX.md)"]
        ARCHITECTURE --> DESIGN["design.md"]
        SPECS --> DESIGN
    end

    PLAN_DOC["plan.md"]
    CONCEPT --> PLAN_DOC
    ARCHITECTURE --> PLAN_DOC

    subgraph OptionalDocs ["任意設計ドキュメント (Optional)"]
        REQ["requirements.md"] -.-> ARCHITECTURE
        SEC["security.md"] -.-> ARCHITECTURE
        SCHEMA["schema.md"] -.-> MODELS["models/"]
        MODELS -.-> DESIGN
    end

    subgraph IncrementalDev ["インクリメンタル開発・実装実行"]
        SPECS --> INCR_SPECS["specs/incremental/<br/>(増分仕様: SPEC-I-XXX.md)"]
        USECASES --> SLICE["docs/backlog/slices/"]
        SLICE -->|"構成"| IMPL_PLAN["backlog/implementations/<br/>(<SPEC-I-ID>.md)"]
        INCR_SPECS -->|"1:1:1"| IMPL_PLAN
        DESIGN --> IMPL_PLAN
        IMPL_PLAN -->|"1:1:1"| TASK["backlog/tasks/<br/>(<SPEC-I-ID>.md)"]
        TASK --> IMPL["実装・自動テスト実行"]
        ISSUES["backlog/issues/"]
        TODOS["backlog/todos/"]
    end

    subgraph BacklogViews ["バックログ・進捗ビュー (参照のみ)"]
        SPEC_LOG["backlog/spec.md"]
        USECASE_LOG["docs/backlog/usecase.md"]
        WBS["backlog/wbs.md"]
        PHASE_LOG["docs/backlog/phase.md"]
    end

    IMPL -.->|"フィードバック・仕様更新"| INCR_SPECS
    INCR_SPECS -.->|"マウント・反映"| SPECS
    IMPL -.->|"設計修正"| DESIGN

    SPEC_LOG --> SPECS
    USECASE_LOG --> USECASES
    WBS --> TASK
    WBS --> ISSUES
    WBS --> TODOS
    PHASE_LOG --> WBS
    PHASE_LOG --> SPEC_LOG
    PHASE_LOG --> USECASE_LOG
    PHASE_LOG -->|"フェーズ定義参照"| PLAN_DOC

    linkStyle 0,1,2,3,4,5,6,11,12,14,15,17 stroke:#f97316,stroke-width:2px;
    linkStyle 7,8,9,10 stroke:#f97316,stroke-width:2px,stroke-dasharray:5 5;
    linkStyle 13,16 stroke:#84cc16,stroke-width:2px;
    linkStyle 18,19,20 stroke:#84cc16,stroke-width:2px,stroke-dasharray:5 5;
    linkStyle 21,22,23,24,25,26,27,28,29 stroke:#06b6d4,stroke-width:2px;

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

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

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