ドキュメント作成基準

このスキルはドキュメントの振り分け、すなわち変更に伴って記録すべき持続的な判断と各ドキュメントの保存先を定める。各ドキュメントの内容と構造の要件は、「保存場所」からリンクされた各テンプレートが定める。

各ドキュメントで確定すること

• PRD — 後続作業のトレーサビリティの基点となるビジネス成果、現時点の要件、対象外、受入条件を確定する。AC IDは設計と検証で使う安定したトレーサビリティキーとする。実装設計はDesign Doc、技術的な選択肢の決定はADR、タスクの順序は作業計画書に記載する。
• ADR — 持続的な技術判断を1つと、それが退けた実質的に異なる選択肢を確定し、後続作業が受理済みの判断と偶発的な実装を区別できるようにする。完全な実装設計はDesign Docに記載する。
• UI Spec — 実装前に画面構造、遷移、コンポーネントと状態の契約、インタラクション、ビジュアル受入条件を確定する。これらの判断が未確定の場合に限って作成する。承認済みのUI Specがある場合は再利用し、リポジトリの代表的なエビデンスから判断できる場合はDesign Docへ進む。
• Design Doc — 確認済みスコープに対する完全な実装設計として、責務、フロー、契約、変更影響、検証境界を確定する。実装では、承認済みの設計判断を読み取り専用の根拠として扱う。
• 作業計画書 — 依存順序、タスク境界、実行可能な検証、最初に有用な証明を得る地点を確定する。設計詳細は再掲せず参照する。
• タスクファイル — 作業計画書の実行可能な成果1つについて、根拠となる情報源、調査の開始地点、書き込み責務、観測可能な検証を実装へ引き継ぐ。

作成判定マトリクス

| 構造スケール | 基本ドキュメント | 作成順序 | |-------------|----------------|---------| | 小規模 | なし | 直接実装 | | 中規模 | Design Doc、作業計画書 | Design Doc -> 作業計画書 | | 大規模 | PRD、Design Doc、作業計画書 | PRD -> Design Doc -> 作業計画書 |

フロントエンドまたはフルスタックの作業でUIに関する判断が未確定の場合は、Design Docの前にUI Specを追加する。適格なADRバッチはDesign Docの前に完了させる。適格なADRがある場合、スケールは最低でも中規模とする。

大規模変更のPRD要件は、新規PRDの作成、関連PRDの更新、現行のプロダクト文書がない場合のリバースPRD作成のいずれかで満たす。どのスケールでも、プロダクトスコープが変わる場合は既存PRDを更新する。

構造スケール

分類するのはリポジトリ上のレイアウトではなく判断負荷である。ファイル数は補助的なエビデンスにとどまる。

| スケール | 判断負荷 | |---------|---------| | 小規模 | まとまった成果が1つで、1つの責務境界の中にリポジトリが支持する明白な実装が1つあり、未解決の持続的な選択がない | | 中規模 | まとまった成果が1つで、境界の調整を伴うか、持続的になりうる選択を含む | | 大規模 | 独立して価値を持つ成果が複数あり、それぞれ別個の設計判断を要する |

レイヤーをまたぐ実装であっても、まとまった成果1つに資する場合は中規模のままでよい。

ADR判定フィルタ

確認済みの実装スコープ内にある技術的な論点ごとに、選択（Choice）フィルタ、次いで持続性（Durability）フィルタを適用する。新たな記録を作る前に、受理済みADRを確認する。

1. 選択に判断を要する — 確認済み要件、受理済みの判断、リポジトリの代表的なエビデンスを適用した後も、妥当かつ実質的に異なる選択肢が2つ以上残る。
2. 選択が持続的である — 選択によって、後続作業が維持または理解すべき責務、依存方向、共有契約、永続化、技術、可逆性、ライフサイクルコストのいずれかが実質的に変わる。

両方のフィルタを通過した論点ごとにADRを1つ作成し、バッチ全体をまとめてレビューする。一緒に選択または再検討しなければならない判断はまとめ、独立して再検討できる判断は分ける。ローカルな実装詳細や、安価に元へ戻せるその他の選択はDesign Docに記載する。

保存場所

| ドキュメント | パス | 命名規則 | テンプレート | |------------|-----|---------|------------| | 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/ | task-decomposerのファイル名表を参照 | task-template.md |

作業計画書は.gitignoreで除外される。

参照資料

各テンプレートが、そのドキュメントの内容、ステータス規則、必要なエビデンス、任意の図、完了条件を定める。作成またはレビューするドキュメントのテンプレートだけを読み込む。