ADRに残すのは結論より、捨てた案と制約

ADRは、5つの欄を持つ短い文書

ADRの形を広めたのは、Michael Nygard が2011年に書いた短い記事です。そこでは、1つの判断を5つの欄で書くことを勧めています。ADRという言葉を、このページで改めて押さえておきましょう。

題名は、判断を短い名詞句で書きます。背景には、そのとき働いていた力（要求、制約、事情）を、意見ではなく事実として書きます。決定は「〜にする」という能動の文で言い切ります。状態は、提案・採用・廃止・置き換え済みのどれか。結果には、決めたあとに起きることを書きます。Nygard は、ここに良いことだけでなく悪いことも書くよう念を押しています。

このプラグインでは、この5つの欄に、MADRというひな形の「判断の決め手」と「検討した選択肢」を足し、さらに「見直す条件」の欄を置きました。実際にリポジトリへ置いているひな形はこれです。

# ADR-NNNN: <判断を短い名詞句で>

- 状態: 提案 / 採用 / 廃止 / 置き換え済み（→ ADR-NNNN）
- 記録日: YYYY-MM-DD

## 背景
いま何に困っていて、どんな力（要求・制約・事情）が働いているか。事実だけを書く。

## 判断の決め手
- 目的:
- 制約:

## 検討した選択肢
1. <案>：利点／欠点（捨てた理由）

## 決定
「〜にする」と能動の文で書く。

## 結果
良いことも悪いことも、決定のあとに生じる状況をすべて書く。

## 見直す条件
どの前提が変わったら、この判断を見直すか。

1ファイルに書くのは、1つの重要な判断だけです。いくつもの判断を1つの文書にまとめると、どれか1つを覆したとき、文書全体の扱いに困るからです。短く、1件ずつ。これがADRのいちばん大事な約束です。

結論より、捨てた案と制約を厚く書く

では、この欄のうち、どこに力を入れて書けばよいのでしょうか。1件目の記録（ADR-0001）の欄ごとに、書いた量の目安を横棒で並べてみました。

決定の欄は、たった1〜2行です。共有欄を独自の要素として作る。それだけです。結論は、実はコードを読めば分かります。一方で、何を比べ、何を捨て、どんな制約に縛られていたかは、コードのどこにも残りません。残るのは、選ばれた案だけだからです。結論は1行で足り、厚く書くのは捨てた案と制約です。設計の判断はいつもトレードオフの上にあるので、何を手放したかを書かないと、判断の半分しか残らないことになります。

捨てた案の記録が、同じ議論のやり直しを止める

捨てた案を残すと、どんな場面で役に立つのでしょうか。たとえば、新しく加わった人が「共有ボタンはReactの部品で作り直したほうが書きやすいのでは？」と提案したとします。もっともな提案です。

記録が無ければ、Reactの利点と欠点を、一から話し合うことになります。記録があれば、ADR-0001 の「検討した選択肢」を開くだけで、Reactの部品がすでに比べられ、「設置する側にReactの読み込みを求め、静的なHTMLへそのまま置けない」という理由で捨てられたことが分かります。あとは「その前提は、今も同じか」を確かめるだけです。同じなら、議論はそこで閉じられます。変わっていたら、見直す条件にあたるので、記録を開き直す番です。

ここで大事なのは、記録が提案を門前払いするための道具ではないことです。捨てた理由が残っていれば、議論を「前提は変わったか」から始められる。ゼロからではなく、前回の続きから話せるのです。