← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0139type: adrstatus: accepted
pagemode: Standardkruchten: Executivescope: platformimplementation_status: Done (amends 辺 = PRproposed_at: 2026-06-11 19:50approved_at: 2026-06-11 20:12deciders: [email protected] (単独)business: meta
型付き辺: 出 2 / 入 1
部分修正する: ADR-0105 関連: ADR-0140 部分修正された: ADR-0146全体は INDEX →

ADR-0139: ADR 冒頭要約を「決定の早わかり」へ一本化する (ADR-0105 TL;DR 箇条の Amend)

  • Status: Accepted (PR #1786 merge = 受理の規約により 2026-06-11 受理・代表取締役判断)
  • Mode: Standard
  • Kruchten Type: Executive
  • Scope: platform
  • Implementation Status: Done (amends 辺 = PR #1786 / テンプレート TL;DR 枠削除 + 残存参照精査 + 申し送り確定 = 本 flip PR に同梱)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-06-11 19:50
  • 承認日時 (JST): 2026-06-11 20:12
  • Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

ADR-0138 (2026-06-11 受理) で新規 ADR に冒頭サマリー「決定の早わかり」が全 Mode 必須化され、H1 後の最初の H2・構造化 7 箇条・adr-lint 機械強制と自動生成の実装が申し送られた。これにより ADR-0105 の決定の 1 箇条「冒頭 TL;DR」(Standard/Critical 必須・Status ブロック直後に専門語ゼロの要旨を 1 段落) と冒頭要約の規約が 2 系統並立する状態になった。

§1.2 現状 (As-Is)

テンプレート (docs/adr/templates/template.md) の冒頭に 2 つの要約枠が並んでいる。TL;DR を実装済みの ADR は 137 本中 4 本 (2.9%・ADR-0105/0106/0108/0114 = 0105 受理直後期のみ)。adr-lint に TL;DR の検査はなく (grep 0 件)、Decision Pipeline の body_generation プロンプトにも生成指示がない (grep 0 件)。

§1.3 課題

「Standard/Critical 必須」の規約にもかかわらず、受理後の新規 ADR 約 30 本への TL;DR の自然普及は 0 本で、規約と実態が乖離している。読者は同じ情報を 2 度読み、書き手と生成プロンプトは 2 つの要約を同期する負担を負う。これは ADR-0138 が根拠とした「機械強制のない冒頭要約規約は普及しない」と同じ現象である。

§1.4 制約・要件

  • ADR-0138 の main 分実装 (body_generation プロンプト改修) が申し送り済みで、着手前に冒頭要約を 1 本化するか決めないと「TL;DR も生成に含めるか」が宙に浮き、実装の手戻りが生じる。
  • ADR-0105 の用語 Tier・原語温存という主題 (Tier 0/1/2・初出グロス・glossary 連携) には一切触れない (TL;DR 箇条のみ廃止)。
  • 受理済み本文の遡及変更はしない (既存 4 本の TL;DR は温存する)。
  • amends 辺と逆辺 (amended_by) を同一 PR で宣言する (ADR-0131 規約)。

§1.5 目標 (To-Be)

冒頭要約を「決定の早わかり」1 つに統合し、規約と実態の乖離を解消する。Non-Goals: ADR-0105 の用語 Tier 規約本体の変更、既存 ADR 本文の遡及修正、早わかり自体の構造変更。

決定

ADR-0105 の決定から「冒頭 TL;DR」箇条のみを廃止する Amend を行う。TL;DR が担っていた「専門外読者の入口」機能は早わかりが引き継ぎ、早わかりの文章は文の軸 (公用文 2022 ベースの日本語わかりやすさ要件・専門語の初出定義) と ADR-0105 の Tier 規約 (原語温存 + 初出グロス) に従って書くため、専門外読者が読める平易さは規約として担保される。実装は (1) テンプレートから TL;DR 説明 blockquote と記入枠の計 2 ブロック削除、(2) 本 ADR から ADR-0105 への amends 辺と逆辺 (amended_by) を同一 PR で宣言、(3) ADR-0138 の body_generation 申し送りに「TL;DR 生成指示を入れない」ことを確定、の 3 点に閉じる (約 0.1 人日)。

判断基準 (Decision Drivers)

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#usableMust (×2.0)冒頭の読み筋が 1 つで、専門外読者の入口 (平易な要約) が失われない
2#maintainableHigh (×1.0)規約と実態が一致し、2 つの要約を同期する負担が発生しない
3#efficientMedium (×0.5)ADR-0138 main 分実装が単純化し、生成トークンの追加増がない

K.O. criterion: 専門外読者の入口が規約上失われる案は不採用 (Must 軸 score < 3 で不採用)。

3.2 評価軸 × 案スコア表

軸係数採択案 (一本化)案 B (併存正式化)案 C (現状維持)案 D (早わかりに吸収)
#usable2.04323
#maintainable1.05213
#efficient0.55234
加重和 (正規化)0.8710.4860.3430.629
K.O. 通過 (Must ≥3)✓✓❌✓

検討した代替案 (Alternatives Considered)

  • 案 B (併存を正式化する): TL;DR と早わかりの両方を生成・両方を lint 対象にする。役割分担 (専門語ゼロ 1 段落 / 構造化 7 箇条) は明確になるが、冒頭に要約が 2 つ並び読者は同じ決定の要旨を 2 度読む。生成トークンも 2 枠分増え、書き直し時は 2 つの同期が要る。認知負荷の最小化という導入目的と逆行 (§3.2 で #maintainable=2)。
  • 案 C (現状維持): TL;DR 規約 (Standard/Critical 必須) と実態 (生成されない・検査されない・4/137 本) の乖離が残り続ける。ADR-0138 main 分実装で「TL;DR を生成に含めるか」の判断が宙に浮き、手戻りの火種になる (K.O. 通過 ❌)。
  • 案 D (TL;DR を早わかりの先頭箇条として吸収): 8 箇条目「ひとことで」を追加。冒頭要約は 1 つになるが、型の正典 (§D の 7 箇条) を変更することになり、ADR-0107/0138 で確立した読み筋 (文脈から入る) と「結論先行の 1 文」が競合して構造が複雑化する。早わかり自体が平易化規約に従う以上、専用箇条の追加は冗長。

影響 (Consequences)

§5.1 正の影響 (Good)

  • 冒頭要約が 1 本化され、読者・書き手・生成プロンプトの負担が減る。
  • ADR-0105 の規約と実態の乖離 (137 本中 4 本) が解消する。
  • ADR-0138 main 分実装 (body_generation プロンプト改修) が単純化する。生成トークンに TL;DR 分が上乗せされない。

§5.2 負の影響 (Bad)

  • 「専門語ゼロ」を明示的に求める専用枠がなくなる。早わかりは Tier 規約に従いグロス付きの原語を許すため、TL;DR より専門語の密度が上がりうる。
  • 「専門語ゼロ」の明文規約が消えるため、ADR を社外監査・コンプライアンス審査に提出する運用 (現時点で要件存在の確認情報なし。本 ADR では当該要件は未確認のまま進める。要件判明時に ADR-0138 側で平易さ担保の明文化先を追補する) で不備指摘を受けるリスクがゼロではない。

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

  • 早わかり平易さの lint 検査未実装リスク (high): adr-lint が検査するのは早わかりの「構造化 7 箇条の存在」のみで、各箇条の語彙難易度や Tier 規約の遵守を機械検査する実装は ADR-0138 申し送りに含まれていない。早わかりの平易さは現時点で人間レビュー (operator_guide §4.4) のみで担保され、TL;DR が辿った「規約はあるが検査されないので形骸化」と同じ構造に陥る可能性がある。ADR-0138 main 分実装の申し送りに「早わかりブロック内の Tier 2 語彙出現密度の警告ルール追加」を将来課題として記録する。
  • ADR-0138 実装遅延時の空洞化リスク (medium): ADR-0138 の lint・自動生成実装が遅延または縮小された場合、冒頭要約規約が TL;DR 廃止後に完全に空洞化する可能性がある。本 ADR の Accepted 遷移は ADR-0138 実装完了を待たない (申し送りの単純化が目的のため) が、ADR-0138 撤退条件発動時は本 ADR の撤退条件 #2 で連動対応する。
  • ADR-0105 残存参照の精査負担: ADR-0105 本文の他箇条が TL;DR を前提とした記述を含まないかの精査を実装手順に追加する。Amend PR のチェックリストに「ADR-0105 残存参照の確認」を明記する。

撤退条件 (Rollback Plan)

  1. 一本化後 3 ヶ月で「冒頭要約が専門語で読めない」という指摘 (経路: GitHub issue ラベル feedback/readability・Slack #adr-feedback で受付。代理指標としてレビュアーが早わかりに平易化コメントを付けた PR 数も併用) が 3 件以上 (累計許容上限 2 件) になったら、専門語ゼロ 1 段落の枠 (旧 TL;DR) を早わかり直前に復活する Amend を起案する。発動時は adr-lint の冒頭 H2 位置規則の改修が必要になる可能性があり、その工数を事前に見積もった上で 30 日以内に判断する。
  2. ADR-0138 自体が撤退条件発動で必須化を撤回した場合、冒頭要約の受け皿がなくなるため、本 Amend を再評価する (TL;DR 箇条の復活を含めて 30 日以内に判断)。撤回確定時点で 5 営業日以内に TL;DR 箇条を暫定復活させる緊急 Amend を起案する。30 日の判断期間中は「早わかり省略可・TL;DR 任意」の暫定ルールが適用される。

コスト試算

  • 起案・審査: 約 0.25 人日 (本起案 + 審査 run + PR レビュー)。
  • 実装: 約 0.1 人日 (テンプレート 2 ブロック削除 + amends 辺と逆辺の宣言 + ADR-0105 残存参照の通読精査 + index 再生成)。類似実績 = ADR-0138 の Status flip + index 再生成が約 0.1 人日。
  • 運用: 追加コスト 0 円。むしろ body_generation に TL;DR 枠を足さないことが確定するため、ADR-0138 実装による生成トークン増 (1〜2 割) に TL;DR 分が上乗せされない。

Confirmation

  • 検証手段: テンプレートに TL;DR 枠が存在しないこと、および新規 ADR の冒頭要約が「決定の早わかり」1 つであることを、ADR-0138 の月次集計 (書き直し件数・形骸化指標) と同時に目視確認する。早わかりの平易さは operator_guide §4.4 のレビュー確認項目で毎 PR 確認する。
  • 実行頻度: 月次 (ADR-0138 の集計に相乗り)。レビュー確認は PR 毎。
  • 違反時対応: 新規 ADR に TL;DR 枠が再出現したらテンプレート参照元を特定して修正 PR を出す。専門外読者からの指摘は件数を記録し撤退条件 #1 の判定に使う。
  • KPI: 新規 ADR の冒頭要約数 = 1 (早わかりのみ) を 100% 維持。専門外読者からの「読めない」指摘 0 件/月 (許容上限: 3 ヶ月累計 2 件)。

参照 (References)

  • 関連 ADR:
    • ADR-0105 (ADR の用語 Tier・原語温存) — Amends (決定の 1 箇条「冒頭 TL;DR」のみ廃止。用語 Tier 規約本体は不変)
    • ADR-0138 (新規 ADR に冒頭サマリー「決定の早わかり」を必須化する) — 補完 (冒頭要約の一本化により同 ADR の実装を単純化する)
    • ADR-0107 (ADR 群を「探して再利用できる情報資産」にする) — 並立 (早わかりのパイロット)
    • ADR-0131 (amends 辺と逆辺の同一 PR 宣言規約) — 準拠
  • 関連 PR/Issue: -
  • 外部資料: 公用文作成の考え方 (2022)