← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0024type: adrstatus: accepted
pagemode: Standardkruchten: Propertyscope: platformimplementation_status: Done (§1/§5 サブ見出し body_generation.ts 実…proposed_at: 2026-05-13 00:23approved_at: 2026-05-13 00:30deciders: [email protected] (単独)business: meta
型付き辺: 出 7 / 入 3
前提とする: ADR-0023 関連: ADR-0021 ADR-0033 ADR-0088 ADR-0030 ADR-0097 ADR-0113 部分修正された: ADR-0091 ADR-0099 前提とされる: ADR-0038全体は INDEX →

ADR-0024: ADR テンプレートのコンテキスト/影響セクションを構造化サブ見出しに整える

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Property
  • Scope: platform
  • Implementation Status: Done (§1/§5 サブ見出し body_generation.ts 実装済)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-13 00:23
  • 承認日時 (JST): 2026-05-13 00:30
  • Deciders: [email protected] (単独)

Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は ADR-0031 §決定セクションおよび docs/adr/README.md の Kruchten 3 分類ガイドを参照。 Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

コンテキスト

1.1 背景 (Background)

ADR-0023 で ADR ドキュメント群の構造を業界標準 (Nygard + MADR 4.0 ミニマル統合) に整えた直後、RQ-042 並列調査 (Claude Research + Gemini Deep Research) で両エンジンが完全一致で推奨するコンテキスト構造化方針が得られた。これを受けて、テンプレ自体のサブ見出し化を決定するタイミングとなった。

1.2 現状 (Current State / As-Is)

ADR テンプレート (docs/adr/templates/template.md) の §1 コンテキストと §5 影響は依然として「単一節での自由記述」を基本とし、サブ見出しへの分解は「詳細起案の場合のみ §1.1〜§1.5 に分割可」というコメントレベルの示唆にとどまっている。ADR-0021 (UC スライス) は先行事例として独自に §1.1〜§1.6 構造で書かれているが、テンプレと実態が乖離している。

1.3 課題 (Problem)

単一節の §1 コンテキストには「過去の経緯 (背景)」「現在の状況 (現状)」「現在の痛み (課題)」「動かせない前提 (制約)」「達成したい未来 (目標)」の 4 種類の時間軸・性質の異なる情報が混在し、(1) 後から ADR を読む人 (Jr エンジニア・将来の自分・副業協力者) が論理を追いにくい、(2) 客観事実と主観目標の混同で代替案の評価軸がブレる、(3) 200〜400 行規模の Critical Mode で認知負荷が著しく高い、という問題が発生している。このまま放置すると 2026-10 入社予定の Jr エンジニアのオンボーディング期間が伸びるリスクがある。

1.4 制約・要件 (Constraints & Requirements)

  • 既存 ADR-0001〜0023 はイミュータブル原則により遡及適用しない (ADR-0023 で確立した原則)
  • 改修対象は docs/adr/templates/template.md と docs/adr/README.md の 2 ファイルのみに限定 (Pipeline ノード自体の改修は含まない)
  • 2026-10 入社予定 Jr エンジニアのオンボーディング開始までに整備完了
  • RQ-042 並列調査の両エンジン完全一致部分のみを採用 (片方しか推奨していない構造は不採用)

1.5 目標 (Goals / To-Be)

ADR テンプレートの §1 / §5 を Mode 別の構造化サブ見出しに整え、Jr エンジニアの認知負荷を低減し、客観事実と主観目標を構造的に分離する。Non-Goals: 既存 ADR-0001〜0023 の遡及改変、Decision Pipeline ノード自体の改修、ADR-0021 の §1.1〜§1.6 構造との完全一致 (差異理由は §決定に明記)。

決定

§1 コンテキストを 5 サブ見出し (§1.1 背景 / §1.2 現状 / §1.3 課題 / §1.4 制約・要件 / §1.5 目標) に、§5 影響を 3 サブ見出し (§5.1 正の影響 / §5.2 負の影響 / §5.3 中立・トレードオフ) に分解し、Standard Mode で採用推奨・Critical Mode で必須・Light Mode では単一節維持とする。「該当なし」の項目はサブ見出しごと削除 (空欄禁止)、歯抜け番号は許容、各サブ項目の本文は 1〜2 文に制限する。既存 ADR-0001〜0023 はイミュータブル原則により遡及適用しない。改修対象は docs/adr/templates/template.md と docs/adr/README.md の 2 ファイルのみ。

ADR-0021 (§1.1〜§1.6 = 6 区分) との差異理由

ADR-0021 (UC スライス開発と監査ログ機構の採用) は先行事例として §1.1〜§1.6 の 6 区分 (現状 / 課題 / 要求 / 前提条件 / 制約条件 / 判断基準) を採用したが、本テンプレートでは §1.1〜§1.5 の 5 区分とする。差異の根拠は以下の通り:

  • ADR-0021 の §1.6 「判断基準」を本テンプレートでは §2 (Decision Drivers) として独立節化済 — MADR 4.0 の標準構造に合わせ、判断基準を §1 コンテキスト内に埋め込むのではなく独立節で扱う方が、代替案 (§3) との論理的繋がりが明確
  • ADR-0021 の §1.4「前提条件」と §1.5「制約条件」を本テンプレートでは §1.4「制約・要件」に統合 — 1 人開発の規模では「前提」と「制約」の区別が起案コストに見合わない冗長性となるため統合
  • 結果: ADR-0021 の 6 区分 - 判断基準の独立節化 (-1) - 前提/制約の統合 (-1) + 背景の追加 (+1) = 5 区分。情報量は減らさず、配置のみ変更する整理

ADR-0021 は本決定の起案前に書かれた先行事例として位置付けられ、本テンプレートで §1.1〜§1.5 を採用しても ADR-0021 の不変性は維持される (本決定は遡及適用しない)。

検討した代替案 (Alternatives Considered)

  • 案 A: §1 コンテキストと §5 影響を Standard 以上で正式サブ見出し化 ← 採択

    • Good: 両エンジン完全一致の推奨構造、業界標準 (MADR / Tyree & Akerman / arc42) 準拠
    • Good: Jr エンジニアの認知負荷低減、論理を追いやすい
    • Good: ADR-0021 (UC スライス) の先行事例と整合
    • Good: Light Mode は単一節を維持し、軽量起案の柔軟性を温存
    • Bad: Standard 以上で起案コストがやや増加 (1 ADR あたり推定 5-10 分)
    • Bad: 既存 ADR-0001〜0023 と新 ADR-0024 以降の見た目が不統一 (3 層併存)

  • 案 B: 現状維持 (コメント示唆のまま) — 不採用

    • Good: 起案コスト増加なし、既存 ADR と見た目が統一、「分割可」コメントで自由度が温存
    • Bad: 単一節での時間軸 / 客観・主観の混在問題が解決しない
    • Bad: ADR-0021 の先行事例とテンプレートの乖離が放置される、Jr エンジニア入社時の認知負荷が高いまま

  • 案 C: Critical Mode 限定で必須化、Standard はオプション — 不採用

    • Good: Standard Mode の起案コスト増加を回避、Critical (不可逆判断) のみ厳格化で焦点を絞れる
    • Bad: Standard Mode (80-200 行) も十分に長く、サブ見出しの恩恵が大きい範囲
    • Bad: Mode 境界の判断負荷が増加、案 A と案 B の中間的な妥協で両方の良さを取りきれない

  • 案 D: §1 だけサブ見出し化、§5 は単一節のまま — 不採用

    • Good: §1 の時間軸混在問題が最も深刻なため、影響範囲を限定して効果最大化
    • Bad: §5 の Good/Bad/Neutral 区別も読みやすさに寄与 (Fairy Tale アンチパターン回避にも有効)
    • Bad: 構造化が中途半端で「なぜ §1 だけ?」という疑問を後から呼ぶ

影響 (Consequences)

5.1 正の影響 (Good)

  • Jr エンジニア (2026-10 入社) の認知負荷低減: サブ見出しにより論理が追いやすくなり、Critical ADR 1 件あたり 20-30 分の読解時間節約。ADR 5 件読めば +1 時間のオンボーディングコスト増を回収可能
  • 客観事実と主観目標の分離: §1.2 現状 (As-Is) と §1.5 目標 (To-Be) の分離により、代替案の評価軸がブレにくくなる
  • Fairy Tale アンチパターン回避: §5.2 負の影響を必須 1 行以上とすることで、楽観バイアスのある ADR を抑止
  • 業界標準との整合: MADR / Tyree & Akerman / arc42 / David Youngblood ADR Master 等の先行事例と一致
  • ADR-0021 (UC スライス) の先行事例とテンプレートの整合性回復
  • Parallel Review LLM (Gemini / Claude / GPT-4o): サブ見出しごとの個別評価が可能になり、レビュー品質向上

5.2 負の影響 (Bad)

  • 起案コスト増: Standard 以上で 1 ADR あたり 5-10 分増 (代表取締役本人)
  • 既存 ADR との見た目の不統一: ADR-0001〜0020 は単一節、ADR-0021 以降は分割、ADR-0024 以降は明示的サブ見出し、と 3 層が併存
  • 「該当なし」運用判断負荷: 削除するか歯抜け番号で残すかの判断が起案ごとに発生 (README で「項目ごと削除、番号は歯抜け許容」と明文化して固定化)
  • 副業協力者 / 業務委託エンジニア: 初回 30 分の学習コスト (新テンプレ + README + サンプル ADR 読了)

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

  • 形式的フォーム埋め化 (Blueprint in Disguise): サブ見出し本文が 3 文以上に膨張するリスク → 1〜2 文ルールで抑制、wc -l 確認で検知
  • 歯抜け番号への違和感蓄積: Jr エンジニアから「番号が飛んでて気持ち悪い」フィードバックの可能性 → 撤退条件 #3 で前詰めルールに変更可能
  • Light Mode 濫用: Standard 相当規模 (80-200 行) なのに Light で起案される傾向 → 月次の ADR モード分布確認で監視
  • Pipeline LLM が新構造を Mega-ADR と誤判定: Scoring Gate で構造化過剰減点が頻発する可能性 → Pipeline 側のプロンプト改修 ADR を別途起案
  • 金銭コスト: 0 円 (SaaS / API / インフラ追加なし)
  • コスト構造: 代表取締役の実装コスト (一回) + 各ステークホルダーの学習コスト (各人初回のみ) は分離して扱う

コスト試算詳細

実装コストと学習コストを分離して再集計 (Parallel Review #1 数字整合性指摘対応):

A. 実装コスト (代表取締役、一回のみ発生)
項目見積もり根拠
docs/adr/templates/template.md の §1 / §5 改訂30 分既存 119 行に §1 サブ見出し 5 個 + §5 サブ見出し 3 個 = 計 8 ブロック追加。1 ブロック 3-4 分
docs/adr/README.md の Mode 別構造粒度表追加 + 運用ルール明文化30 分新規セクション 1 個 + 運用ルール 3 件。表 10 分 + 文書化 15 分 + 整合性確認 5 分
次回 ADR-0025 起案で実地検証+0 分通常起案フローで吸収、ADR-0023 DoD #7 と兼用
A 小計 (実装コスト)約 1 時間ADR-0018 (ドキュメント整理 1 件) と同等規模
B. 学習コスト (各ステークホルダー、初回のみ)
対象見積もり根拠
副業協力者 (1 名あたり初回)30 分新テンプレ 10 分 + README 10 分 + サンプル ADR 10 分
業務委託エンジニア (1 名あたり初回)30 分同上
Jr エンジニア (2026-10 入社、初回)+1 時間旧 ADR-0001〜0023 と新 ADR-0024 以降の差分理解。逆に Critical ADR 1 件あたり 20-30 分節約 → ADR 5 件で回収
代表取締役本人0 分起案者本人のため学習なし
B 小計 (初回学習コスト、副業+委託+Jr 1 名ずつの場合)約 2 時間ステークホルダー人数に比例
総括
  • 本 ADR を採用するために代表取締役が今すぐ投じる時間: 約 1 時間 (A のみ)
  • 将来のステークホルダー参画時に発生する累積学習コスト (1 人ずつの場合): 約 2 時間 (B、参画タイミング分散)
  • 長期トータル (1 + 2): 約 3 時間 (今すぐ発生する金額換算 = 0 円、人的稼働の機会コストのみ)

完了条件 (検証可能メトリクス)

#完了条件検証コマンド (Pass 閾値)
1ADR-0024 が Accepted 化grep -E "^- \*\*Status\*\*: Accepted" docs/adr/0024-*.md → exit 0
2テンプレ §1 が 5 サブ見出し構造grep -cE "^### 1\.[1-5] " docs/adr/templates/template.md → = 5
3テンプレ §5 が 3 サブ見出し構造grep -cE "^### 5\.[1-3] " docs/adr/templates/template.md → = 3
4README に Mode 別構造粒度表が存在grep -E "Light|Standard|Critical|Initial Master" docs/adr/README.md | wc -l → >= 4
5README に運用ルール 3 件明文化grep -cE "1〜2 文ルール|該当なし.*削除|歯抜け番号" docs/adr/README.md → >= 3
6Pipeline 採番がハイフン形式で成功ls docs/adr/0024-*.md | wc -l → = 1
7本 ADR が新サブ見出し構造を遵守grep -cE "^### 1\.[1-5] |^### 5\.[1-3] " docs/adr/0024-*.md → >= 5
8CI markdown-link-check が passgh pr checks <PR> で SUCCESS 確認
9既存 ADR への遡及改変なしgit diff main..HEAD -- 'docs/adr/0001-*' ... 'docs/adr/0023-*' | wc -l → = 0

撤退条件 (Rollback Plan)

撤退トリガーと対応マトリクス

#判定指標閾値対応レベル手順
1ADR 起案頻度が半減月次起案数が現状の 50% を下回る部分撤退手順 A: Standard を必須→推奨に格下げ (30 分)
2「該当なし」サブ見出しが新規 ADR の 50% 以上直近 6 件中 3 件以上縮退手順 B: 5 項目分解を Critical 専用に縮退 (45 分)
3歯抜け番号の読みにくさフィードバックJr / 外部レビュアから明示的指摘微修正手順 C: 歯抜け番号を前詰めに変更 (30 分)
4Pipeline Triage / Socratic が新構造で誤動作採番失敗 or Gate チェックエラー本 ADR 不変Pipeline 側の改修 ADR で対応
5Health Metrics の危険閾値に 3 ヶ月連続到達(下記参照)完全撤退手順 D: テンプレ完全 revert (2 時間)

Health Metrics (負債化リスク定量指標)

指標健全閾値警告危険根拠
サブ見出し採用率>= 90%70-90%< 70%Triage 誤判定 1 割を吸収、70% 以下は形骸化
該当なし削除率10-30%30-50%> 50%ADR-0021 実績 (1/6=17%) から逆算
空セクション率0%1-10%> 10%ルール上違反、10% 超で Blueprint in Disguise 化
1〜2 文ルール違反率< 20%20-40%> 40%MADR 公式「2-3 sentences」基準
平均 ADR 行数80-200 行200-300> 300Standard Mode の想定範囲
起案頻度変化率>= 0.80.5-0.8< 0.5コスト +5-10 分は 20% 低下に収まる想定

Review After タイミング

  • 1 ヶ月後 (2026-06-12 前後): 採用率 >= 90%、空セクション 0%
  • 3 ヶ月後 (2026-08-12 前後): ADR >= 3 件、削除率 10-30%
  • 6 ヶ月後 (2026-11-12 前後): Jr エンジニア入社後の学習コスト定性ヒアリング
  • 1 年後 (2027-05-12 前後): 全 Health Metrics 年次レビュー、ADR 50 本超チェック
  • 以降 6 ヶ月ごと: Health Metrics の継続観測

撤退コスト

完全撤退は約 2 時間 (テンプレ revert 30 分 + 既存新形式 ADR 扱い 30 分 + README 戻し 15 分 + 撤退 ADR 起案 1 時間)。採用コスト (1 時間) の 2 倍程度で撤退可能な範囲。Git 履歴に全変更が保存されるためデータロスなし、git revert で完全復旧可能。

撤退時の既存 ADR-0024 以降の扱い (撤退の非対称性)

完全撤退 (手順 D) を実行しても、既に新形式で起案された ADR-0024 以降の本文はイミュータブル原則により遡及修正できないため永続残置される。Parallel Review #5 で指摘された通り、この非対称性に対する具体策を明文化する:

既存新形式 ADR の状態採用する方針1 件あたりの追加コスト
採用方針 (推奨)そのまま残置 — イミュータブル原則優先、新形式 ADR は「試行期間の記録」として保持0 分
補足追記 (例外)README に「ADR-0024〜NNNN は新形式の試行期間、ADR-NNNN+1 以降は旧形式」と注記全体で 10 分 (件数依存なし)
Supersede (限定例)新形式の決定そのものが致命的に誤りだった場合のみ、新 ADR で Supersede 宣言1 件あたり 60 分 (新 ADR 起案コスト)

判断ルール: 撤退理由が「運用負荷の問題」(Health Metrics 危険閾値到達等) の場合は方針 1 (残置)、撤退理由が「決定内容の誤り」(MADR 標準への重大な不整合発見等) の場合のみ方針 3 (Supersede) を検討。残置時の混乱は方針 2 (README 注記) で吸収。

3 層併存への対応: 撤退後は旧形式 ADR-0001〜0020 (単一節) / ADR-0021 (§1.1〜§1.6) / ADR-0024〜NNNN (新形式) の 3 層が併存し、Jr エンジニア入社時のオンボーディングで混乱要因となるリスクがある。README に各層の経緯と読み方ガイドを明記することで吸収する (10 分の追加コストに織り込み済)。

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

  • 検証手段: scripts/adr-lint.mjs の規約チェック + 手動レビュー
  • 実行頻度: PR ごと
  • 違反時の対応: 自動 fail

参照 (References)

  • 関連 ADR:
    • ADR-0023: ADR ドキュメント群の構造業界標準化 (本 ADR の前提、本決定はこれを拡張)
    • ADR-0021: UC スライス開発と監査ログ機構の採用 (§1.1〜§1.6 構造の先行事例)
  • 関連 PR/Issue: -（要追記: ADR-0024 採番後の実装 PR URL）
  • 外部資料:
    • docs/_internal/research_prompts/RQ-042_adr_context_subsection_structuring_result_claude.md
    • docs/_internal/research_prompts/RQ-042_adr_context_subsection_structuring_result_gemini.md
    • docs/_internal/research_prompts/RQ-042_adr_context_subsection_structuring_synthesis.md
    • docs/adr/templates/template.md (現状のテンプレート / 本 ADR で改訂予定)
    • docs/adr/README.md (運用ガイド / 本 ADR で Mode 別粒度表追加予定)
    • MADR 4.0 / Tyree & Akerman / arc42 / David Youngblood ADR Master / Olaf Zimmermann アンチパターン (Mega-ADR / Blueprint in Disguise / Fairy Tale)