ドキュメント作成基準

ドキュメント作成基準

作成判定マトリクス

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要素:

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

作成プロセス

1. 問題分析: 変更規模判定、ADR条件確認
2. ADR選択肢検討（ADR時のみ）: 3案以上比較、トレードオフ明記
3. 作成: テンプレート使用、測定可能な条件記載
4. 承認: レビュー後「Accepted」で実装可

保存場所

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

ADRステータス

Proposed → Accepted → Deprecated/Superseded/Rejected

AI自動化ルール

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

図表作成要件

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

共通ADRとの関係性

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

テンプレート

テンプレートはreferences/ディレクトリにあります：

• Design Documentテンプレート
• PRDテンプレート
• 作業計画書テンプレート
• ADRテンプレート
• タスクファイルテンプレート