なぜこの設計を採用したのか、代替案や選定理由が記載されているか？¶
Type: Structure
Category: 共通
Audience: すべて
背景・概要¶
設計は唯一の正解があるものではなく、複数のアプローチの中から制約に応じて選定されるべきもの
そのため、「なぜこの方式にしたのか」「他の案はなかったのか」といった意思決定の過程を明示的に残すことで、レビュワーは背景を理解しやすくなり、後工程での仕様変更にも対応しやすくなる
例¶
- データ連携方式をポーリングではなくWebhookにした理由を通信頻度と即時性のトレードオフとして記述
- UI設計で一覧表示の仮想スクロールを導入した理由として、パフォーマンス要件や既存UIライブラリの制約を記述
- 検討したDB設計のうち、「テーブルを分ける案」「1テーブルに統合する案」の比較表を記述しておく
よくある失敗例¶
- 「〇〇方式を採用」とだけ書かれており、なぜそうしたのかが不明
- 課題が発生しても元の意図が分からず、再検討が困難
- 「将来的に拡張しやすいから」といった漠然とした理由しか書かれていない
FAQ¶
Q. 検討していない案も書く必要がある？
A. 検討しなかった理由を書かれたい。主要な選定ポイントに関しては、「検討したが採用しなかった案」を1〜2つ簡潔に触れるだけでも十分に価値がある
Q. 明文化すべき選定理由の粒度は？
A. 原則として設計に影響する前提（制約・トレードオフ）が絡む判断は明記するのが望ましい。開発チーム内の共通認識に頼らずドキュメントとして残す前提で記述すべき
関連観点¶
- 全て