| name | adr-design-history |
| description | 設計判断やアーキテクチャ上の判断を ADR として記録するときに使う。判断理由、選択肢、影響を設計判断履歴として残す方針を指示する。 |
ADR 設計判断履歴
目的
重要な設計判断を ADR (Architecture Decision Record) として残し、なぜその判断をしたのかを後から追えるようにする。
ADR を残す判断基準
- 構成、責務分割、依存関係、データの流れ、認証、永続化、運用方法などに影響する判断。
- 複数の妥当な選択肢があり、トレードオフを説明する価値がある判断。
- 将来の実装者が「なぜこの形なのか」を知る必要がありそうな判断。
- 既存の設計判断を置き換える、または前提を変える判断。
小さな命名変更、単純なバグ修正、明らかな実装詳細だけの変更では ADR を作らない。
配置と命名
- ADR は
docs/adr/ 配下に置く。
- ファイル名は
NNNN-short-title.md の形式を推奨する。
- 既存 ADR を変更するよりも、新しい判断で置き換える場合は新しい ADR を追加し、古い ADR から参照できるようにする。
最低限記録する項目
- タイトル
- ステータス: Proposed、Accepted、Superseded など
- 背景と課題
- 決定内容
- 検討した選択肢
- 採用理由
- 影響、制約、リスク
- 関連する issue、PR、ドキュメントがあればその参照
守ること
- ADR は結論だけでなく、判断に至った理由と捨てた選択肢を残す。
- 将来の読み手が現在の前提を理解できる粒度で書く。
- 実装と ADR の内容が矛盾しないように、設計変更時は ADR の追加または更新を検討する。
- 推測や未確認の事実は断定せず、前提や未解決事項として明示する。
