/da-adr-figure — ADR の判断を、ひと目で掴める 1 枚にする

図解 1 枚につき定義 1 ファイル（figure.json）を書き、${CLAUDE_SKILL_DIR}/scripts/figure.mjs で PNG にする。 図は ADR の要約ではなく、入口である。図を見た人が、判断ごとに「何を選び、一番強い理由は何で、一番強い対抗案だと何が起きるか」を掴めることを目指す。 細部と残りの反論への答えは ADR に任せる。反論をすべて図で潰そうとすると文字が増え、肝心の判断が埋もれる。

触ってよいもの: 作業ディレクトリ（scratchpad を推奨）に置く定義・HTML・PNG だけ。ADR は書き換えない。 図に書きたい理由が ADR に無ければ、止まって報告する（Step 2）。

実行条件

1 行でも満たさなければ即座に止まり、どの条件かを報告する。続けない。

ワークフロー上の位置

読むファイル

常に読む

条件つきで読む

「念のため」全部を読むことは禁止。

手順

Step 1. ADR の判断を数える

ADR の判断の節（## 1. 〜 ## N.）を 1 つずつ、カード 1 枚にする。カードの数と順は ADR の節と同じにする。 全体像（overview）には、データや処理の流れを 2〜4 段で描く。段の中の箱の名前は、ADR と同じ名前にする。 全体像とカードで同じ内容を描かない。全体像に一覧を描いたら、カードではその一覧を繰り返さず、全体像に無いこと（理由、境目の例）だけを書く。

Step 2. カードの中身を書く

figure-format.md の「カードの書き方」に従う。要点:

• 決定: 何をするかを、具体例で書く
• なぜ: 仕組みまで書く。「〜が違うため」で止めず、何をして、どこで失敗し、それが何を意味するから、こうする、まで
• ボツ案: 案ごとに「その案だと何が起きるか」。比べる観点が 2 つ以上なら表にする
• ボツ案が無い判断には「見直す条件」か「限界」を置く
• 量の上限：決定は 90 字、なぜは 2 項目（各 70 字）、ボツ案は 2 件、表は 1 つで 4 行まで。lead は 1 行。題は ADR の題をそのまま使う（上限なし）。上限は check が検査する。超えたら削る。残すのは一番強い理由と一番強い対抗案で、残りは ADR に任せる

ADR より強い理由を図に書かない。 書きたい理由が ADR に無い、または ADR の理由が弱くて図だけを読んだ人が反論できる時は、図を作る前に止まり、ADR のどこに何が足りないかを報告する。図と ADR の理由がずれると、読み手は弱い方の文書を信じる。

Step 3. 定義を書いて検査する

node ${CLAUDE_SKILL_DIR}/scripts/figure.mjs check figure.json

決定 と なぜ の無いカード、result の無いボツ案、列の数が合わない表、量の上限を超えた文は、書き出す前にここで落ちる。上限は scripts/figure.mjs の LIMIT にある。上限を上げて通さない。

Step 4. 書き出して、目で確かめる

node ${CLAUDE_SKILL_DIR}/scripts/figure.mjs build figure.json figure.png

文字が枠からあふれると、確認用の PNG を書いたうえで失敗し、あふれた箇所を挙げる。文言を詰めて書き出し直す。枠を小さくしたり、あふれを隠したりして通さない。 通ったら PNG を開き、カードごとに「最初の 10 秒で、何を選んだかと一番強い理由が目に入るか」を確かめる。入らなければ Step 2 に戻って削る。

根拠の扱い

• カードの理由・数値・識別子は、ADR か、ADR が引くコード・実測にあるものだけを書く。
• 場所を示すときは path/to/file.ts:L42 の形で示す。
• 確かめられなかった数値は図に載せず、「確認できなかった」と報告する。
• 事実と推論を分ける。図に推論を書くなら、ADR に同じ推論があることを確かめる。

出力

作業ディレクトリに figure.json・figure.html・figure.png の 3 つ。報告には PNG のパスと、ADR に足りなかったもの（Step 2 で止まった時）を書く。

完了条件

• カードが ADR の判断の節と 1 対 1 で、同じ順に並んでいる
• すべてのカードに「決定」と「なぜ」があり、なぜが仕組みまで書かれている
• ボツ案には「何が起きるか」があり、ボツ案の無い判断には「見直す条件」か「限界」がある
• 図の理由・数値・名前が ADR と一致し、ADR より強い理由を図だけに書いていない
• check が量の上限込みで通り、全体像とカードで同じ内容を描いていない
• build があふれなしで通り、PNG を目で確かめた

次に

図で ADR の弱い所が見えたら /da-adr で ADR を直し、図を書き出し直す。