Documentation Criteria Agent Skill

ドキュメント作成基準

作成判定マトリクス

確定した規模に対応する行を評価し、同じ行に記載された条件付きドキュメントを追加する。

| 確定規模 | 必要ドキュメント | 条件付き追加 | 作成順序 |

|---------|----------------|-------------|---------|

| 大規模（6ファイル以上、またはリスク軸が大規模） | PRD、Design Doc、作業計画書 | フロントエンド/フルスタックではUI Spec、ADR条件該当時はADR | PRD → UI Spec（該当時）→ ADR（該当時）→ Design Doc → 作業計画書 |

| 中規模（3〜5ファイル、またはリスク軸が中規模） | Design Doc、作業計画書 | フロントエンド/フルスタックではUI Spec、ADR条件該当時はADR、機能スコープ変更時は既存PRDを更新 | PRD更新（該当時）→ UI Spec（該当時）→ ADR（該当時）→ Design Doc → 作業計画書 |

| 小規模（1〜2ファイルで、より高いリスク軸なし） | task-template形式のタスクファイル1つ | 機能スコープ変更時は既存PRDを更新 | PRD更新（該当時）→ タスクファイル |

大規模変更のPRD要件は、新規PRDの作成、関連PRDの更新、現行の製品文書がない場合のリバースPRD作成のいずれかで満たす。

構造的エスカレーション

ファイル数は規模を測るが構造的な影響は測らないため、2ファイルの変更でも契約やデータフローを作り替えることがある。

下記のADR作成条件のいずれかが該当する場合、確定規模はファイル数に関わらず最低でも中規模（Design Docと作業計画書が必須）とする。エスカレーションは規模を引き上げるだけで、ファイル数がすでに中規模・大規模に達している場合はそのまま据え置く。引き上げの根拠となった条件を、規模を決めた軸として記録する。

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（各指標に数値目標、測定方法、期間を明記）
• ユーザーストーリーとユースケース
• 受入条件（AC）に連番ID（AC-001, AC-002, ...）を付与し、下流でのトレーサビリティを確保
• MVPへの収束 — 価値を届ける最小のまとまった振る舞い・ジャーニーと、除外した機能をFutureまたはOut of Scopeへ理由付きで配置し、ユーザーが除外を決めたのか要件分析が判断したのかを示すoriginを併記
• ユーザージャーニー図（必須）
• スコープ境界図（必須）

スコープ: ビジネス要件、ユーザー価値、成功指標、ユーザーストーリー、優先順位のみ。技術実装詳細は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参照。各条件に検証可能な条件と合否閾値を明記）
• 変更影響マップ（直接影響、間接影響、検証済みの波及なしを明記）
• 統合点の完全な列挙
• データ契約の明確化
• 合意事項チェックリスト（関係者との合意内容）
• コード調査エビデンス（調査時に確認したファイル/関数）
• フィールド伝播マップ（フィールドがコンポーネント境界を越える場合）
• Requirement Convergence（必須） — 成果、ユーザーが除外した非ゴールと投機的要件、ユーザーが未解決のまま残したフィールド。PRDがこれらを保持する場合、前半3項目はPRDのパスを添えてN/Aとする（design-template.md 参照）
• Design Convergence（必須） — Direct MVP、Failed Items、Adopted Additions、Rejected Additions（design-template.md 参照）
• データ構造の採用判断（収束後の設計が構造を導入・変更する場合）
• 適用基準（explicit/implicit分類）
• 前提となるADR（共通ADR含む）
• 検証戦略（必須）
• 正しさの証明方法（この変更で「正しい」とは何か、どう検証するか、いつ検証するか）
• 早期検証ポイント（アプローチの妥当性を証明する最初の対象、成功基準、失敗時の対応）

必須構造要素:

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

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

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

作業計画書

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

含むもの:

• フェーズ構成（Design Docの技術的依存関係を基に作成）
• 実装成果ごとに1つのタスクエントリ。各エントリは安定IDのPhase X タスクY、Target Files、ロールバック境界、Executor lane を持つ（plan-template.md 参照）
• それら安定IDで宣言するタスク依存関係（最大2階層まで）
• スケジュールと期間見積もり
• 本作業計画用に生成されたテストスケルトンファイルパスを配置（統合テスト・E2E）
• 検証戦略の要約（Design Docから抽出）
• 最終フェーズに品質保証を含む（必須）
• 進捗記録（チェックボックス形式）

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

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

垂直スライス選択時:

• 各フェーズ = 1つの価値単位（機能、コンポーネント、移行対象）
• 各フェーズに検証戦略に基づく実装＋検証を含む

水平スライス選択時:

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

ハイブリッド選択時:

• Design Docの実装アプローチに基づき垂直と水平を組み合わせる

全アプローチ共通: 最終フェーズは品質保証とし、受入条件、設定済みのテスト、適用対象の品質チェックを検証する。各フェーズの検証手法はDesign Docの検証戦略に従う。

タスク完了定義の3要素:

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

作成プロセス

• 問題分析: 変更規模判定、ADR条件確認
• 調査開始前にプロジェクトのexplicit/implicit基準を特定
• 出力証跡: 規模を決めた軸を含む確定規模、必要ドキュメント一覧、既存ドキュメントごとの情報源
• 移行条件: 各ドキュメントをcreate、update、not requiredのいずれかに分類し、ルールに基づく理由を示したら次へ進む
• ADR選択肢検討（ADR時のみ）: 3案以上比較、トレードオフ明記
• 出力証跡: 採用案、不採用案、既知の不明点、撤回基準を含む選択肢比較
• 移行条件: 判断をレビューでき、作業を妨げる不明点が明記されたら次へ進む
• 作成: テンプレート使用、測定可能な条件記載
• 出力証跡: 必須の保存先に置かれ、全必須セクションが記入済み、または理由付きでN/Aとされたドキュメント
• 移行条件: テンプレートとトレーサビリティのチェックが成功したら次へ進む
• 承認: レビュー後「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自動化ルール

• すべての規模でADR作成条件を評価し、いずれかに該当する場合はADRを作成または更新
• 型またはデータフローの変更が、上記の該当セクションにある条件を満たす場合はADRが必須
• 既存ADR確認してから実装

図表作成要件

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

| ドキュメント | 必須図表 | 目的 |

|------------|---------|-----|

| PRD | ユーザージャーニー図、スコープ境界図 | ユーザー体験と範囲の明確化 |

| ADR | 重要な選択肢が2つ以上あり、その関係やトレードオフを図の方が比較しやすい場合は選択肢比較図 | トレードオフの視覚化 |

| UI Spec | 画面遷移図、コンポーネントツリー図 | 画面フローとコンポーネント構造の明確化 |

| Design Doc | アーキテクチャ図、データフロー図 | 技術構造の理解 |

| 作業計画書 | フェーズ構成図、タスク依存関係図 | 実装順序の明確化 |

共通ADRとの関係性

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

テンプレート

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

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