ADR-0162: ADR 本文と分離した impl_detail 節を正式機能化し、機械担保 (adr-lint) と派生ビュー (adr-index) を実装する

• Status: Accepted
• Mode: Standard
• Kruchten Type: Existence/Executive
• Scope: platform
• Implementation Status: Done (PR #2426)
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-20 19:41
• 承認日時 (JST): 2026-06-21
• Approver Role: platform
• Approver Who: [email protected]
• Driver: [email protected]
• Consulted: Decision Pipeline AI 審査 (Gate 0-4)

コンテキスト

§1.1 背景

ADR-0149 (Accepted 2026-06-13) は残タスクを SSoT ページ + 派生索引拡張で扱う方針を決定し、その派生として ADR 本文に「実装状況詳細 (impl_detail) 節」を試行的に追加する改修が PR #2026 (merged) で実施された。ADR-0149 ページに ## 実装状況詳細 (impl_detail) 節 + <!-- impl_detail:start/end --> マーカーで「ADR 本文ではない/差し替え可」を明示し、短縮した implementation_status (frontmatter / 本文太字メタ) との分離を試行した。ADR-0149 残タスク #1 で「正式化 / 撤退 / 現状維持」の判断を 2026-06-19 セッションで達希に確認した結果、正式化 が選択された。

§1.2 現状 (As-Is)

• impl_detail 節は HTML コメントマーカーだけで意味付けされ、adr-lint は「未知だが許容される H2」として通すに過ぎない。「ADR 本文ではない」ことの機械的担保は未実装。
• 派生ビュー化も未実装で、ADR-0149 の implementation_status を短縮した副作用として、adr-index.mjs の「Impl状況詳細」列が 0149 で — になっており、詳細は impl_detail 節 (本文中) にしか無い = 機械可読でない状態。
• マーカー慣習が ADR テンプレ / operator_guide に明文化されていないため、新規 ADR は impl_detail 節を使えない (Jr が見つけられない)。

§1.3 課題

試行のままではマーカーコメントだけの暗黙慣習に留まり、新規 ADR で利用が広がらず、ADR-0146 路線 (決定の早わかりを派生ビューへ) の最初の本格運用例として不十分。adr-index 「Impl状況詳細」列が ADR-0149 で — のまま機械可読性が失われている。

§1.4 制約・要件

• マーカー仕様は PR #2026 (<!-- impl_detail:start --> ... <!-- impl_detail:end -->) と互換維持。
• 既存 ADR (impl_detail 節なし) は挙動不変 (false positive 0)。
• adr-lint / adr-index が新規 ADR で 100% 動作。
• 実工数 2 人日 (上振れ警戒 2.4 人日)。
• 実装は main 役割で人間が書く (LLM コストなし)。

§1.5 目標 (To-Be)

impl_detail 節を機械担保 (adr-lint) + 派生ビュー (adr-index) + ADR テンプレ明文化を伴う一級機能に昇格させ、ADR-0146 路線の最初の参考実装にする。Non-Goals: 既存 ADR への一括移設、frontmatter への移設 (ADR-0137 と分離)。

決定

〔X〕 ADR 本文と分離した impl_detail 節を 〔Y〕 ADR-0146 路線 (決定の早わかりを派生ビューへ) の最初の本格実装として正式機能化することで 〔A〕 試行のままマーカーコメントだけに留めるのではなく 〔Z〕 機械担保 (adr-lint) と派生ビュー (adr-index) を伴う一級機能に昇格させる。〔B〕 これにより ADR 本文を「決定だけ読みたい」読み手向けに簡潔に保ちつつ実装状況詳細を機械可読にし 〔C〕 ADR-0146 路線の最初の完成形を提示することで以降の派生ビュー化 ADR の参考実装にする。

実装スコープ (main 役割):

1. メタ抽出ユーティリティ (scripts/lib/adr_meta.mjs): extractImplDetail(text) → {content, hasMarker} / stripImplDetail(text) → text_without_impl_detail を追加。マーカーは <!-- impl_detail:start --> ... <!-- impl_detail:end --> (PR #2026 と互換)。
2. adr-lint 構造検査 (scripts/adr-lint.mjs): impl_detail 節を「ADR 本文外」として扱い、本文構造検査 (必須 H2 等) からスキップ。ただし構造検査のみスキップし、コンテンツ品質検査 (リンク切れ・用語統一) は impl_detail 節も対象にする 2 段階スキップ方針 を採用 (将来ルール追加者向けに README / コメント明記)。既存 ADR (impl_detail なし) は挙動不変。
3. 派生ビュー (scripts/adr-index.mjs): impl_detail 節を持つ ADR について「Impl状況詳細」列の入力として読み、INDEX.md / adr-index.json に反映。impl_detail 節なし ADR は従来通り implementation_status のみ。
4. ADR テンプレ / operator_guide 明文化: impl_detail 節の使い方 (任意・短縮 implementation_status と併用・SSoT は本文の節) を ADR テンプレと operator_guide に追記。「impl_detail を選ぶ条件」を具体基準として明記 (例: implementation_status が 100 文字超かつ段階的実装を伴う ADR は impl_detail 推奨)。
5. 2 か所同期 lint: impl_detail 節があるなら implementation_status は短縮形式という形式チェックを追加。
6. 使用想定: ADR-0149 を最初の正式化対象。今後の ADR は任意で impl_detail 節を利用可。

判断基準 (Decision Drivers)

3.1 評価軸

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

3.2 評価軸 × 案スコア表

検討した代替案 (Alternatives Considered)

• 案 A: 撤退 (PR #2026 を revert 相当に戻す) — ADR-0149 を元の長い inline status に戻す。#usable が score 1 (本文が長く実装詳細混在) で実用に耐えない。試行投資 (#2026) も無駄になる。不採用。
• 案 B: 現状維持 (試行のまま放置) — adr-lint が「未知だが許容」と通すため目立った問題は起きないが、Must 軸 (#maintainable / #operable) ともに score 2 で K.O. を通過しない。新規 ADR で利用が広がらず、ADR-0146 派生ビュー化路線の最初の本格運用例として不十分。不採用。
• 案 C (採用): 正式化 (機械担保 + 派生ビュー化 + テンプレ明文化) — adr-lint + adr-index で一級機能に昇格。実装コスト 2 人日と適度で、ADR-0146 派生ビュー化路線と整合し、新規 ADR も使える。

影響 (Consequences)

§5.1 正の影響 (Good)

• ADR 本文が短くなり「決定だけ知りたい」読み手の認知負荷が下がる。
• impl_detail 節は派生ビュー (adr-index 別列) で機械可読。
• 新規 ADR は任意で impl_detail を使え、未使用 ADR も互換維持。
• ADR-0146 路線の最初の参考実装になる。

§5.2 負の影響 (Bad)

• 2 か所同期リスク: implementation_status (短縮) と impl_detail 節 (詳細) の 2 か所が乖離する可能性 (実装が進んでも片方を更新し忘れる)。ADR-0137 frontmatter-meta-sync と類似の課題。adr-lint で形式チェック (impl_detail 節があるなら implementation_status は短縮形式) を追加して緩和するが、意味的乖離は lint で検出不能であり、月次 adr-lint の頻度では最大 30 日間 adr-index に誤情報が公開される。週次目視を Confirmation に追加して運用カバーする。
• 撤退時の情報消失リスク: PR #2026 で ADR-0149 の実装詳細は impl_detail 節に集約済みであり、撤退条件「案 A 縮退」を実行すると impl_detail 節のテキスト (Phase 1-2 Done / PR 一覧 / 残タスク) は特定 git commit を cherry-pick しなければ復元できない。撤退条件に逆移設手順を明記して緩和。
• 採用促進の強制力なし: 「任意で利用可」のため新規 ADR が選ばないと KPI 1 (半年で ≥2 本) を達成できない。operator_guide に選択基準を明記して緩和。

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

• 派生ビュー化により ADR 本文と adr-index の 2 か所に impl_detail 情報が分散する形になる。SSoT = ADR 本文の impl_detail 節とし、adr-index は派生 (生成) 物として明示。
• adr-lint の構造検査スキップは 2 段階方針 (構造検査のみスキップ、コンテンツ品質検査は対象) で対応するが、将来のルール実装者が方針を理解する必要があり、README / コメント明記で緩和。

撤退条件 (Rollback Plan)

• 半年後 (≤ 2026-12-19) で impl_detail 節を利用する ADR が 2 本未満 (ADR-0149 のみ) なら、本 ADR を status: deprecated へ遷移させ、PR #2026 と本 ADR の改修を revert (案 A 縮退)。
• adr-index の「Impl状況詳細」列に false positive (impl_detail 節なし ADR が描画される) が 1 件でも発生したら即修正。修正できなければ deprecated。
• impl_detail 節の adr-lint 構造検査スキップが、別の lint チェックを副作用で誤って通過させる事例 (false negative) が出たら即修正。修正できなければ deprecated。
• 2 か所同期 lint (impl_detail と implementation_status の整合) が 3 ヶ月 (≤ 2026-09-19) で月次 1 件以上の違反を継続的に検出するなら、「impl_detail 利用 ADR の維持コストが過剰」と判定し deprecated を検討。

逆移設手順 (案 A 縮退時):

1. PR #2026 マージコミット (git log --all -- docs/adr/0149-*.md で特定) を起点に、impl_detail 節へ移設された差分を git show <commit> で抽出。
2. 抽出テキストを ADR-0149 の implementation_status 直下 (旧 inline 位置) に貼り戻し。
3. git diff で逆移設前後の内容と PR #2026 直前の内容を突き合わせ、欠落 0 を確認。
4. 同手順を operator_guide に追記してから revert PR を出す。

コスト試算

• メタ抽出ユーティリティ (adr_meta.mjs への extractImplDetail/stripImplDetail + 単体テスト): 約 0.5 人日。
• adr-lint 構造検査の改修 (impl_detail 節を本文外として扱うロジック + テスト + 既存 ADR 全件で false positive 0 確認): 約 0.5 人日。
• adr-index の派生ビュー化 (「Impl状況詳細」列の入力を impl_detail 節から取る + テスト + INDEX.md / adr-index.json 再生成): 約 0.5 人日。
• ADR テンプレ / operator_guide 明文化 (選択基準 100 文字超 + 段階的実装等の具体条件含む): 約 0.3 人日。
• 2 か所同期 lint 追加 (impl_detail 節があるなら implementation_status 短縮形式): 約 0.2 人日。
• 合計: 約 2 人日 + LLM コストなし (実装は main 役割で人間が書く)。

備考: PR #2026 で試行投資は済んでおり、本 ADR は機械担保化・派生ビュー化が主スコープ。実工数は試算の 1.2 倍 (2.4 人日) を上振れ警戒範囲とする。

Confirmation

• KPI 1: 半年後 (2026-12-19) 時点で impl_detail 節を使う ADR が ≥ 2 本存在する。
  • 検証手段: grep -l "<!-- impl_detail:start -->" docs/adr/*.md | wc -l
  • 実行頻度: 月次 adr-lint
  • 違反時対応: 撤退条件に従い deprecated へ
• KPI 2: adr-index の「Impl状況詳細」列が impl_detail 節を持つ ADR で正しく描画される。
  • 検証手段: CI テスト fixture + 月次目視
  • 実行頻度: CI 毎 PR + 月次
  • 違反時対応: 起案者が修正 PR
• KPI 3: adr-lint が既存 ADR (impl_detail 節なし) で false positive を出さない。
  • 検証手段: CI (全 ADR を adr-lint に通す)
  • 実行頻度: CI 毎 PR
  • 違反時対応: 即修正、できなければ deprecated
• KPI 4: ADR-0149 の adr-index 「Impl状況詳細」列が impl_detail 節の内容を反映している。
  • 検証手段: 実装後の adr-index.json 確認
  • 実行頻度: 実装完了時 1 回 + 月次
  • 違反時対応: 起案者が修正 PR
• KPI 5: operator_guide / ADR テンプレに impl_detail 節の使い方と選択基準が記載され、Jr が読んで使える。
  • 検証手段: テンプレ / operator_guide の grep + Jr ヒアリング (利用が広がってから)
  • 実行頻度: 実装完了時 + 四半期
  • 違反時対応: ドキュメント追記 PR
• KPI 6 (意味的乖離の運用カバー): implementation_status (短縮) と impl_detail 節 (詳細) の意味的整合を週次で目視確認 (impl_detail 利用 ADR が ≥1 本ある期間のみ)。
  • 検証手段: 起案者または当番が週次で impl_detail 利用 ADR を目視レビュー
  • 実行頻度: 週次
  • 違反時対応: 即時 PR で同期、3 ヶ月で月次 1 件以上継続検出なら撤退条件発動

参照 (References)

• 関連 ADR:
  • ADR-0149: refines (本 ADR は ADR-0149 の派生 SSoT 方針を impl_detail 節として具体化。逆辺 refined_by: [本 ADR] を ADR-0149 に追記)。
  • ADR-0146: refines (決定の早わかりを派生ビューへ路線の最初の本格実装。逆辺 refined_by を ADR-0146 へ追記)。
  • ADR-0032: refines (実装ライフサイクル管理。impl_detail で短縮 implementation_status と詳細の分離を明示)。
  • ADR-0137: relates_to (メタデータ frontmatter 移行。本 ADR の impl_detail は frontmatter ではなく本文 (派生)、分離の根拠を明確化。意味的乖離防止策の参考)。
• 関連 PR/Issue:
  • PR #2026: 試行起点 (本 ADR で正式化)。マーカー仕様は本 ADR が引き継ぐ。
  • PR #2020: 詳細の情報保全先 (Phase 1-2 Done / PR 一覧 / 残タスクは impl_detail 節へ移設済み)。
• 外部資料: -