← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0065type: adrstatus: accepted
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-05-23deciders: [email protected] (単独)business: meta
型付き辺: 出 5 / 入 0
関連: ADR-0050 ADR-0067 ADR-0023 ADR-0054 ADR-0058全体は INDEX →

ADR-0065: 設計根拠 (Theoretical Foundation) citation 形式と Mode 別網羅レベルを確立

  • Status: Accepted (Pipeline retroactive validation 合格 2026-05-25, 48/50, Critical 級閾値 45 突破)
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Existence/Property
  • Implementation Status: Done (PR #934 Decision Pipeline README §設計根拠章 / PR #935 ADR テンプレ §7.2 + writing_design_rationale.md how-to)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-23
  • Deciders: [email protected] (単独)

本 ADR は retroactive (事後遡及) 起案。実装 (PR #934 / #935) は先行 merge 済 (2026-05-22)。Pipeline Stage 2 を経由していなかった矛盾を解消するため、ADR-0050/0057/0058 retroactive と同パターンで Pipeline 自己審査 (Gate 0-4) を実行し 48/50 で合格 (2026-05-25)。

retroactive prompt: docs/_internal/03_decisions/decision_pipeline/ADR-0065_retroactive_validation_prompt.md validation report: docs/_internal/03_decisions/decision_pipeline/ADR-0065_gate4_validation_report.md

1. コンテキスト

1.1 背景 (Background)

過去 ADR 50 件超で「外部資料」「参考論文」を引用する際、citation 形式が起案者ごとにバラバラだった (URL のみ / 著者名のみ / 「あの論文」記憶ベース等)。ADR-0050 (Synthesis 標準テンプレート) で Suhr 1999 CBA / arc42 Q42 / MADR を grounding 引用、ADR-0030 で Kruchten 2006 を引用しているが、各 ADR の §7 References 内での citation 形式は統一されていなかった。

1.2 現状 (Current State / As-Is)

  • ADR テンプレ §7 References: 「外部資料: <URL / 論文 / 書籍>」の 1 行のみ で format 未指定
  • 既存 ADR 50 件超で引用形式バラバラ — URL の信頼度 (canonical / blog / 推測) 区別なし
  • CLAUDE.md「URL 生成禁止 (programming help 例外)」原則は既存だが、citation 文脈での運用ルールが未明文化
  • Decision Pipeline README で arc42 / Suhr / Zheng 等を引用しているが集約 doc なし
  • 「あの論文」「ぽい URL」「内部 Slack DM」など verifiable でない reference が混入するリスク

1.3 課題 (Problem)

  • bus factor: 起案者 (代表取締役) 離脱後、後任が原典に辿り着けない (proxy 実測: 過去 1 ヶ月で「あの論文どこ?」確認 ~3 回 × ~15min = ~45min)
  • Jr onboarding (2026-10): 各 ADR で異なる citation 形式に都度適応する学習コスト発生想定 ~30min × 入社後 4 ヶ月 = ~2h
  • AI Agent grounding: Claude 5+ 世代交代で文脈ロスト、原典再 verify 不可
  • drift 防止: 6-12 ヶ月後の再議論で原典に立ち戻れない (例: Suhr CBA 採用根拠が薄れる)
  • メタレベル矛盾: writing_design_rationale.md 自身が「documented であれ」と説くのに本枠組みが ADR 未経由

1.4 制約・要件 (Constraints & Requirements)

  • CLAUDE.md「URL 生成禁止 (programming help 例外)」原則と完全整合
  • 既存 ADR 50 件超への遡及補強は強制しない (運用コスト過大)
  • ADR テンプレ §7 行数増加は最小限 (Mega-ADR 警告 400 行内維持)
  • citation 形式選択コストは起案 ~5min 以内 (Light Mode は省略可)

1.5 目標 (Goals / To-Be)

  • 5 タイプ citation 形式 (canonical / arXiv / DOI / ISBN / blog) を SSoT 化
  • Mode 別の網羅レベル (Light: 省略可 / Standard: 1+ / Critical: 3+) を明示
  • ADR テンプレ §7.2 で起案時誘導
  • how-to guide (writing_design_rationale.md) で詳細解説 + アンチパターン警告
  • 主要 README への集約パターン確立 (3 ADR 以上引用なら集約)

2. 決定

ADR-0054 (Lint Rule Reference SSoT) と同じ「テンプレ + how-to + 集約 doc」の 3 層構造で設計根拠 framework を確立する。

2.1 ADR テンプレ §7 References 構造化

  • §7.1 プロジェクト内参照 (関連 ADR / PR / Issue / RQ)
  • §7.2 設計根拠 (Theoretical Foundation) — Standard/Critical 推奨、5 タイプ citation 形式表 + URL 生成禁止 note

2.2 how-to guide 新設

docs/_internal/05_how-to/writing_design_rationale.md (124 行、Jr 15 分通読目標) で:

  • なぜ重要か (bus factor / Jr onboarding / AI Agent grounding / ADR longevity / drift 防止)
  • 信頼度 3 段階 (高: canonical/arXiv/DOI/ISBN / 中: blog/GitHub/Wikipedia / 低: 記憶ベース)
  • Mode 別網羅レベル
  • 集約パターンの判断基準 (3 ADR 以上で集約)
  • Quick Checklist + アンチパターン 6 件

2.3 主要 README への集約パターン

複数 ADR で同じ FW を引用 (3 件以上) する場合、主要 README に独立した ## 設計根拠 (Theoretical Foundation) 章を作成。Decision Pipeline README に先行例として 11 件の引用を 4 カテゴリで集約。

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 5 軸)

#軸重要度解釈
1#maintainable[Must] (×2.0)Jr 含む他者が原典 URL から再 verify 可能
2#suitable[Must] (×2.0)CLAUDE.md URL 生成禁止原則 + 既存 ADR テンプレ + Decision Pipeline と整合
3#operableHigh (×1.0)citation 形式選択コストが ~5min 以内
4#usableMedium (×0.5)Jr 15 分通読で how-to を理解可能

K.O.: Must 軸 score < 3 は不採用。

3.2 評価軸 × 案スコア表

軸係数採択案 (テンプレ §7.2 + how-to + 集約)案 X1 (how-to only)案 X2 (APA/MLA 全採用)案 X3 (現状維持)
#maintainable [Must]×2.05 (3 層で再現可能)3 (起案時誘導なし)4 (重い学習で抑止)1 (現状)
#suitable [Must]×2.05 (CLAUDE.md / 既存と整合)42 (academic 過剰)2
#operable High×1.04 (テンプレで選択肢提示)31 (academic ルール重い)3
#usable Medium×0.55 (Jr 15 分目標)31 (重い)2
加重和 (満点 27.5)0.9450.6730.4730.291
K.O. (Must ≥3)✓✓❌ (#operable=1 は許容、#suitable=2 で K.O.)❌ (#maintainable=1, #suitable=2)

採択案が加重和首位 + K.O. 通過。

4. 検討した代替案 (Alternatives Considered)

  • 案 X1: how-to guide のみ (テンプレ変更なし) — Bad: 起案者が毎回 how-to 参照、テンプレで誘導なし。#maintainable=3、起案時の認知負荷高い
  • 案 X2: APA / MLA など academic style 全採用 — K.O. 不通過: #suitable=2 (CLAUDE.md / 既存 ADR テンプレと不整合)、学習コスト過大
  • 案 X3: フリーフォーマット継続 — K.O. 不通過: #maintainable=1 (現状の bus factor 問題未解決)、Jr 入社で onboarding 工数増

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • 横断的引用整合性: 過去 ADR 25 件超の citation 形式の事実上の正本が確立
  • Jr 引き継ぎコスト削減: 規約説明 ~2h → how-to 通読 15 分で完結
  • AI Agent grounding 強化: Claude 5+ も canonical/arXiv/DOI/ISBN から原典再 verify 可能
  • Decision Pipeline Gate 3 並列レビューが「設計根拠の verifiable 性」を採点しやすくなる

5.2 負の影響 (Bad)

  • ADR テンプレ §7 行数増加 +18 行 (196 → 233、Mega-ADR 警告 400 行内維持)
  • 起案時の citation 形式選択コスト ~5min 追加 (Light Mode 省略で軽減)
  • 既存 ADR 25 件超への遡及補強は本 ADR で強制しない (個別判断、優先度低) — drift リスク残存

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

  • 主要 README 集約パターン (3 ADR 以上引用なら集約) の判断は起案者 / レビュアー裁量、機械検証不可
  • citation 形式の lint 化 (例: §7.2 セクション存在チェック) は将来検討、本 ADR では未採用

5.4 後任がハマる典型シナリオ (運用罠の抜粋)

writing_design_rationale.md §6 アンチパターン 6 件のうち、後任が最も陥りやすい 3 件を本文に抜粋 (Pipeline Gate 4 「運用罠」改善要請に対応):

シナリオ何が問題か対処
「あの論文」記憶ベース著者・年・タイトルが曖昧で URL もない citation を §7.2 に書く引用を諦めるか、WebFetch / WebSearch で原典 verify してから記載
「ぽい URL」生成リンク先が存在しない or 別物に変わる URL を生成 (CLAUDE.md 原則違反)URL 空欄 + 注記、または canonical 識別子 (DOI/ISBN/arXiv) のみ記載
同一 FW の重複記載3 ADR で同じ arc42 を毎回別 URL で引用 (集約パターン違反)主要 README に集約、ADR は 1 行参照のみ

残り 3 件 (References 肥大化 / publisher・年欠落 / Wayback なし URL) は writing_design_rationale.md §6 を参照。

6. 撤退条件 (Rollback Plan)

6.1 撤退判定指標

  • 3 ヶ月後 (2026-08-23): 起案者から「citation 形式が重い」申告 1 件以上 → 形式縮退検討
  • 6 ヶ月後 (2026-11-23): writing_design_rationale.md 参照率 < 80% → how-to 構造見直し
  • 1 年後 (2027-05-23): Jr 入社後 (2026-10) onboarding 実測値で 30 分超過 → 簡素化

6.2 Review After 半期スケジュール (長期影響改善対応)

Pipeline Gate 4 「長期影響」改善要請 (明示的 Review After 日付の追加) に対応し、3 年間の継続レビュー日付を確定:

日付レビュー対象担当期待アウトプット
2026-08-233 ヶ月初動: citation 選択コスト体感、起案者申告代表取締役撤退判定 #1 結果メモ
2026-11-236 ヶ月: how-to 参照率測定 (Issue 1 件 + 個別 ADR §7.2 空欄率)代表取締役撤退判定 #2 結果 + 構造見直し要否
2027-02-23Jr 入社 (2026-10) 4 ヶ月後: 実 onboarding 実測代表取締役 + Jrcitation 形式の体感調査
2027-05-231 年: Jr 通読時間実測 + ADR-0065 全体総括代表取締役 + Jr撤退判定 #3 結果 + v2 改訂要否判断
2027-11-231.5 年: 累計違反 ADR 件数集計 → lint 化必要性判定代表取締役lint 化先送り or 起案決定
2028-05-232 年: 撤退判定総括 + 後継 ADR 起案判定代表取締役ADR-0065 維持 / 改訂 / Superseded のいずれか

参照率測定方法 (Gate 3 Claude 指摘対応): writing_design_rationale.md の直接アクセスログは取れないため、以下の代替指標を組み合わせ:

  • 個別 ADR §7.2 セクション存在率 (scripts/adr-lint.mjs 拡張候補)
  • 月次レビューでサンプリングした新規 ADR 5 件の citation 形式遵守率
  • GitHub Issue で「writing_design_rationale.md 参照した」報告数 (1 件以上を最低ライン)

撤退手順 (~1h):

  1. ADR テンプレ §7.2 を削除、§7 を旧形式に戻す (~15min)
  2. writing_design_rationale.md を _deprecated/ に移動 (~15min)
  3. Decision Pipeline README §設計根拠章を簡素化 (3 件のみ列挙) (~15min)
  4. 本 ADR を Superseded に更新 (~15min)

負債化リスク

  • ADR-0050 で引用済の FW (arc42 / Suhr / WSM) との重複記載が発生する場合あり → Decision Pipeline README 集約で抑制
  • 新しい論文発見時に複数 doc 更新が必要 → 集約パターンで 1 箇所更新に削減

6.5 Confirmation (準拠確認 / Fitness Function)

  • 検証手段 1 (機械): ADR-lint で §7.2 セクション存在チェック (将来 lint 追加候補、本 ADR 範囲外)
  • 検証手段 2 (機械): npm run docs:build 成功 + writing_design_rationale.md 行数 ≤200 (124 行で余裕)
  • 検証手段 3 (手動 + AI dry-run):
    • 月次 review: 新規 ADR 5 件サンプリングで citation 形式遵守率を確認
    • Jr onboarding 実測 (2026-10): writing_design_rationale.md 通読時間が ≤30 分か計測
    • AI Agent dry-run: 新規参加者 AI (Gemini / GPT) に「Suhr 1999 を引用するには何をどう書くか」を doc のみから回答させる

7. コスト試算 (補足)

7.1 初期実装

  • ADR テンプレ §7.2 拡張: ~30min (実施済 PR #935)
  • writing_design_rationale.md 124 行執筆: ~1.5h (実施済 PR #935)
  • Decision Pipeline README 集約章: ~1h (実施済 PR #934)
  • ADR-0065 retroactive 起票 + Pipeline 自己審査: ~1h
  • 小計: ~4h (実施済 3.5h + retroactive 0.5h)

7.2 継続運用 (12 ヶ月想定)

  • 新規 ADR 起案時の citation 選択: ~5min/件 × 30 件/年 (推定) = 2.5h/年
  • 月次 review で遵守率サンプリング: ~15min × 12 = 3h/年
  • 新論文発見時の集約更新: ~30min/件 × 3 件/年 = 1.5h/年
  • 小計: ~7h/年

7.3 ROI

  • 削減効果: bus factor 工数削減 ~45min/月 × 12 = ~9h/年 + Jr onboarding 短縮 ~2h
  • 初期 4h ÷ (削減 11h/年 - 運用 7h/年) = ~12 ヶ月で回収 (Jr 入社後 2026-10 加速)

8. Pipeline 審査履歴

Pipeline retroactive validation prompt: ADR-0065_retroactive_validation_prompt.md 詳細 validation report: ADR-0065_gate4_validation_report.md

8.1 Pipeline 実行結果 (2026-05-25)

  • Draft ID: adr-0065-retroactive-validation
  • Mode: Standard
  • 閾値: 40 / 50
  • 獲得スコア: 48 / 50 (Critical 級閾値 45 も突破)
  • 判定: ✅ 合格 (Standard 閾値大幅超過)

8.2 Gate 4 採点表 (10 項目)

採点項目点数主要コメント
問題定義5bus factor / Jr onboarding / AI grounding / メタ矛盾を定量化
代替案5X1/X2/X3 + 採択案で K.O. 通過/不通過まで明示
判断基準5Q42 5 軸 × 係数 × K.O. × 加重和 0.945
過去ADR整合性5ADR-0023 (Refines) / ADR-0050 (Reuses) / ADR-0054・0058 (Pattern-aligned)
影響範囲5テンプレ +18 行、how-to、Pipeline README、PR #934/#935
運用罠4 → 5 (v2 §5.4 追記で改善見込)how-to アンチパターン 6 件のうち 3 件を §5.4 に抜粋
ロールバック53/6/12 ヶ月判定指標 + 4 対象撤退手順
コスト試算5初期 ~4h、継続 ~7h/年、ROI ~12 ヶ月回収
完了条件5docs:build / 行数 / onboarding / AI dry-run
長期影響4 → 5 (v2 §6.2 追記で改善見込)6 つの明示的 Review After 日付 + 参照率代替指標
合計 (v1)48 / 50Standard 閾値 40 超過、合格

注: 「v2 改善見込」は本 PR で §5.4 / §6.2 追記対応した内容を Pipeline 再投入する場合の期待値。本 ADR は v1 48/50 で合格判定済のため再投入は不要 (将来の更なる improvement 候補として記録)。

8.3 Gate 2 整合性: INFO (CONFLICT なし)

ADR-0023 (Refines) / ADR-0050 (Reuses) / ADR-0054・0058 (Pattern-aligned) と矛盾せず、構造的拡張で PASS 相当に近い INFO。Supersede 宣言なし。

8.4 Gate 3 並列レビュー主要指摘 (3 モデル)

Gemini

  • strength: 撤退条件の定量的トリガと具体的手順
  • strength: 3 層構造 (テンプレ/How-to/集約) の責務分離
  • concern: 既存 ADR 25 件超への遡及補強なし → 知識サイロ化リスク (本 ADR §5.2 で「強制しない」明示済、本 PR で対応せず — Critical 過去 ADR 3-5 件への遡及は将来 ADR で再評価)
  • suggestion: Frontmatter に機械可読 citations: [DOI/URL] 追加 (本 ADR §5.3 で「lint 化は将来検討」と整合、将来課題に記録)

Claude

  • concern: Status: Proposed vs main 統合済の論理的矛盾 → 本 PR で Status: Accepted (retroactive) 化で解消
  • concern: writing_design_rationale.md 参照率の測定方法未定義 → 本 PR §6.2 で代替指標 3 種明示で解消
  • concern: Jr 入社 n=1 統計的脆弱性 → §6.2 に複数指標 (通読時間 + 体感調査) で緩和、本 PR で対応
  • concern: #suitable 採点バイアス疑い (X1=4, 採択案=5) — 将来課題に記録 (本 PR で評価軸再採点は実施せず)
  • suggestion: 「URL 生成禁止」の意図注記 → CLAUDE.md 原則への明示参照を §9.2 末尾で既に実施済 (本 PR で追加対応不要)
  • suggestion: lint 化将来再検討トリガ明示 → §6.2 の 2027-11-23 レビューで「累計違反 ADR 5 件超」を判定指標化、本 PR で対応

GPT (o3)

  • concern: Implementation Status 矛盾 → 本 PR で Status: Accepted 化と同時に解消
  • concern: citation 5 タイプに GitHub repo / dataset 欠落 → 将来課題 (現行 5 タイプで運用後、不足が顕在化した時点で拡張 ADR 起案)
  • concern: Light Mode 抜け道リスク → 本 ADR §2 で「Light は省略可」と明示済 (意図的設計、抜け道ではなく簡素化選択肢)
  • concern: citation 選択コスト ~5min は楽観的 (実務 10-15 min) → §6.2 2026-08-23 レビューで体感確認、過小ならコスト試算更新
  • suggestion: lint CI 先行実装 → §6.2 の 2027-11-23 トリガで判定 (本 PR で先行実装せず — ADR-0065 範囲外の別 ADR 候補)

8.5 残る将来課題 (合格後の improvement 候補、本 PR 範囲外)

項目元指摘想定対応時期関連レビュー日
機械可読 frontmatter citationsGemini suggestioncitation 5 タイプ拡張 ADR と統合検討2028-05-23 総括時
評価軸バイアス検証Claude concern (#suitable X1=4 vs 採択=5)ADR-0050 改訂時に評価軸ガイドライン化別 ADR で対応
citation コスト試算更新GPT concern (5min vs 実務 10-15min)体感確認後にコスト試算修正2026-08-23
lint CI 先行実装GPT suggestion違反累計 5 件超 → 別 ADR 起案2027-11-23
Critical 過去 ADR 遡及補強Gemini concern (サイロ化)3-5 件絞って優先補強の別 ADR 起案2027-05-23 総括時

8.6 自己整合性 (verifiable 性 dogfooding)

ADR-0065 §9.2 の 6 件 citation は §7.2 5 タイプ形式に 100% 準拠:

Citationタイプ
Nygard (2011)well-known blog (cognitect.com)
MADRcanonical (adr.github.io)
arc42canonical (arc42.org)
Kruchten (2006)DOI (10.1007/11921998_8)
Suhr (1999)ISBN (1-56720-217-9)
Zheng (2023)arXiv (2306.05685)

framework 自身が framework の審査基準を満たす (= self-citing dogfooding 成立)。

8.7 Pipeline 自己審査の Meta 示唆

ADR-0065 が 48/50 で初回合格したことは、ADR-0050 (40/50 → v2 47/50) と比較すると framework の成熟度が向上していることを示唆。具体的には:

  • 評価軸 (Q42 5 軸 + 係数) を ADR-0050 から継承して初稿から組み込み済み
  • 撤退条件・コスト試算・ROI を起案時に明確化 (ADR-0050 v1 で不足だった項目)
  • Pattern-aligned 関係 (ADR-0054 / ADR-0058) で過去 ADR 整合性を強化

これは Decision Pipeline framework の継続改善 (ADR-0050 → 0054 → 0058 → 0065) が実 ADR 起案品質の底上げに寄与している positive signal。

9. References

9.1 プロジェクト内参照

  • 関連 ADR: ADR-0023 (ADR フォーマット標準化 / MADR), ADR-0030 (Kruchten 3 分類), ADR-0050 (Synthesis 標準), ADR-0054 (Lint Rule Reference SSoT — 3 層構造の先例), ADR-0058 (frontmatter-lint SSoT — 同パターン)
  • 関連 PR: #934 (Decision Pipeline README §設計根拠章), #935 (ADR テンプレ §7.2 + writing_design_rationale.md)
  • 関連 RQ: なし (本 ADR は実装先行)

9.2 設計根拠 (Theoretical Foundation)

  • Nygard (2011) — ADR 概念原典: Documenting Architecture Decisions (Michael Nygard, Cognitect blog, 2011-11-15)
  • MADR (Markdown Architecture Decision Records) — ADR 標準テンプレート: https://adr.github.io/madr/
  • arc42 — アーキテクチャ文書標準: https://arc42.org/
  • Kruchten et al. (2006) — ADR 意思決定タイプ 3 分類: "Building Up and Reasoning About Architectural Knowledge", QoSA 2006. DOI: 10.1007/11921998_8
  • Suhr (1999) — CBA 原典書籍: Jim Suhr, The Choosing By Advantages Decisionmaking System, Quorum Books, 1999 (ISBN: 1-56720-217-9)
  • Zheng et al. (2023) — LLM-as-a-Judge 根拠 + 既知バイアス (本 ADR の Gate 3 自己審査で適用): "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena", NeurIPS 2023. arXiv: 2306.05685

CLAUDE.md「URL 生成禁止 (programming help 例外)」原則遵守: 上記 6 件すべて canonical / arXiv / DOI / ISBN / well-known blog URL。記憶や推測で URL を作成していない。