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

実例1：共有ボタンを Web Components にした判断

ここからは、このプラグインで実際に書いた記録を読みます。1件目は、共有ボタンをどう作るかの判断です。このプラグインを作る前の共有欄は、各SNSの公式ウィジェットで、中身はiframeでした。iframe の中は別の文書なので、ボタンの見た目をサイトにそろえることも、どのボタンが押されたかを数えることもできません。そこで、作り方を4つの案から選びました。

比べる物差しは、記録の「判断の決め手」に書いた3つです。見た目と計測を自分たちで持てるか。静的なHTMLにも置けるか。設置する側に何も求めないか。公式ウィジェットは、1つ目を満たしません。Reactの部品とPHPで描く案は、2つ目と3つ目を満たしません。3つすべてを満たしたのが、Web Componentsでした。

## 判断の決め手

- 目的: 静的な HTML と WordPress の両方に、同じ部品を置きたい。
- 目的: 見た目とクリックの計測を、自分たちが管理できる範囲に置きたい。
- 制約: 設置する側（ホスト）に、特定のフレームワークや実行環境を要求しない。
- 制約: SNS 側の投稿処理までは作らない。持つのは、共有画面へ渡す入口まで。

4行目の制約にも注目してください。「SNS側の投稿処理までは作らない」。これは、やらないことを先に決めた制約です。やらないことが書いてあると、あとで「ついでに投稿の予約もできたら」という提案が来たとき、それがこの判断の範囲の外だとすぐに分かります。そして結果の欄には、良いことと並べて、悪いことも書きました。共有URLの形式の変更や端末ごとの違い、アクセシビリティを、公式ウィジェットに任せず自分たちで保守する、という負担です。

なお、この1件目は、判断をした当時には書かれていませんでした。更新履歴と、本編の記事をもとに、あとから書き起こしたものです。記録が無かった判断は、書き起こしたと断ったうえで残しています。記録の冒頭の「記録日」の行に、そのことを明記してあります。

実例2：共有先をデータで宣言した判断

2件目は、前回の名札カードの判断です。1ページ目で見た「共有先はPHPのクラスで書く」という、理由の消えた形を直したときの記録です。こちらは判断と同じときに書きました。候補は、PHPのクラスのまま、TypeScriptで宣言する、1つのJSONにまとめる、共有先ごとのTOMLファイルの4つでした。

## 検討した選択肢

1. **PHP のクラスのまま**: 変更は要らない。一方で、実行されないコードの形をしたデータを正規表現で読み続けることになる。→ 捨てた。
2. **TypeScript で宣言する**: 型の検査が効く。一方で、設定を検証する Python の生成器から読みにくく、同じ問題が残る。→ 捨てた。
3. **1つの JSON にまとめる**: 読みやすい形式。一方で、共有先を足すたびに同じファイルを書き換えることになり、1ファイル足すだけの差し込み口がなくなる。→ 捨てた。
4. **共有先ごとの TOML ファイル**: 採用。

読んでほしいのは、捨てた3案のそれぞれに、利点も書いてあることです。PHPのままなら変更は要らない。TypeScriptなら型の検査が効く。JSONなら読みやすい。どれも悪い案ではありませんでした。利点のある案を、どの制約で捨てたのか。ここが書いてあれば、たとえば将来「生成器をTypeScriptで書き直そう」という話が出たとき、2番目の案を捨てた理由が消えたことに、すぐ気づけます。

見直す条件を、先に書いておく

2つの記録には、最後に見直す条件の欄を置いています。ADR-0001 に書いたのは、次の3つです。

## 見直す条件

- 保存先が増えた、または変わった（いいねの保存先など）。
- 対応する端末やブラウザの範囲が変わった。
- 公式ウィジェットに、見た目の調整やクリックの観測に必要な機能が備わった。

見直す条件は、決めたときがいちばん書きやすい欄です。そのときは、どの前提に寄りかかって決めたのかを、自分がいちばんよく知っているからです。半年たつと、その前提は当たり前になって見えなくなります。1ページ目の名残の話は、まさにこれでした。「PHPがURLを組み立てている間は、PHPで書く」と書いてあれば、組み立てを移した日が、見直す日だと分かったはずです。

決定は消さずに、置き換える

判断を覆したとき、古い記録はどうすればよいのでしょうか。消してしまうと、すっきりはします。けれど Nygard は、古い記録を消さずに残すことを勧めています。

ADRの状態は、提案から採用へ進み、覆されたら置き換え済みになります。番号は使い回しません。置き換え済みになった記録には、新しい記録へのリンクを書き足します。かつてそう判断していたことも、大事な事実だからです。ADR-0002 の冒頭には「置き換えたもの：記録の無かった『共有先はPHPのクラスで書く』」と書きました。置き換えられた側には記録がありませんでしたが、置き換えた側が、その存在を書き留めています。