documentation-criteria

ドキュメント作成基準

このファイルでは、変更に必要なドキュメントとその保管場所を決定します。各ドキュメントに記載する内容は、「保管場所」からリンクされているテンプレートで定義されています。

各ドキュメントが解決すること

各ドキュメントは、リポジトリだけでは判断できない種類の決定を一つずつ解決します。記入されていないセクションは、以下に示す利用者が後で推測することになり、何を前提としたか記録が残りません。

• PRD — ビジネス上の成果と、その後の作業がたどる受け入れ基準を明確にします。AC ID はトレーサビリティのキーであり、Design Doc、UI Spec、テストの選定で再利用されます。これがないと、各利用者が文章から要件を独自に導き直すことになり、テストと、それが保護する価値とのつながりが失われます。実装の詳細は Design Doc、選定理由は ADR、フェーズとタスクの内訳は Work Plan に記載します。

• ADR — 長期にわたって有効な技術的選択と、採用しなかった選択肢を記録し、後続の作業で意図的な決定と偶発的な結果を見分けられるようにします。これがないと、将来の変更時に同じ比較をやり直すか、気付かないまま決定を覆すことになります。Accepted は現在選択されている手段を記録するものであり、それを維持する義務を意味するものではありません。後から得られた根拠により、より小さく十分な選択肢が裏付けられた場合、確認済みの成果、望ましい将来要件、非目標が引き続き妥当である限り、決定を更新または置き換えてください。エンドツーエンドの実装設計は Design Doc、スケジュールとリポジトリのタスクは Work Plan に記載します。

• UI Spec — コンポーネントが存在する前に、画面構成、遷移、コンポーネント／状態の契約、視覚的な受け入れ基準を記録します。これにより、実装中にコンポーネントごとに決めるのではなく、分解の方針を事前に決定できます。これらの決定が未確定の場合は作成してください。承認済みの UI Spec を再利用できる場合、またはリポジトリで裏付けられた明白なパターンによって決定できる場合は、UI Spec を作成せずに Design Doc に進んでください。技術的な実装と API の契約は Design Doc に記載します。

• Design Doc — 確認済みの範囲について、フロー、契約、変更の影響、検証戦略を含む完全な実装設計を記録します。タスクの実行ではこれを主要な技術的基準として扱うため、実装時に不足している方法を黙って作り出すことがありません。リポジトリの根拠によって技術的な実装方法が無効になった場合でも、確認済みの成果、望ましい将来要件、非目標が引き続き妥当であれば、プロダクト要件を再検討せず、担当するワークフローを通じて実装と影響を受ける技術成果物を修正してください。技術選定の理由は ADR、スケジュールと担当割り当ては Work Plan に記載します。

• Work Plan — タスクの順序、依存関係、実行可能な検証、最初の垂直方向の実証ポイントを明確にします。これがないと、タスクの順序は依存関係ではなくファイル構成に従い、統合リスクが作業の最後に持ち越されます。設計の詳細は繰り返し記載せず、Design Doc を参照します。

作成判断マトリクス

構造規模	基本ドキュメント	作成順序
小規模	なし	直接実装
中規模	Design Doc → Work Plan	Design Doc から開始
大規模	PRD → Design Doc → Work Plan	PRD の承認後に続行

次の順序で一つの経路を組み立てます。

1. 構造規模に基づいて基本経路を選択します。
2. 該当する UI Spec がある場合は、Design Doc の直前に挿入します。
3. 該当する ADR の判断点が一つ以上ある場合は、Design Doc の直前に ADR の一式を挿入します。該当する判断点がある場合、規模の下限は中規模になります。

構造的な規模

リポジトリの構成ではなく、意思決定の負担を分類してください。ファイル数は補足的な根拠にすぎません。

規模	構造上の条件
小	一貫した成果を、単一の責任境界内で、リポジトリの根拠に裏付けられた明確な方法で実現でき、未解決の長期的な選択肢がない
中	一貫した成果を実現するために境界をまたいで調整するか、長期的に影響する可能性のある選択肢を調査する必要がある
大	独立して価値のある複数の成果に、それぞれ別個の設計上の意思決定が必要である

該当する ADR の意思決定ポイントがある場合、長期的な意思決定が生じるため、規模は少なくとも「中」になります。一貫した成果が複数のレイヤーをまたぐ場合も「中」です。「大」とするには、独立して価値のある成果と、それぞれ別個の設計上の意思決定が必要です。

ADR の意思決定フィルター

確認済みの実装範囲内にある各技術的トピックに対して、まず選択肢フィルターを適用し、次に永続性フィルターを適用します。構造的な規模とは独立して適用し、先に既存の ADR を確認してください。

1. 選択には判断が必要 — 現在の要件、承認済みの決定、代表的なリポジトリの根拠から、比較検討を必要とする、信頼でき、実質的に異なる選択肢が少なくとも 2 つあると判断できる。
2. 決定は長期にわたって影響する — それらの選択肢から選ぶことで、責任、依存関係の方向、共有契約、永続化、技術依存関係、可逆性、またはライフサイクルコストが実質的に変わり、今後の作業でその決定を維持または理解する必要が生じる。

両方のフィルターを通過したトピックごとに ADR を 1 件作成し、すべての ADR をまとめてレビューしてください。選択や再検討を一緒に行う必要がある選択肢は、1 つの意思決定ポイントとして扱います。独立して再検討できる選択肢は分けてください。

該当する長期的な選択肢には、次のようなものがあります。

• 技術、ライブラリ、プラットフォーム、ストレージモデル、または外部依存関係の導入や置き換え。
• 信頼できる代替案がある場合に、所有権、依存関係の方向、信頼境界、または共有公開契約を変更すること。
• 承認済みのアーキテクチャ上の決定を、両方のフィルターを通過する別の長期的な選択肢に置き換えること。
• 元に戻せない、または元に戻すコストが高いデータ戦略や互換性戦略を選択すること。

承認済みの設計に沿う変更、リポジトリの根拠に裏付けられた明確な実装方法がある変更、または低コストで元に戻せる変更であれば、ローカルな契約、データフロー、状態、コンポーネントの変更は Design Doc に記載してください。ファイル数、利用者数、ネストの深さ、状態数、ステップ数、非同期処理の数は、ADR の基準ではなく補足的な根拠です。ADR を作成するのは、上記の条件を満たす意思決定のみです。一般的な技術上の懸念、運用上の可能性、却下された作業は、その判断を裏付ける材料にしかなりません。

保存場所

ドキュメント	パス	命名規則	テンプレート
PRD	docs/prd/	[feature-name]-prd.md	prd-template.md
ADR	docs/adr/	ADR-[4-digits]-[title].md	adr-template.md
UI Spec	docs/ui-spec/	[feature-name]-ui-spec.md	ui-spec-template.md
UI Spec Assets	docs/ui-spec/assets/{feature-name}/	プロトタイプのコードファイル	-
Design Doc	docs/design/	[feature-name]-design.md	design-template.md
Work Plan	docs/plans/	YYYYMMDD-{type}-{description}.md	plan-template.md
Task File	docs/plans/tasks/	{plan-name}-task-{number}.md	task-template.md

*注：Work Plan は .gitignore によって除外されます。

参考資料

各テンプレートでは、そのドキュメントの内容、構成要素、図の基準を定めています：prd-template.md、adr-template.md、ui-spec-template.md、design-template.md、plan-template.md、task-template.md