ADR-0140: 既存 ADR への決定の早わかり遡及 — 被参照上位 20 本を優先バックフィルし残りは改訂時に追加する

• Status: Superseded by ADR-0146 (バックフィル+改訂時追加義務を生成ビューへ置換・2026-06-12。元の受理 = PR #1796 merge 2026-06-11・代表取締役判断)
• Mode: Standard
• Kruchten Type: Executive/Property
• Scope: platform
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-11 21:21
• 承認日時 (JST): 2026-06-11 23:17
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

ADR-0138 は「決定の早わかり」を受理後の新規 ADR 全件に必須化したが、既存 ADR は Non-Goals として分離し、「受理後 30 日以内 (期限 2026-07-11) に別 ADR 起案か過去 ADR 更新運用かを判断する」フォローアップ義務を残した。判断が受理後 60 日 (2026-08-10 頃) を過ぎると ADR-0138 撤退条件 #3 が発動し、0138 自体の再評価になる。

なお、ADR-0138 撤退条件 #3 の「義務履行」の解釈 (判断の確定で足りるか、全数整備への定量マイルストーン提示が必要か) について、本決定では「判断の確定 + 上位 20 本バックフィル + touch-time ルール明文化」を以て履行とみなす立場を取る。全数整備マイルストーンは ADR-0138 起案者との解釈確認が未完のため本 ADR では定義せず、承認時 (2026-07-11 までの判断期限内) に確認結果を本 ADR の前提節へ追記する (ADR-0091(a))。本決定の月次 KPI と撤退条件で「上位 20 本到達」「対応付け食い違い 0 件」を担保する。

確認結果の追記 (2026-06-11・承認時): ADR-0138 起案者 (代表取締役) に確認し、上記の立場 — 「判断の確定 + 上位 20 本バックフィル + touch-time ルール明文化」を以て撤退条件 #3 の義務履行とみなす — で確定した。全数整備の定量マイルストーンは定義しない (残りの既存分は touch-time ルールで漸進整備する)。

§1.2 現状 (As-Is)

2026-06-11 実測で既存 ADR 138 本のうち早わかり節を持つのは ADR-0107 の 1 本のみ。docs 全域の被参照 (自 ADR と INDEX を除く延べ参照ファイル数) は合計 2,555 で、上位 20 本が 45% (1,150) を占める。1 位 ADR-0131 / 2 位 ADR-0019 / 3 位 ADR-0049。

§1.3 課題

参照頻度の高い古い ADR ほど早わかりがなく、ADR-0138 §5.2 が指摘した「参照頻度の高い古い ADR ほど読み筋が揃わない」状態が定量的に確認できる。フォローアップ判断を 30 日以内に履行しないと ADR-0138 自体の再評価に連鎖し、新規 ADR 必須化ルール全体が不安定化する。

§1.4 制約・要件

• 受理後 30 日 (2026-07-11) 以内にフォローアップ判断を確定すること
• 過去 ADR の改変原則 (意味不変) と整合させること。早わかりは本文の要約に限定し新規の主張を含めない
• LLM 下書きを用いる場合の捏造を構造的に防止すること (対応付けレビュー)
• adr-lint の既存検査対象は変更しないこと (既存分は ADR-0138 のしきい値番号方式どおり対象外)
• ADR-0130 (索引類の自動生成) との関係を明確化すること (早わかりは本文の一部で機械生成導出物ではない)

§1.5 目標 (To-Be)

全被参照の 45% (上位 20 本) で読み筋が新規 ADR と揃い、残りは touch-time で漸進的にカバーされる状態。Non-Goals: 既存 138 本の全数一括整備、adr-lint への既存分強制、索引側要約列の追加。

決定

被参照上位 20 本へ早わかりを優先バックフィル (LLM 下書き + 対応付けレビュー、1〜1.5 人日) し、残り約 117 本は意味改訂 PR (Amend/Supersede/Corrigendum 等) 発生時に早わかり追加を必須とする touch-time 運用に乗せる。運用ルールは writing-guide と構造正典 §D に明記し、ADR-0139 で温存された TL;DR 4 本 (0105/0106/0108/0114) が対象に入る場合は同一 PR で早わかりへ統合する。

実施要領:

• 対象確定: 着手時に被参照ランキングを再計測して上位 20 本を確定する (本起案の数値は 2026-06-11 時点の参考値)。ADR-0107 は対象外。再計測スクリプトのロジック (自己参照・INDEX 除外条件) と実行タイミング・担当者・出力を実施計画書に明記し、計測結果を着手 PR に添付することをレビュー合格条件とする。バックフィル完了後に上位 20 本の顔ぶれが 3 本以上入れ替わった場合は追加バックフィルを起動する。
• 捏造防止: 早わかりの各箇条 (文脈/問題/問題点と課題/前提/決定/目的/代償) が本文のどの節に根拠を持つかの対応付けをレビュー合格条件とする。さらに operator_guide §4.4 のチェックリストに「各箇条について本文の意図・前提・代償を正確に反映しているかを 1 文で記述する」欄を追加し、存在確認だけでなく意味の正確性確認まで合格条件に含める。
• TL;DR との統合: ADR-0139 温存 4 本が対象に入る場合は同一 PR で統合し読み筋の二重化を作らない。
• 残りの運用 (touch-time): 意味を変える改訂 PR で早わかり追加を必須とする。「意味改訂」と「軽微」の判定は writing-guide に具体例 (例: 前提条件の変更・代替案評価の追加は意味改訂、誤字・リンク修正は軽微) 付きで追記し、PR テンプレートに「このPRは意味改訂か？(Yes/No)」チェックボックスを追加する。
• 進捗監視: 月次集計に加え、バックフィル期間中は週次進捗トラッキングを行い、3 週目時点で 10 本未満の場合に担当者とレビュアーへエスカレートする。
• 次層への波及: 21〜40 位の被参照層は touch-time 発動を待たず、本決定受理後 6 か月以内に追加バックフィルするかを月次集計のレビュー時に判断する (時点で 21〜40 位の保有率が改善していなければ追加起案)。
• lint は変えない: 既存分は adr-lint 対象外のまま。追加された早わかりの品質は新規分と同じ PR レビューチェックリストで確認する。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸 (#usable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

採択案は Must #usable を通過し最高加重和。案 A は Must 満点だが捏造リスク管理を短期集中投下する点で #reliable が低く加重和で劣る。案 B/C は Must K.O. 不通過。

検討した代替案 (Alternatives Considered)

• 案 A: 全数一括バックフィル (ADR-0138 案 D 相当): 137 本 × 20〜40 分で 7〜9 人日 + 捏造リスクの短期集中 — 被参照下位 117 本は全被参照の 55% を分け合い 1 本あたりの読者効果が薄く費用対効果が悪い (§3.2 で #reliable #efficient 低)。不採用。
• 案 B: 過去 ADR 更新運用のみ (touch-time だけ・起案なし): ADR-0138 §5.2 が「起案する」を義務化しており、運用追記だけでは判断義務未履行と解釈されるリスク (撤退条件 #3)。被参照上位の安定 ADR ほど改訂契機がなく永続的に未整備で残る。Must #usable K.O. 不通過で不採用。本決定の「残り」部分として内包する。
• 案 C: 索引側要約列 (ADR-0138 案 C の既存分適用): 本文を直接開く読者 (最多導線) に届かず、要約の正典が本文の外に出て食い違いが構造的に発生。ADR-0138 本体が Must #usable K.O. とした弱点がそのまま残り不採用。

影響 (Consequences)

§5.1 正の影響 (Good)

• 全被参照の 45% (上位 20 本) で読み筋が新規 ADR と揃う
• ADR-0138 のフォローアップ義務を期限 (受理後 30 日) 内に履行し撤退条件 #3 を閉じる
• touch-time 運用で残り 117 本も漸進的にカバー
• ADR-0139 温存 TL;DR 4 本の統合手順が確立

§5.2 負の影響 (Bad)

• 上位 20 本分のレビュー工数 (対応付け確認は機械化できず人手)
• 受理済み本文への追記が入る (意味不変原則との整理は対応付けレビューで担保)
• touch-time 部分の進捗は改訂頻度に依存し、安定 ADR ほど整備が遅れる
• 残り約 117 本に早わかりがない状態が長く続く

§5.3 中立・トレードオフ (Neutral / Trade-offs)

• LLM 下書きの捏造・要旨の誤りリスク → 対応付けレビュー + 意味正確性 1 文記述 + ADR-0138 §5.2 月次集計に相乗り
• 「意味改訂か軽微か」の判定境界 → writing-guide 具体例 + PR テンプレチェックボックスで明文化
• 全数整備マイルストーンは ADR-0138 起案者との解釈確認が未完のため本 ADR では設定せず、21〜40 位の追加バックフィル判断は月次レビュー時に保有率実測値を見て決める (ADR-0091(a))

撤退条件 (Rollback Plan)

• バックフィル 20 本のうち、対応付けレビューで捏造・要旨の誤りが 4 本以上 (20%) 見つかったら、LLM 下書き方式を中止して人手起草へ切り替える
• 受理後 60 日でバックフィル完了が 10 本未満なら計画を再評価する (touch-time のみへ縮退するか再起案)
• 期間中の週次進捗トラッキングで 3 週目時点 10 本未満なら担当者・レビュアーへ早期エスカレーション
• ロールバック手順: 追加した早わかり節は通常 PR で削除可 (本文の他節・lint・パイプラインへの影響なし)

コスト試算

Confirmation

• 検証手段: 早わかり節の保有本数を grep (または adr-index) で集計し、上位 20 本の保有率と全体保有率を確認する。対応付けレビューでの食い違い件数を併記。
• 実行頻度: 月次 (ADR-0138 §5.2 の月次集計に相乗り)。バックフィル期間中のみ週次進捗トラッキングを併走。
• 違反時対応: 撤退条件の閾値評価。KPI = 受理後 2 ヶ月で上位 20 本の保有率 100%、対応付けレビューでの食い違い検出 0 件。閾値超過時は撤退条件に従い LLM 方式中止または計画再評価。

参照 (References)

• 関連 ADR:
  • ADR-0138: 新規 ADR への早わかり必須化 — 補完 (本決定は 0138 が Non-Goals に分離した既存分フォローアップ義務の履行)
  • ADR-0139: 冒頭要約の早わかり一本化 — 補完 (温存 TL;DR 4 本の統合手順を既存分バックフィルへ適用)
  • ADR-0107: 早わかりパイロット — 並立 (既存で唯一の保有 ADR。バックフィル対象外)
  • ADR-0130: 索引類の自動生成 — 並立 (早わかりは本文の一部であり機械生成導出物ではない。手書き禁止対象外であることを本決定で明確化)
• 関連 PR/Issue: -
• 外部資料: Goyal et al. (2022) LLM 要約 faithfulness 評価 / Bacchelli & Bird (2013) コードレビュー密度低下