半年後に「なぜ通知処理をこの方式にしたのですか」と聞かれ、コードだけでは答えられない。担当者が異動すると、当時は合理的だった選択も、単なる奇妙な実装に見えることがあります。
この場面では、結論だけでなく、当時の条件と引き受けた不利益を残すことを優先します。 ADR（Architecture Decision Record）は、その設計判断を後から読み直すための記録です。全てのクラスやメソッドを文書化する必要はなく、後で変更費用が大きくなりそうな判断に使います。
MADRの公式テンプレートには、背景、判断材料、選択肢、決定、結果が含まれます。ここでは新人も読みやすいように項目を絞り、架空の問い合わせ管理アプリで一枚を埋めます。
書く前に、結論を変えうる条件を洗い出す
題材は「問い合わせを登録したら、担当チームへ通知する」機能です。登録自体と通知送信のどちらを優先するかで、設計が変わります。
この例では、通知サービスが一時的に止まっても問い合わせは受け付け、通知は後で再試行したい、という要件にします。通知の遅延は数分まで許容します。これらが未合意なら、先に仕様担当と確認します。ここを曖昧にしたまま「非同期が良さそう」と決めるのは早すぎます。
記入済みADR：問い合わせ受付通知
ADR-007: 受付通知をDBの送信待ち記録から非同期に送る
状態: 採用
決定日: 2026年9月23日（架空）
関連する仕様: 問い合わせ登録は通知先の一時障害でも受け付ける。通知は数分の遅延を許容する。
背景と制約
現在は問い合わせ登録の処理中に外部通知サービスへ同期送信している。通知サービスが遅いと登録画面も待たされ、失敗すると登録の成否を利用者が判断しにくい。登録データはDBへ保存している。今回は通知対象が一種類で、運用チームは送信待ち件数を監視できる。
比較した選択肢
| 案 | よい点 | 引き受ける問題 |
|---|---|---|
| A: 登録処理中に同期送信する | 構成が簡単で、即時の送信結果を返せる | 外部の遅延・障害が登録操作へ伝わる |
| B: DBへ問い合わせと送信待ち記録を同一トランザクションで保存し、別処理で送信する | 登録と送信の成否を分け、後から再試行できる | ワーカー、送信待ち監視、重複送信への備えが必要 |
| C: DB保存後すぐ、通知キューへ直接投げる | 非同期の処理系を利用できる | DB保存とキュー投入の間で失敗すると、登録済みなのに通知がない状態を扱う必要がある |
決定と理由
Bを採用する。 受付を外部通知の状態から切り離し、登録データと送信待ち記録を同一DBトランザクションで残せるからだ。送信側は失敗を再試行し、一定時間を超えた待ちを運用へ知らせる。
受け入れた不利益と確認方法
通知が即時とは限らない。再試行時には二重送信の可能性があるので、送信待ちレコードの状態管理に加え、通知先が対応できるなら一意キーによる重複排除を検討する。送信待ち件数、最古の待ち時間、失敗回数を監視対象へ加える。テストでは、通知サービスが落ちても登録できることと、復帰後に送信されることを確かめる。
見直し条件
通知の即時性が必須になった場合、現在の監視・再試行で遅延を守れない場合、通知件数が運用可能な範囲を超えた場合は再検討する。新しい判断はADRを消して上書きせず、後続のADRから参照する。
比較表の「不利益」を消さない
上の例で一番大事なのは、B案を「非同期だから高品質」と持ち上げていないことです。運用する処理が増え、監視が必要で、重複送信にも備える。その負担を引き受けられない小さな試作なら、同期送信を選ぶ判断もありえます。
ADRには、選ばなかった案の敗因も一行で残します。将来「通知は即時でなければならない」と要件が変わったとき、どの前提が崩れたか分かります。MADRの紹介でも、選択肢の長所・短所を残すことを重視しています。
コピペ用の短いテンプレート
ADR番号・題名:
状態・決定日・判断者:
背景: いま何が困るか。合意済みの要件は何か。
判断材料: 何を優先するか。守るべき制約は何か。
選択肢: 案ごとの利点と不利益。
決定: どれを選び、なぜか。
結果: 新しく発生する作業や運用上の負担。
見直し条件: 何が変われば再度判断するか。
関連資料: 仕様・実装・テスト・後続ADRへのリンク。小さな命名変更にこの票は重すぎます。複数人の仕事や運用方法を左右し、後から「なぜ」と聞かれそうな設計なら、十数行でも残す価値があります。まず直近の設計判断を一つ選び、選んだ案の欠点を隠さず一行で書くことから始めてください。
