majiayu000 ドキュメント作成基準
作成判定マトリクス
| 条件 | 必要ドキュメント | 作成順序 |
|---|---|---|
| 新機能追加 | PRD → [ADR] → Design Doc → 作業計画書 | PRD承認後 |
| 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）
- MVPとFutureフェーズの分離
- ユーザージャーニー図（必須）
- スコープ境界図（必須）
含まないもの:
- 技術実装詳細（→Design Doc）
- 技術選定理由（→ADR）
- 実装フェーズ（→作業計画書）
- タスク分解（→作業計画書）
ADR（Architecture Decision Record）
目的: 技術的決定の理由と背景を記録
含むもの:
- 決定事項（何を選択したか）
- 根拠（なぜその選択をしたか）
- 選択肢の比較（最低3案）とトレードオフ
- アーキテクチャへの影響
- 実装への原則的な指針（例:「依存性注入を使用」）
含まないもの:
- 実装スケジュール、期間（→作業計画書）
- 実装手順の詳細（→Design Doc）
- 具体的なコード例（→Design Doc）
- 担当者の割り当て（→作業計画書）
Design Document
目的: 技術的実装方法を詳細定義
含むもの:
- 既存コードベース分析（必須）
- 実装パスマッピング（既存と新規の両方を記載）
- 統合点の明確化（新規実装でも既存との接続点を記載）
- 技術的実装アプローチ（垂直/水平/ハイブリッド）
- 技術的依存関係と実装制約（実装の必要順序）
- インターフェース定義と型定義
- データフローとコンポーネント設計
- 統合ポイントでのE2E確認手順
- 受入条件（EARS形式: When/While/If-then/無印）
- 変更影響マップ（直接影響/間接影響/波及なしを明記）
- 統合点の完全な列挙
- データ契約の明確化
- 合意事項チェックリスト（関係者との合意内容）
- 前提となるADR（共通ADR含む）
必須構造要素:
変更影響マップ:
変更対象: [コンポーネント/機能]
直接影響: [ファイル/関数]
間接影響: [データ形式/処理時間]
波及なし: [影響を受けない機能]
インターフェース変更マトリクス:
既存: [メソッド名]
新規: [メソッド名]
変換必要性: [あり/なし]
互換性確保: [方法]
含まないもの:
- なぜその技術を選んだか（→ADR参照）
- いつ実装するか、期間（→作業計画書）
- 誰が実装するか（→作業計画書）
作業計画書
目的: 実装タスクの管理と進捗追跡
含むもの:
- フェーズ構成（Design Docの技術的依存関係を基に作成）
- タスク分解と依存関係（最大2階層まで）
- スケジュールと期間見積もり
- Design DocのE2E確認手順を各フェーズに配置
- 最終フェーズに品質保証を含む（必須）
- 進捗記録（チェックボックス形式）
含まないもの:
- 技術的な根拠（→ADR）
- 設計の詳細（→Design Doc）
- 技術的依存関係の決定（→Design Doc）
タスク完了定義の3要素:
- 実装完了: コードが動作する
- 品質完了: テスト・型チェック・リントがパス
- 統合完了: 他コンポーネントとの連携確認
作成プロセス
- 問題分析: 変更規模判定、ADR条件確認
- ADR選択肢検討（ADR時のみ）: 3案以上比較、トレードオフ明記
- 作成: テンプレート使用、測定可能な条件記載
- 承認: レビュー後「Accepted」で実装可
保存場所
| ドキュメント | パス | 命名規則 | テンプレート |
|---|---|---|---|
| PRD | docs/prd/ |
[機能名]-prd.md |
prd-template.md |
| ADR | docs/adr/ |
ADR-[4桁]-[タイトル].md |
adr-template.md |
| 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 | 選択肢比較図（必要時） | トレードオフの視覚化 |
| Design Doc | アーキテクチャ図、データフロー図 | 技術構造の理解 |
| 作業計画書 | フェーズ構成図、タスク依存関係図 | 実装順序の明確化 |
共通ADRとの関係性
- 作成時: 共通技術領域（ログ、エラーハンドリング、非同期処理等）を特定し、既存共通ADRを参照
- 不足時: 必要な共通ADRが存在しない場合は作成を検討
- Design Doc: 「前提となるADR」セクションで共通ADRを明記
- 準拠確認: 設計が共通ADRの決定事項と整合しているかを検証
テンプレート
テンプレートはreferences/ディレクトリにあります：
- Design Documentテンプレート
- PRDテンプレート
- 作業計画書テンプレート
- ADRテンプレート
- タスクファイルテンプレート