Documentation Criteria

---
name: documentation-criteria
description: 変更に必要なPRD、ADR、UI Spec、Design Doc、作業計画書と、それぞれの保存先を判定する。ドキュメントの範囲を決める時、または技術ドキュメントを作成・レビューする時に使用。
---

# ドキュメント作成基準

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

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

- **PRD** — 後続作業のトレーサビリティの基点となるビジネス成果、現時点の要件、対象外、受入条件を確定する。AC IDは設計と検証で使う安定したトレーサビリティキーとする。実装設計はDesign Doc、技術的な選択肢の決定はADR、タスクの順序は作業計画書に記載する
- **ADR** — 後続作業に長く影響する技術判断を1つと、それが退けた実質的に異なる選択肢を記録し、後続作業が承認済みの判断と偶発的な実装を区別できるようにする。`Accepted` は現時点で選ばれている手段を記録したものであり、維持する義務ではない。確認済みの成果、将来状態の要件、対象外を維持したまま、より小さく十分な選択を後のエビデンスが支持する場合は、そのADRを更新または置き換える。完全な実装設計は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/` | `[feature-name]-prd.md` | [prd-template.md](references/prd-template.md) |
| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | [adr-template.md](references/adr-template.md) |
| UI Spec | `docs/ui-spec/` | `[feature-name]-ui-spec.md` | [ui-spec-template.md](references/ui-spec-template.md) |
| UI Specアセット | `docs/ui-spec/assets/{feature-name}/` | プロトタイプコードファイル | - |
| Design Doc | `docs/design/` | `[feature-name]-design.md` | [design-template.md](references/design-template.md) |
| 作業計画書 | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | [plan-template.md](references/plan-template.md) |
| タスクファイル | `docs/plans/tasks/` | `{plan-name}-task-{NN}.md`（backendのみの計画）、`{plan-name}-backend-task-{NN}.md`（frontendを含む計画のbackend）、`{plan-name}-frontend-task-{NN}.md`（frontend） | [task-template.md](references/task-template.md) |

生成パスの可変部分は、小文字ASCIIのkebab-case slugとする。非ASCIIの入力はパス作成前にこの形式へ変換する。

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

## 参照資料

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