documentation-criteria

# ドキュメント作成基準

## 作成判定マトリクス

| 条件 | 必要ドキュメント | 作成順序 |
|-----|--------------|---------|
| 新機能追加（バックエンド） | PRD → [ADR] → Design Doc → 作業計画書 | PRD承認後 |
| 新機能追加（フロントエンド/フルスタック） | PRD → **UI Spec** → [ADR] → Design Doc → 作業計画書 | Design Doc前にUI Spec |
| ADR条件該当（下記参照） | ADR → Design Doc → 作業計画書 | 即座に開始 |
| 6ファイル以上 | ADR → Design Doc → 作業計画書（必須） | 即座に開始 |
| 3-5ファイル | Design Doc → 作業計画書（推奨） | 即座に開始 |
| 1-2ファイル | なし | 作業計画書なしの実装サイクル |

## ADR作成条件（いずれか該当で必須）

### 1. 型システム変更
- **3階層以上のネスト型追加**: `type A = { b: { c: { d: T } } }`
  - 判断理由: 深いネストは複雑性が高く、影響範囲が広い
- **3箇所以上で使用される型の変更・削除**
  - 判断理由: 複数箇所への影響は慎重な判断が必要
- **型の責務変更**（例: DTO→Entity）
  - 判断理由: 概念モデルの変更は設計思想に関わる

### 2. データフロー変更
- **保存場所変更**（DB→ファイル、メモリ→キャッシュ）
- **3ステップ以上の処理順序変更**
  - 例: 「入力→検証→保存」から「入力→保存→非同期検証」
- **データ受け渡し方法変更**（props→Context、直接参照→イベント）

### 3. アーキテクチャ変更
- レイヤー追加・責務変更・コンポーネント再配置

### 4. 外部依存変更
- ライブラリ・フレームワーク・外部API導入・置換

### 5. 複雑な実装ロジック（規模に関わらず）
- 3つ以上の状態を管理
- 5つ以上の非同期処理の連携

## 各ドキュメントの詳細定義

### PRD（Product Requirements Document）

**目的**: ビジネス要件とユーザー価値を定義

**含むもの**:
- ビジネス要件とユーザー価値
- 成功指標とKPI（各指標に数値目標、測定方法、期間を明記）
- ユーザーストーリーとユースケース
- MoSCoW法による優先順位（Must/Should/Could/Won't）
- 受入基準に連番ID（AC-001, AC-002, ...）を付与し、下流でのトレーサビリティを確保
- MVPとFutureフェーズの分離
- ユーザージャーニー図（必須）
- スコープ境界図（必須）

**スコープ**: ビジネス要件、ユーザー価値、成功指標、ユーザーストーリー、優先順位のみ。技術実装詳細はDesign Doc、技術選定理由はADR、フェーズとタスク分解は作業計画書に記載。

### ADR（Architecture Decision Record）

**目的**: 技術的決定の理由と背景を記録

**含むもの**:
- 決定事項（何を選択したか）
- 根拠（なぜその選択をしたか）
- 選択肢の比較（最低3案）とトレードオフ
- アーキテクチャへの影響
- 実装への原則的な指針（例:「依存性注入を使用」）

**スコープ**: 決定事項、根拠、選択肢比較、アーキテクチャへの影響、原則的な指針のみ。実装手順とコード例はDesign Doc、スケジュールと担当割り当ては作業計画書に記載。

### UI Spec

**目的**: フロントエンド機能のUI構造、画面遷移、コンポーネント分解、インタラクション設計を定義

**含むもの**:
- 画面リストと遷移条件
- 状態×表示マトリクスを含むコンポーネント分解（default/loading/empty/error/partial）
- PRD受入条件にリンクしたインタラクション定義（EARS形式）
- プロトタイプ管理（コードベースのプロトタイプは添付扱い、正式な仕様ではない）
- PRDから画面/コンポーネントへのACトレーサビリティ
- 既存コンポーネント再利用マップとデザイントークン
- ビジュアル受入条件(AC)（ゴールデンステート、レイアウト制約）
- アクセシビリティ要件（キーボード、スクリーンリーダー、コントラスト）

**スコープ**: 画面構造、遷移、コンポーネント分解、インタラクション設計、ビジュアル受入条件のみ。技術実装とAPIコントラクトはDesign Doc、テスト実装はテストスケルトン生成出力、スケジュールは作業計画書に記載。

**必須構造要素**:
- 状態×表示マトリクスとインタラクション表を含むコンポーネントが1つ以上
- PRD ACを画面/状態にマッピングするACトレーサビリティ表
- 遷移条件付きの画面リスト
- 既存コンポーネント再利用マップ（再利用/拡張/新規の判定）

**プロトタイプコードの取り扱い**:
- ユーザー提供のプロトタイプコードは`docs/ui-spec/assets/{feature-name}/`に配置
- プロトタイプはUI Specの添付であり、正式な仕様ではない
- UI Spec + Design Docが正式な仕様

### Design Document

**目的**: 技術的実装方法を詳細定義

**含むもの**:
- **既存コードベース分析**（必須）
  - 実装パスマッピング（既存と新規の両方を記載）
  - 統合点の明確化（新規実装でも既存との接続点を記載）
- 技術的実装アプローチ（垂直/水平/ハイブリッド）
- **技術的依存関係と実装制約**（実装の必要順序）
- インターフェース定義と型定義
- データフローとコンポーネント設計
- **受入条件（EARS形式 — design-template.md参照。各条件に検証可能な条件と合否閾値を明記）**
- 変更影響マップ（直接影響/間接影響/波及なしを明記）
- 統合点の完全な列挙
- データ契約の明確化
- **合意事項チェックリスト**（関係者との合意内容）
- **コード調査エビデンス**（調査時に確認したファイル/関数）
- **フィールド伝播マップ**（フィールドがコンポーネント境界を越える場合）
- **データ構造の採用判断**（新規構造導入時）
- **Minimal Surface Alternatives**（永続状態、公開コントラクト要素または境界を越えるフィールド、振る舞いモード/フラグ、再利用可能な抽象/コンポーネント分割を導入する場合 — design-template.md の5ステップ出力フォーマットを参照）
- **適用基準**（explicit/implicit分類）
- **前提となるADR**（共通ADR含む）
- **検証戦略**（必須）
  - 正しさの証明方法（この変更で「正しい」とは何か、どう検証するか、いつ検証するか）
  - 早期検証ポイント（アプローチの妥当性を証明する最初の対象、成功基準、失敗時の対応）

**必須構造要素**:
```yaml
変更影響マップ:
  変更対象: [コンポーネント/機能]
  直接影響: [ファイル/関数]
  間接影響: [データ形式/処理時間]
  波及なし: [影響を受けない機能]

インターフェース変更マトリクス:
  既存: [メソッド名]
  新規: [メソッド名]
  変換必要性: [あり/なし]
  互換性確保: [方法]
```

**スコープ**: 技術実装方法、インターフェース、データフロー、受入条件、検証戦略のみ。技術選定理由はADR、スケジュールと担当は作業計画書に記載。

### 作業計画書

**目的**: 実装タスクの管理と進捗追跡

**含むもの**:
- **フェーズ構成**（Design Docの技術的依存関係を基に作成）
- タスク分解と依存関係（最大2階層まで）
- スケジュールと期間見積もり
- **本作業計画用に生成されたテストスケルトンファイルパスを配置**（統合テスト・E2E）
- **検証戦略の要約**（Design Docから抽出）
- **最終フェーズに品質保証を含む**（必須）
- 進捗記録（チェックボックス形式）

**スコープ**: タスク分解、依存関係、スケジュール、検証戦略の要約、進捗追跡のみ。技術的な根拠はADR、設計詳細はDesign Docに記載。

**フェーズ分割基準**（Design Docの実装アプローチに応じて適用）:

**垂直スライス選択時**:
- 各フェーズ = 1つの価値単位（機能、コンポーネント、移行対象）
- 各フェーズに検証戦略に基づく実装＋検証を含む

**水平スライス選択時**:
1. **Phase 1: 基盤実装** - 型定義、インターフェース、テスト準備
2. **Phase 2: コア機能実装** - ビジネスロジック、ユニットテスト
3. **Phase 3: 統合実装** - 外部接続、プレゼンテーション層

**ハイブリッド選択時**:
- Design Docの実装アプローチに基づき垂直と水平を組み合わせる

**全アプローチ共通**: 最終フェーズは常に品質保証（受入条件達成、全テストパス、品質チェック）。各フェーズの検証手法はDesign Docの検証戦略に従う。

**タスク完了定義の3要素**:
1. **実装完了**: コードが動作する
2. **品質完了**: テスト・型チェック・リントがパス
3. **統合完了**: 他コンポーネントとの連携確認

## 作成プロセス

1. **問題分析**: 変更規模判定、ADR条件確認
   - 調査開始前にプロジェクトのexplicit/implicit基準を特定
2. **ADR選択肢検討**（ADR時のみ）: 3案以上比較、トレードオフ明記
3. **作成**: テンプレート使用、測定可能な条件記載
4. **承認**: レビュー後「Accepted」で実装可

## 保存場所

| ドキュメント | パス | 命名規則 | テンプレート |
|------------|-----|---------|------------|
| PRD | `docs/prd/` | `[機能名]-prd.md` | `prd-template.md` |
| ADR | `docs/adr/` | `ADR-[4桁]-[タイトル].md` | `adr-template.md` |
| UI Spec | `docs/ui-spec/` | `[機能名]-ui-spec.md` | `ui-spec-template.md` |
| UI Specアセット | `docs/ui-spec/assets/{feature-name}/` | プロトタイプコードファイル | - |
| Design Doc | `docs/design/` | `[機能名]-design.md` | `design-template.md` |
| 作業計画書 | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | `plan-template.md` |
| タスクファイル | `docs/plans/tasks/` | `{plan-name}-task-{number}.md` | `task-template.md` |

※作業計画書は`.gitignore`で除外

## ADRステータス
`Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`

## AI自動化ルール
- 5ファイル以上: ADR作成提案
- 型・データフロー変更検出: ADR必須化
- 既存ADR確認してから実装

## 図表作成要件

各ドキュメントで必須の図表（mermaid記法使用）：

| ドキュメント | 必須図表 | 目的 |
|------------|---------|-----|
| PRD | ユーザージャーニー図、スコープ境界図 | ユーザー体験と範囲の明確化 |
| ADR | 選択肢比較図（必要時） | トレードオフの視覚化 |
| UI Spec | 画面遷移図、コンポーネントツリー図 | 画面フローとコンポーネント構造の明確化 |
| Design Doc | アーキテクチャ図、データフロー図 | 技術構造の理解 |
| 作業計画書 | フェーズ構成図、タスク依存関係図 | 実装順序の明確化 |

## 共通ADRとの関係性
1. **作成時**: 共通技術領域（ログ、エラーハンドリング、非同期処理等）を特定し、既存共通ADRを参照
2. **不足時**: 必要な共通ADRが存在しない場合は作成を検討
3. **Design Doc**: 「前提となるADR」セクションで共通ADRを明記
4. **準拠確認**: 設計が共通ADRの決定事項と整合しているかを検証

## テンプレート

テンプレートは`references/`ディレクトリにあります：
- [Design Documentテンプレート](references/design-template.md)
- [PRDテンプレート](references/prd-template.md)
- [作業計画書テンプレート](references/plan-template.md)
- [ADRテンプレート](references/adr-template.md)
- [タスクファイルテンプレート](references/task-template.md)
- [UI Specテンプレート](references/ui-spec-template.md)