第6章ADRの扱い ── 決定を書く
ADRに何を書くか
ADRに必ず残すのは、業務ルールに関してプロジェクトが下した決定です（2章）。
ADRは、次の5つを持つ——何を決めたか／なぜそう決めたか／誰が確定したか／その結果（良い結果とトレードオフ）／この決定から生じる制約。
この5つには、Trusted Spec の定義の章で挙げた3点（何を決めたか／なぜそう決めたか／誰の判断か）が含まれています。
ADRの記述形式の一案として、Nygard形式（ステータス／背景／決定／結果）に「この決定から生じる制約」節を足した形を推奨する。本書の例はこの形で書く。プロジェクトの文書標準に合う記述形式があるなら、上の要素が揃っていればそれでよい。
例をひとつ示します。題材は、最初の章の例1、送料無料の閾値です。この章と次章では、このADRを最後まで使います。
# ADR-0231：送料無料の閾値は、業務部門が自分で切り替える
## ステータス
- 状態：仮決定
- 発生工程：要件定義
- 確定者：発注者側の販売業務責任者
- 発生箇所：販売業務
- 置換：なし
- 前提とする決定：なし
## 背景
閾値の変更は、恒久的な料金改定ではなく、期間を区切ったキャンペーンの
実施手段である。売り方を決めるのは業務部門であり、実施の判断から
反映までの間に開発側の作業が挟まると、打ちたいときに打てない。
履歴を残すのは、過去の受注がどの条件で成立したかを後から説明する
必要があるためである。
## 決定
送料無料の閾値は、業務部門が自分で切り替えられる形で提供する。
開発側のリリースを伴う変更手段は採らない。変更の履歴を残す。
## 結果
### 良い結果
キャンペーンの実施が、開発側の作業計画から切り離される。
### トレードオフ（悪い結果）
変更の手段・権限・履歴の分だけ、作るものが増える。
### この決定から生じる制約（後続成果物が満たすべき状態）
- 販売業務の要求事項：閾値は業務部門が変更し、変更に開発側のリリースを
必要としないことが記述されている。
- 販売業務の要求事項：閾値の変更履歴（変更日時・変更者・変更前後の値）を
保持することが記述されている。
- 販売業務の業務の定義：閾値の変更が、開発側のリリースを伴う作業として
記述されていない。
- 販売業務のユースケース：業務部門の担当者が閾値を変更する手順（システムの
ふるまいを含む）が記述されている。（番号も題材も架空です。ステータス節の項目〈状態・発生工程など〉は、次の章で扱います。）
確定者は、Trusted Spec の定義の章でいう「誰の判断か」にあたります。
本メソッドで大切にしているのは、制約節です。この決定を受けて、後の成果物に何が書かれていればよいかを書く節です。
書く人にとっては、決定を詰める道具になります。どの成果物に何が書かれていればよいかを書こうとすると、決定のあいまいなところが見えてきます。そして後で成果物を書く人は、自分の成果物に当たる制約を読んで、何を書けばよいかを知ります（【たたく】の章で見たとおりです）。
検査にとっては、決定が効く先の目印になります。制約節がないと、この決定がどこに効くのかが推測できず、検査の範囲が広がりすぎてしまいます（10章）。
制約節に何を書くか
制約節は、1行に「影響範囲：満たすべき状態」を1組ずつ書く。
影響範囲をどう書くか
影響範囲は、決定を受け止める成果物（その決定を反映させる要件定義や外部設計の文書）の範囲を、プロジェクトの文書に実在する名前で書く。特定の範囲に絞れないときは「横断」と書き、空欄にしない。
文書を名指しで書けるなら、そのほうが良い書き方です。反映漏れを見つけやすくなるからです。ADR-0231 では、販売業務の要求事項・業務の定義・ユースケースを名指しています。できるだけ名指しを目指しますが、名指しできないときは、業務プロセスやサブシステムのような範囲で書くこともできます。もっと広く、プロジェクト全体に及ぶときは「横断」と書きます。「横断」の表記は、開始時に決めておきます。空欄にしないのは、空欄では、横断と書き忘れの区別がつかないからです。
影響範囲に書けるのは、そのADRを決めた工程の成果物だけである。工程をまたがない。
その工程で決めたことは、その工程の成果物に反映されて、次の工程へ流れます。
満たすべき状態をどう書くか
制約節の各行は、その影響範囲の成果物を人やAIが確かめるときのチェック項目になります。
満たすべき状態は、その影響範囲の成果物を読めば、満たしているかどうかを人もAIも答えられる形で書く。
多くの項目は「〜が記述されているか」になります。何の記述かを具体的に書きます。ADR-0231 のユースケースの行なら、「業務部門の担当者が閾値を変更する手順」です。機能として「できてはいけないこと」も、「〜ができないことが記述されている」と書きます。この形の項目は、どこに書かれているべきかが決まっていないと確かめられないので、影響範囲を「横断」にしません。
ほかにも、たとえば次のような項目が書けます。
- 決定と食い違う記述が残っていないか。決定より前に書かれた文書に効きます。ADR-0231 の業務の定義の行がそれです。名指した文書を1件ずつ読めば答えが出るので、最も判定しやすい項目です。
- 書かれている内容が、決定どおりの条件になっているか。たとえば、閾値を変更できる主体が、包括的な役割名ではなく業務部門の役割として書かれているか、です。
答えが出ない項目は書きません。「配慮されているか」「適切か」は、読む人によって答えが変わります。
検査が崩れる書き方と、直し方
ADR-0231 を書く途中で起こりうる崩れ方を、わざと作った例です。
| 満たしていない例 | 引っかかるところ | 直した形 |
|---|---|---|
| 「業務部門の担当者が閾値を変更する手順が記述されている。」 | 影響範囲がない | 「販売業務のユースケース：業務部門の担当者が閾値を変更する手順が記述されている。」 |
| 「販売業務のユースケース：閾値を変更するユースケースを記述する。」 | 書き手への指示になっている。成果物が満たす状態ではない | 「販売業務のユースケース：業務部門の担当者が閾値を変更する手順が記述されている。」 |
| 「販売業務の業務の定義：閾値の変更のしやすさに配慮する。」 | 判定できない | 「販売業務の業務の定義：閾値の変更が、開発側のリリースを伴う作業として記述されていない。」 |
| 「販売業務の業務の定義：閾値の扱いは現行のままとする。」 | 何を維持するのかが特定されていない。「〜のままとする」は、維持すべき記述を特定しないと判定できず、最も判定しにくい | 維持したい中身を「〜が記述されている」で書く |
| 「販売業務のユースケース：閾値を変更する手順が記述され、変更履歴を保持することも記述されている。」 | 1行に2つの要求 | 2行に分ける（変更履歴は要求事項の行へ） |
| 権限・業務イベント・画面……と、当たりそうな成果物を並べて同じ満たすべき状態を書く | 網羅しようとしている | 受け止める成果物（要求事項）に着地させる。その先は辿りに任せる |
| 「販売業務の要求事項」と名指しできるのに、影響範囲を「横断」と書く | 全員に届き、読む量が膨らむ | 受け止める文書を名指す |
| 要件定義のADRで「受注登録画面：…」と書く | 決めた工程の外の成果物を名指している | 要件定義の成果物（要求事項・ユースケースなど）で書き直す。画面は、外部設計がその成果物から書く |
| 制約節が空 | 記録には残るが、検算に使えない | 業務ルールに関する決定で書けないなら、決まり切っていない疑いがある。未決型ISSUEにするかを人が判断する（次の小節） |
制約が書けないとき
業務ルールに関する決定なのに、制約が1つも書けないことがあります。どの成果物に何が書かれていればよいのかが言えない、ということです。それは、決まり切っていない疑いの合図です。ADRにするか、未決型ISSUEにするかは、人が判断します。どちらに残しても、漏らしてはいません。
制約はまだ書けないが、理由だけは残しておきたい決定もあります。そういうときは、成果物の本文に理由を書き添えて残して構いません。ただし書き添えは索引に載らず、検査にも掛かりません。増えれば、後で「これは決定だったのか」を人が読み返して拾い直すことになるので、迷うなら、制約の形に書けないかを先に試してください。
業務ルールのほかにも、残したい決定があるとき
決定の中には、業務ルールではないけれど、後で「なぜこうなっているのか」と聞かれそうなものもあります。どこまでADRにするかは、開始時に線を決めておきます。
業務ルールに関する決定のほかにADRを残すときは、「制約節テスト」で選ぶ——この決定から生じる制約を1つでも書けるなら、ADRにする。書けないなら、しない。
この目安で書いたADRは、書いた瞬間から【確かめる】に使えます。目安なので、境界の事例は残ります。迷ったら人が判断します。
| 決定の例 | どうするか |
|---|---|
| 受注番号を、何桁で、どう採番するか | 「販売業務の情報の一覧：受注番号が、年度と連番からなる10桁として定義されている」と制約が書けるので、ADRにする |
| 一覧画面を、1ページに何件ずつ表示するか | 画面の設計標準に決まりがあるなら、ADRにしない（次の1つ目の規範） |
| 設計書のレビューを、誰と誰で行うか | プロジェクト運営の決定なので、ADRに混ぜない（次の2つ目の規範） |
どの線を使っても、ADRに書かないものが2つあります。
標準・ルールで既にカバーされている決定は、ADRに書かない。
プロジェクト運営の決定（体制・スケジュール・会議体）を、ADRに混ぜない。次元が別であり、記録するとしても別台帳にする。
なぜ業務ルールで線を引くのか（読み飛ばしてよい）
主流のADRは、アーキテクチャ上重要な決定に絞ります。代表的な様式は一度 "Any Decision Record" を名乗りましたが、2024年の改訂で "Architectural" に戻りました。絞る理由は、陳腐化と維持コストです（付録_出典）。
本書がそれに従わないのは、SIでAIが埋めてしまう空白が、アーキテクチャの外にあるからです。最初の章の失敗例——閾値を誰が変えるのか、画面が業務判断をしてよいのか——は、どちらも業務ルールの決定です。アーキテクチャで絞れば、拾うべき決定が対象から外れます。
ただし、本書は実のところ、完全な "Any" ではありません。業務ルールに関する決定は必ず残します。それ以外の決定は、制約が書けるかで絞ることを勧めます（前の節）。主流が「重要か」で残すものを絞るのに対し、本書は「業務ルールに関する決定か」で必ず残すものを決めます。維持コストのほうは本書も引き受けており、その勘定は15章にあります。