← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0138type: adrstatus: superseded
pagemode: Standardkruchten: Executive/Propertyscope: platformimplementation_status: In Progress (sub 分 = PRproposed_at: 2026-06-11 18:23approved_at: 2026-06-11 19:13deciders: [email protected] (単独)business: meta
型付き辺: 出 4 / 入 2
関連: ADR-0144 ADR-0143 ADR-0142 ADR-0141 置換された: ADR-0146 宿題回答された: ADR-0140全体は INDEX →

ADR-0138: 新規 ADR に冒頭サマリー「決定の早わかり」を必須化する

  • Status: Superseded by ADR-0146 (本文内必須化を受理後生成の派生ビューへ置換・2026-06-12。元の受理 = PR #1771 merge 2026-06-11・代表取締役判断)
  • Mode: Standard
  • Kruchten Type: Executive/Property
  • Scope: platform
  • Implementation Status: In Progress (sub 分 = PR #1782 完了: テンプレート + 正典 §D + operator_guide。main 分 = body_generation プロンプト + adr-lint しきい値ルール、実装中)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-06-11 18:23
  • 承認日時 (JST): 2026-06-11 19:13
  • Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

ADR は 135 本まで増え、過去の決定を参照する場面 (新規決定との整合確認・実装・レビュー・経営判断) が日常化した。読者も設計者だけでなく、経営判断者や専門外の参画者まで広がっている。冒頭サマリー「決定の早わかり」(Y-statement 箇条形) は ADR-0107 でパイロット実装済みであり (Y-statement 箇条形への確定 = PR #1658、本文へのわかりやすさ適用 = PR #1654/#1659)、外部規範による裏づけも社内 how-to 文書 2 本に正典化済みである (文の軸 = 公用文作成の考え方 2022 / 構造の軸 = ミント ピラミッド原則)。読み筋の定義 (文脈/問題/問題点と課題/前提/決定/目的/代償) は docs/_internal/05_how-to/adr_structure_pyramid_principle.md §D にある。

§1.2 現状 (As-Is)

ADR 本文は専門家向けの構造 (コンテキスト/判断基準/代替案/決定/影響) で書かれており、「なにを・なぜ決めたのか」を知るには本文全体を読み解く必要がある。早わかりを実装済みの ADR は 135 本中 1 本 (0.7%・ADR-0107 のみ・実測 20 行/約 1,000 字)。型・正典・実物見本が揃っているのに規約がないため、新規 ADR は Decision Pipeline (body_generation) から従来構造のまま生成され続けており、パイロット後に自然普及した本数は 0 である。

§1.3 課題

理解できないわけではないが、決定の要旨を把握するための認知・時間負担が高く、専門から遠い読者ほど負担が増す。会社全体の意思決定の質は、過去の決定をどれだけ低い負荷で参照できるかに左右される。

§1.4 制約・要件

  • 規約は機械検査可能な形にすること (lint で検出できる形に落とせること)。
  • 起案者の追加作業を増やさないこと (起案テキストの Y-Statement 1 文を種に自動生成)。
  • 既存 134 本と審査中の在庫には遡及しないこと (実装完了時点の次番号以降のみ検査)。
  • 型の正典は 1 か所 (adr_structure_pyramid_principle.md §D) に置き、本文との二重管理を避けること。
  • 本文メタ欄が ADR-0137 で frontmatter へ移行中のため、位置定義は「メタ情報の直後」ではなく「H1 の後の最初の H2」とする。

§1.5 目標 (To-Be)

全ての読者が本文を通読せずに 1 画面で決定 (なにを・なぜ・代償) を把握でき、会社全体の意思決定の質が上がる状態。Non-Goals: 既存 134 本への遡及適用は本決定に含めない (受理後 30 日以内に別 ADR か過去 ADR 更新運用かを判断するフォローアップ義務として分離)。

決定

ADR が 135 本に増え決定の参照が日常化した文脈で、決定の要旨の理解に高い認知・時間負担がかかる課題に直面し、任意慣行のまま広げる案や索引側に要約列を持たせる案ではなく、受理後の新規 ADR 全件 (全 Mode) に冒頭節「決定の早わかり」を必須化し、生成テンプレートと adr-lint で機械強制することを選ぶ。全ての読者が本文を通読せずに 1 画面で決定を把握でき、会社全体の意思決定の質が上がるようにするためであり、生成プロンプト・lint ルールの保守が増えることと、既存 134 本との読み筋の不揃いが当面残ることを受け入れる。

実装は次の 2 点に閉じる。

  1. Decision Pipeline の body_generation プロンプトと rendered テンプレート (docs/adr/templates/template.md) に同節を組み込み、生成段階で自動的に付く状態にする。中身の型は正典 (adr_structure_pyramid_principle.md §D) に従い、文脈/問題/問題点と課題/前提/決定/目的/代償の箇条で書く。起案者の追加作業はない。
  2. adr-lint に「H1 の後の最初の H2 が『決定の早わかり』であること」のチェックを追加し、CI で新規 ADR への同梱を強制する (しきい値番号で対象外を分ける)。

判断基準 (Decision Drivers)

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#usableMust (×2.0)全ての読者 (専門外を含む) が本文を通読せずに決定の要旨 (なにを・なぜ・代償) を把握できる
2#maintainableHigh (×1.0)型の正典が 1 か所にあり、機械検査により規約が形骸化しない
3#efficientMedium (×0.5)起案者・パイプラインの追加負担が小さい (生成は自動・人手は確認のみ)

K.O. criterion: 機械検査できない規約は不採用 (lint で検出できる形に落とせること)。Must 軸の score < 3 は不採用。

3.2 評価軸 × 案スコア表

軸係数採択案 (A: 全 Mode 必須化 + lint 強制)案 B (任意慣行)案 C (索引側に要約列)案 D (既存 134 本も一括バックフィル)案 E (Standard/Critical のみ必須)
#usable2.041253
#maintainable1.041323
#efficient0.545413
加重和 (正規化)0.8000.2430.5000.6710.586
K.O. 通過 (Must ≥3)✓❌❌✓✓

検討した代替案 (Alternatives Considered)

  • 案 B: 任意慣行のまま広げる (規約化しない) — パイロット後の自然普及は 0 本という実測があり、新規 ADR の生成元 (body_generation) が変わらない限り 1/135 のまま動かない (Must #usable K.O. 不通過)。
  • 案 C: 本文は変えず、索引 (adr-index.json / INDEX.md) 側に平易な要約列を持たせる — 本文を直接開いた読者 (最も多い導線) に届かず、要約の正典が本文の外に出るため本文との食い違いが構造的に起きうる (Must #usable K.O. 不通過)。既存 134 本への将来対応の選択肢としては残す。
  • 案 D: 既存 134 本も含めて全数への一括追記 (バックフィル) を義務化 — 受理済み本文は変更しない原則との整理と、過去本文を LLM で要約する際の捏造リスク管理が別途必要で、1 決定に収まらない。本起案から分離し、受理後 30 日以内の判断で扱う。
  • 案 E: Standard/Critical のみ必須とし Light は除外 — lint 判定が Mode 依存の 2 系統になり機械検査が複雑になる。早わかりは実測 20 行程度で Light でも負担が小さく、どの ADR も同じ読み筋で読める価値の方が大きい。

影響 (Consequences)

§5.1 正の影響 (Good)

  • 受理後の新規 ADR すべてに統一された読み筋が立ち、読者の把握コストが本文通読から 1 画面に縮む。
  • 決定の参照が軽くなり、過去の決定を踏まえた質の高い意思決定がしやすくなる。
  • PR 段階の人間レビューも要旨から読み始められる。

§5.2 負の影響 (Bad)

  • body_generation プロンプトと adr-lint ルールの保守対象が 1 つずつ増える。
  • ADR 1 本あたりの生成トークンが増える (コスト試算参照)。
  • 既存 134 本との読み筋の不揃いがフォローアップ判断まで残り、参照頻度の高い古い ADR ほど早わかりがない状態が続く (Gate 1 #6 対応: 受理後 30 日以内の判断で参照頻度上位 20 本を優先バックフィル対象とする方針を起案するフォローアップを義務化。30 日不履行時のエスカレーション先は Decision Pipeline オーナー、最終承認者は起案者本人とする)。
  • 早わかりが「公式要旨」として経営判断に単独引用され、本文の前提条件や代償が伝わらないまま意思決定が行われるリスク (Gate 1 #5 対応: 早わかりの末尾に「詳細は本文の影響・撤退条件セクションを参照のこと」という定型注記を必須箇条として正典 adr_structure_pyramid_principle.md §D に追加する)。

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

  • 生成された早わかりが本文と食い違う可能性 (LLM 生成の要約)。PR 段階の人間レビューと Cross-Validation のセクション構造比較で検出する (Gate 1 #3 対応: Cross-Validation の比較対象・タイミング・粒度は Confirmation §検証手段で明示)。
  • LLM が body_generation 時点で早わかりを生成固定するため、PR レビュー中に本文が変更されると早わかりが古いままになる可能性 (Gate 1 #3 対応: 撤退条件 #2 の「3 ヶ月で 3 件以上の食い違い」発動時、本文確定後に要約を後生成する方式への変更を選択肢に含める)。
  • lint が H2 見出しの存在しか検査しないため、内容が空または定型句だけの早わかりが量産されるリスク (Gate 1 #4 対応: PR レビューチェックリストに「早わかりの 7 箇条 (文脈/問題/問題点と課題/前提/決定/目的/代償) の中身が定型句でないこと」を追加し、§5.2 の月次集計に内容品質指標を含める)。
  • ADR-0137 の frontmatter 移行完了時にテンプレート構造が変わり lint が誤検知してパイプラインが停止するリスク (Gate 1 #2 対応: Confirmation §検証手段に再検証トリガーを明示し、ADR-0137 の受理チケットに本 ADR の lint 互換確認をブロッカーとして追加する)。

撤退条件 (Rollback Plan)

  • 導入後の新規 ADR 10 本のうち、早わかりの人手による全面書き直しが 6 本以上 (50% 超) 必要になったら、生成品質が型に達していないとみなし、必須化を撤回して任意の節に戻す。
  • 早わかりと本文の食い違い (要旨の誤り) が受理後 3 ヶ月で 3 件以上見つかったら、生成方式を見直す (本文確定後に要約を後生成する方式への変更を含む)。
  • スコープ外に送った既存分の扱いの判断 (受理後 30 日以内) が 60 日を過ぎても未実施なら、本決定の運用が回っていないとみなし本 ADR を再評価する。
  • 撤退操作の手順 (Gate 1 #1 対応): 撤退条件が発動した場合、起案者 ([email protected]) が以下の手順を実施する。
    1. adr-lint の見出し存在チェックルールを無効化する PR を起票 (所要工数 約 0.1 人日)。
    2. body_generation プロンプトから「決定の早わかり」生成指示を除去する PR を併せて起票 (所要工数 約 0.1 人日)。
    3. 両 PR の承認者は起案者本人 (単独 Decider) とし、lint ルール削除 PR 自体は早わかり節を持たないため新ルールの merge block には該当しない (撤退操作そのものが新ルールに阻まれないことを保証)。
    4. 撤退後の新規 ADR は早わかり節が任意となる。

コスト試算

  • 実装: 合計約 1.0 人日。内訳:
    • body_generation プロンプト改修 + golden eval 確認 約 0.5 人日 (main・prompt-cicd フロー)
    • adr-lint 見出しチェック追加 + テスト 約 0.25 人日
    • rendered テンプレートと正典 how-to の追従 約 0.25 人日 (sub)
  • 類似実績: ADR-0136 実装 (スクリプト判定追加 + 文書追従) が約 0.25 人日。
  • 運用: 早わかりは ADR-0107 実測で 20 行/約 1,000 字。body_generation の出力が 1 本あたり 1〜2 割増え、API 費は月数ドル規模の増 (Pipeline の現状 API 費 月約 $200 に対し +2〜5% 想定)。人手の追加作業は PR レビュー時の早わかり確認のみ (1 本あたり数分)。

Confirmation

  • 検証手段:
    • adr-lint の新ルールで、新規 ADR (しきい値番号以降) に「決定の早わかり」H2 見出しが H1 直後の最初の H2 として存在することを CI で検査する。違反は merge block。
    • 型の中身 (箇条ラベル 文脈/問題/問題点と課題/前提/決定/目的/代償 が正典どおりか、定型句や空の体言止め羅列でないか) は PR 段階の人間レビューで確認する。PR レビューチェックリストに該当項目を追加する。
    • Cross-Validation で「早わかり 7 箇条」と「本文 §1〜§5 のセクション要旨」を構造比較し、食い違い (要旨の誤り) を検出する。実行タイミングは PR 作成時と本文最終レビュー直前の 2 回、検出粒度は箇条単位。
    • lint ルール再検証トリガー: ADR-0137 (frontmatter 移行) の実装完了時、本 ADR の lint ルールが新テンプレート構造と互換であることを再検証する。ADR-0137 の受理チケットに本項目をブロッカーとして追加する。
  • 実行頻度: CI 毎 (全 PR)。生成品質 (人手書き直しの件数・食い違い件数・形骸化件数) は月次で集計する。
  • 違反時対応: lint 違反は merge block で混入を防ぐ。早わかりの書き直しが必要だった場合は PR 内で修正し、件数を記録して撤退条件 #1 の判定に使う。食い違いは撤退条件 #2、形骸化件数は月次レトロで継続監視。
  • KPI:
    • 受理後の新規 ADR の早わかり同梱率 100% (lint で保証)。
    • 人手による全面書き直し率 50% 以下 (超過で撤退条件 #1 発動)。
    • 受理後 3 ヶ月で本文との食い違い 3 件未満 (超過で撤退条件 #2 発動)。
    • 月次集計で「早わかりの 7 箇条がすべて 20 字以下の体言止めのみ」の ADR 件数を内容品質指標として記録 (形骸化早期検知)。

参照 (References)

  • 関連 ADR:
    • ADR-0107: ADR 群を「探して再利用できる情報資産」にする — 補完 (同 ADR でパイロット実装した冒頭サマリーを、全新規 ADR の規約へ一般化する)
    • ADR-0050: Synthesis 標準テンプレートの確立 — 補完 (canonical ADR 構造の冒頭に節を 1 つ追加する)
    • ADR-0036: Confirmation セクション追加 — 並立 (節の必須化という同型の先行例)
    • ADR-0088: コスト試算必須化 — 並立 (同上)
    • ADR-0091: 起案前ゲートの数値要件 — 並立 (機械強制の同型先行例)
    • ADR-0137: ADR メタデータの frontmatter 移行 — 並立 (本文メタ欄が将来削除されるため、早わかりの位置は「H1 後の最初の H2」と定義して整合させる。実装完了時に lint ルール再検証が必要)
  • 関連 PR/Issue: PR #1658 (Y-statement 箇条形確定)、PR #1654 / #1659 (本文へのわかりやすさ適用)
  • 外部資料:
    • 公用文作成の考え方 (2022) — 文の軸
    • ミント『ピラミッド原則』 — 構造の軸
    • docs/_internal/05_how-to/adr_structure_pyramid_principle.md §D — 読み筋の正典定義
    • Maynez et al. 2020 (abstractive summarization の faithfulness 研究) — LLM 要約の事後検証漏れリスク根拠