adr-design-history

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 の追加または更新を検討する。
• 推測や未確認の事実は断定せず、前提や未解決事項として明示する。