ADRとは｜設計判断を残す5つの記録ポイント

はじめに

「なぜこの処理を非同期にしたのか」。担当者が変わり、設計書を読んでも理由が分からない。AIにコードを修正させると、見た目の簡潔さを優先して同期処理へ戻してしまう。これは説明用の例だが、実装の形だけ残して判断の前提を残さないと、同じ議論や手戻りが起きやすい。

ADRはArchitecture Decision Recordの略で、重要な設計判断と、その背景・結果を記録する文書だ。構成図が「どう作るか」を示すのに対し、ADRは「なぜその形を選んだか」を残す。

本記事では、背景、選択肢、採用理由、影響、見直し条件の5点を整理する。大きな設計書を増やすことではなく、後から判断をたどれる短い記録を作ることが目的だ。

ADRは議事録や仕様書と何が違うのか

議事録には会議中の発言や検討事項が含まれる。仕様書にはシステムが満たす条件が書かれる。ADRは、その条件の下で選んだ設計と、選ばなかった案、受け入れた制約を記録する。関連する議事録や要件へのリンクを持たせても、それらの全文をコピーする必要はない。

Michael Nygardの「Documenting Architecture Decisions」では、判断ごとに短い記録を作り、タイトル、状態、背景、決定、結果を残す形式が紹介されている。AWS Prescriptive Guidanceも、ADRの作成と採用・更新のプロセスを扱っている。

以下の5点は、この基本形を実務で使うための整理であり、ADRの唯一の標準様式ではない。これにID、日付、状態、判断者、関連要件を添えると管理しやすい。

設計判断を残す5つの記録ポイント

1. 背景を、変えられない条件と分けて書く

「性能が必要」だけでは、後任者は判断を再現できない。どの業務で、何が起きると困るかを書く。外部連携先の停止、利用者の待ち時間、処理量、運用体制など、今回の判断に影響した条件を具体化する。

事実、要件、仮定は区別する。計測済みの処理時間と、将来の負荷の見積もりを同じ確かさで書かない。未確認の前提には、誰がいつ確認するかを付ける。

たとえば「外部サービスが停止しても申請の受け付けは続けたい」は業務上の条件だ。一方、「キューを使う」は候補となる解決策である。先に条件を書くと、手段を変える際にも守るべき要件が分かる。

2. 比較した選択肢と評価軸を書く

採用した案だけを記録すると、他の案をなぜ見送ったかが分からない。同期処理、非同期処理、既存のバッチの利用など、実際に比較した案を残す。検討していない案を、比較済みのように後から書き足さない。

評価軸には、応答時間、障害時の継続性、データの整合性、運用負荷、費用、変更のしやすさなどを使う。今回は何を優先したかも書く。

「非同期の方が拡張性が高い」といった抽象論ではなく、「外部停止時も受け付けを継続できる一方、処理結果の通知と滞留監視が必要になる」と、条件に沿って比較したい。数値の根拠がなければ、性能や費用の優劣を断定しない。

3. 採用理由を、要件と結び付けて書く

決定には、採用する案、適用範囲、今回は扱わない範囲を書く。「非同期にする」だけでなく、どの処理をいつ非同期で実行するのかを明示する。

採用理由は評価軸と対応させる。「外部連携先が停止していても申請を受け付ける要件を優先し、受信後に連携処理を実行する」と書けば、実装レビューで守るべき境界が分かる。

提案中と承認済みも分ける。状態名は組織に合わせてよいが、検討中の案を確定した設計として実装へ渡さない。判断者と採用日を付け、合意の根拠を参照できるようにする。

4. 採用後の影響と引き受ける制約を書く

良い点だけでなく、増える作業と制約を残す。非同期処理を採用するなら、結果の反映まで時間差が出ること、再試行や重複排除、失敗時の復旧、監視が必要になることを検討する。

影響先を、画面、API、データ、権限、運用に分けると確認しやすい。たとえば画面に処理状態を表示する必要があるなら、それを要件・仕様に反映する。ADRに書いたことだけで実装やテストが追加されたとは扱わない。

外部連携の受信側に影響する場合は、Webhookの設計の確認事項も参考になる。判断に伴う制約を別の仕様へ渡し、確認結果まで追うことが大切だ。

5. 見直し条件と、置き換える記録の関係を書く

採用時には妥当だった判断も、条件が変われば見直す必要がある。外部連携先の仕様変更、運用体制の変更、負荷の増加など、再検討するきっかけを残す。

ただし、未来の閾値を根拠なく決めない。計測が必要なら、まず対象と確認頻度を決める。「運用開始後に滞留時間を計測し、業務上の許容時間を超える場合に方式を再検討する」と、次の判断に必要な情報を具体化する。

別の設計へ置き換えるときは、新しいADRを作り、古い記録から参照できるようにする。過去の採用理由を消して最新の内容だけに書き換えると、以前の実装がなぜその形だったか分からなくなる。

短いADRの記入例

次の例は説明用であり、非同期処理を一般に推奨するものではない。

判断の単位は、後から独立して見直せる大きさにする。複数の無関係な決定を一件へ詰め込むと、一部だけを置き換えにくい。一方で、すべての変数名や小さな修正をADRにする必要もない。

AIに渡すときは、状態と適用範囲を確認する

AIに設計やコードの変更を頼む際は、対象に関係する採用済みADRと、その制約を渡す。検討中や置き換え済みの記録を区別せず渡すと、古い判断を再利用してしまう可能性がある。

レビューでは、生成された案が要件を満たすかだけでなく、ADRに残した制約を守るか確認する。既存の決定から外れる提案は、その理由と影響を検討し、必要なら新たな判断として記録する。ADRを渡すだけでAIが正しく実装できると考えず、テストと人による確認を組み合わせたい。

まとめ

ADRで残したいのは、結論だけでなく、その時点の条件と引き受けた制約だ。背景、選択肢、採用理由、影響、見直し条件を短くまとめ、要件・仕様・テストへつなぐ。

Kakusillなどの仕様書づくりの道具を使う場合も、要件と設計判断を同じものとして扱わず、対応を整理しておきたい。担当者や開発手段が変わっても、何を守るための設計なのかを引き継げるようになる。