boykush/adr/write-adr

決定を書く

決定は、問いと比べた選択肢と、選んだ理由を残す。読まれるのはルールの理由を知りたいときなので、それに要ることだけを、選び直すまで変わらない形で書く。

選んでもらう

選ぶのはユーザー。drivers と選択肢の候補を調べて挙げ、エージェントの質問の機能（Claude Code の AskUserQuestion、Codex の request_user_input）で選んでもらう。会話で既に決まっているものは訊き直さない。

• 決定に載せる drivers と選択肢は、複数選択で選んでもらう。複数選択ができなければ、候補ごとに載せるかを訊く
• 選ぶ選択肢は、載せた選択肢から1つを選んでもらう
• 書くのは選ばれたとおり。訊いていない drivers や選択肢を足さない。選ばれた drivers では選ばれた選択肢が勝たないなら、理由を曲げずに、書く前にそう伝える

書くことと書かないこと

決定の粒度は、選択肢が決める。1文ごとに「これが変わったら、選び直すか」を問い、選び直さないなら決定には書かない。それは選んだ選択肢の中の How で、書けば How が変わるたびに決定を直すことになる。

• 各リポジトリが満たす形（パス、ファイル名、設定のキー、使う action）は、ルールが持つ（skill write-ade-rule）
• 実装の手順と設定（権限の細部、鍵の入れ方、リポジトリの足し方）は、実装するリポジトリが持つ。ここは決定の適用を持たない（README の「対象」）
• 選択肢を比べるのに効かないこと（時点の一覧や件数、経緯の逸話）は、どこにも書かない

具体的かどうかでは分けない。選択肢の勝ち負けを分けた点なら、ある action の挙動のような細部も決定に書く。

節

次の節だけを書く。1つのことは1箇所に書き、別の決定が持つことは言い直さずに、その決定へのリンクで指す。

• Context and Problem Statement: 問いを立てるのに要る事実と、問い。選択肢の評価は Decision Outcome に回す
• Decision Drivers: 選択肢を比べる軸
• Considered Options: 実際に比べた選択肢を、同じ粒度で
• Decision Outcome: 選んだ選択肢と、drivers に照らした理由。落とした選択肢ごとに、負けた点を
• Consequences: 選んだ結果として得るものと受け入れるもの。理由で述べたことは繰り返さない
• More Information: 他の決定や、決定を支える外部の資料へのリンク。1つの主張を支える出典は、その主張のそばに置いてもよい

置く

• decisions/NNNN-title-with-dashes.md。番号は次の空き。タイトル・ファイル名・本文の書き方は既存の決定に揃える
• frontmatter は status と date。date は status を変えた日。tags は README の「タグ」に従う
• 各リポジトリが満たす形があれば、隣にルールを書く（skill write-ade-rule）。外した How のうち、ルールにできず別のリポジトリが持つべきものは、そこへの変更が要るとユーザーに伝える

直す

accepted の決定の中身——問い、比べた選択肢、選んだ選択肢、その理由と帰結——は変えない。中身が変わるなら新しい決定で置き換え、古い決定は、当時なぜそう選んだかの記録として残す。merge 前の草稿と proposed の決定は、まだ決まっていないので自由に直してよい。

その場で直してよいのは、直した後に読んでも同じ選択肢を同じ理由で選ぶものだけ。status も date も変えない。

• 決定と選択肢に関わらない記述と How を消す。How は、消す前に持ち主——ルールか、実装するリポジトリ——が持っていることを確かめ、持っていなければ先に持ち主へ足す
• 言い直しを1箇所にまとめる。どこに残すかは「節」に従う。別の決定の言い直しは、その決定へのリンクに替える
• 他の決定との関係を今に合わせる。別に決めるとした問いは、決めた決定で指す
• 誤字、壊れたリンク、改名された物の名前を直す。主張を支える出典を足す

次のものでは、決定を書き換えない。

• How が変わった: 直すのはルールか実装するリポジトリ。決定に How が書かれていたなら、書き換えずに上のとおり消す
• 中身が変わった: 問いの範囲、選んだ選択肢、理由や帰結を支える事実のどれかが変わった。How の変更がきっかけでも同じ。選び直して置き換えるか、元のまま残すかを、ユーザーに選んでもらう

どちらに当たるか迷ったら、直さずにユーザーに訊く。

置き換える・退役させる

• 置き換える: 新しい決定を書き、Context に古い決定へのリンクと、何が変わって選び直すかを書く。古い決定を読まなくても分かるように書き、問いが同じならタイトルも同じでよい。古い決定は status を superseded by ADR-NNNN に、date をその日にし、本文は変えない。新しい決定を accepted にするのと同じ変更で行い、どちらのルールも効かない間を作らない
• 退役させる: 問いそのものが無くなったとき。status を deprecated に、date をその日にし、More Information に理由を1行足す
• どちらでも、古い決定の .rule は消す。配られるのは accepted の決定のルールだけなので、残しても効かない。まだ要るルールは、新しい決定の隣に書き直す