← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0036type: adrstatus: accepted
pagemode: Standardkruchten: Propertyscope: platformimplementation_status: Not Startedproposed_at: 2026-05-14 01:56approved_at: 2026-05-14 02:05deciders: [email protected] (単独)business: meta
型付き辺: 出 10 / 入 2
関連: ADR-0011 ADR-0019 ADR-0023 ADR-0029 ADR-0041 ADR-0049 ADR-0056 ADR-0039 ADR-0054 ADR-0099 部分修正された: ADR-0091 宿題回答された: ADR-0038全体は INDEX →

ADR-0036: ADR テンプレに Confirmation セクション追加 — 決定の遵守を fitness function で自動検証

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Property
  • Scope: platform
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-14 01:56
  • 承認日時 (JST): 2026-05-14 02:05
  • Deciders: [email protected] (単独)

決定の早わかり（Y-statement）

本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

  • 文脈: bizlp には ADR が 36 本あり、scripts/adr-lint.mjs や Pipeline Gate 2 など個別の検証メカニズムは存在する。
  • 問題: 決定が Accepted 後も守られているかを確認する手段が散逸している (Confirmation 相当の記述は 0/36 本)。遵守確認に 1 ADR あたり 3-5 分の探索を要し、違反しても気付けない形骸化リスクが累積する。
  • 問題点と課題（直せる原因 → 発生を止めるためにやること）:
    • 継続的遵守の検証手段が ADR 本文に書かれていない → テンプレに ## Confirmation セクション (検証手段 / 実行頻度 / 違反時の対応) を必須追加する。
    • どの ADR が何の CI で守られているかが暗黙 → 既存 36 ADR に検証手段マッピングルールで遡及追加する。
    • 新規 ADR で記述が漏れうる → Pipeline body_generation.ts の SYSTEM_PROMPT で自動付与する。
  • 前提（解決を課題に立てない与件）:
    • 既存 ADR の本文は不変 (イミュータブル原則)。ただし ADR-0031 の運用解釈拡張で遡及追加は許容範囲。
    • 既存検証メカニズムを最大活用し、新規検証ツールは作らない。
    • 単一 ADR への適用コストは 5 分以内に抑える。
  • 決定（対応策）: 現状維持 (案 B) や新規 ADR のみ必須化 (案 C) でなく、テンプレ追加 + 既存 36 ADR への遡及追加 (案 A) を選ぶ。
  • 目的: 遵守確認時間を 1 ADR あたり 3-5 分から 30 秒以下にし、新規 ADR の Confirmation 記述率 100% を実現する。
  • 代償: 既存 36 ADR への遡及追加コスト約 2.5 時間と、起案時の認知負荷増を受け入れる。記述の形骸化リスクは月次サンプリングで監視する。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

1.1 背景 (Background)

RQ-043 (GPT Deep Research, 2026-05-13 取得) の調査で、MADR 4.x / GitLab 公開 ADR が共通して採用している 「Confirmation / fitness function」 概念が bizlp の既存 ADR 構造には未取り込みであることが判明した。fitness function とは、ADR の決定 (例: 「全 API は冪等」) が実装で守られているかを自動検証するメカニズム (CI ルール / ArchUnit / 静的解析 / 自動テスト / 監視メトリクス) を ADR 本文に明記する手法。

bizlp では既に scripts/adr-lint.mjs (ADR-0023) / scripts/4_review_specs_by_gemini.js (ADR-0029) / Decision Pipeline Gate 2 (ADR-0019) など個別の検証メカニズムは存在するが、「この ADR の決定をどう自動確認するか」を ADR 本文に書く構造的習慣はない。

1.2 現状 (Current State / As-Is)

bizlp の Accepted ADR を全件スキャンした結果:

  • 総 ADR 数: 36 本 (ADR-0000〜0035、ADR-0034 / ADR-0035 マージ済)
  • Confirmation 相当の自動検証記述: 0/36 本 (0%)
  • 「完了条件 (Done-done)」を grep コマンドで明示している ADR (例: ADR-0029 §完了条件、ADR-0030 §完了条件): 9 本 (26%、本日マージ済 ADR-0028 以降)
  • しかし完了条件は 起案時の一回限り の検証であり、Accepted 後の 継続的な遵守確認 (例: 6 ヶ月後に ADR-0011 が守られているか) は構造的に未保証
  • 既存自動検証メカニズムは各 ADR と直結しておらず、「どの ADR が何の CI で守られているか」のマッピングが暗黙

1.3 課題 (Problem)

  1. 継続的遵守の検証不在: ADR Accepted 後 6 ヶ月経過時点で「ADR-0011 (DTO Header-based 列参照) は守られているか?」を確認する手段が散逸。本日のような Pipeline 改修や ADR 起案ラッシュで決定数が増えると、各決定の遵守確認手段の把握コストが累積
  2. Jr 入社後の独学コスト: Jr が 36 ADR を読む際、「決定内容」は読めても「どう守られているか」は別途コード/CI/ドキュメントを横断して探索する必要 (1 ADR あたり推定 3-5 分の探索)
  3. 形骸化リスク: ADR を読んでも自動検証がないため、実装で違反しても気付けないケースが累積する可能性。本日 ADR-0029 で scripts/adr-lint.mjs の規範参照を追加したが、ADR 本文側に検証手段が書かれていないので逆方向の trace 不能
  4. RQ-043 GPT DR の主要発見: 業界標準 (MADR 4.x / GitLab) は本セクションを採用済で、bizlp が未取り込みなのは構造的な欠落

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0001〜0035 の本文は不変 (イミュータブル原則)、ただし ADR-0031 で運用解釈拡張済 (業界標準準拠のメタデータ後付けは誤字修正範疇) → Confirmation セクション遡及追加は許容範囲
  • 新規 ADR は Decision Pipeline body_generation.ts で SYSTEM_PROMPT から自動付与
  • fitness function の記述形式は「自動検証可能 (CI/lint/test) を最優先、それが不可なら手動レビューチェックリスト」
  • 単一 ADR への適用コスト ≤ 5 分 (起案時の認知負荷を抑える)
  • 既存検証メカニズム (scripts/adr-lint.mjs / scripts/4_review / Pipeline Gate 2 / 手動 QA) を最大活用、新規検証ツールは作らない

1.5 目標 (Goals / To-Be)

  • ADR テンプレに ## Confirmation セクション追加、各 ADR で fitness function を明記必須化
  • 新規 ADR の Confirmation 記述率: 100% (Pipeline body_generation で自動付与)
  • 既存 36 ADR への遡及追加: ADR-0031 パターン (本文に Confirmation セクション追加 + 注記行) で 80% 以上カバー (実装不要なメタ ADR 等は除外)
  • 6 ヶ月後の遵守確認時間: 1 ADR あたり 3-5 分 → 30 秒以下 (Confirmation セクションを読むだけ)

決定

ADR テンプレ (docs/adr/templates/template.md) の §撤退条件 と §参照 の間に ## Confirmation セクション を新規追加し、3 要素 (検証手段 / 実行頻度 / 違反時の対応) で fitness function を必須記述化する。Decision Pipeline body_generation.ts の SYSTEM_PROMPT に Confirmation 必須化を追記し、新規 ADR に自動付与。既存 36 ADR (ADR-0000〜0035) には ADR-0031 パターン (メタデータ後付け = 誤字修正範疇) で Python 一括スクリプトにより Confirmation セクション + 注記行を遡及追加し、検証手段は §2.3 のマッピングルール (列参照系→scripts/adr-lint.mjs、Pipeline backend→Gate 2、Walking Skeleton→_RUNTIME_METRICS、純ドキュメント→N/A 等) で自動判定する。既存検証メカニズム (scripts/adr-lint.mjs / scripts/4_review_specs_by_gemini.js / Pipeline Gate 2 / 手動 QA) を最大活用し新規ツールは作らない。

テンプレ追加内容

## Confirmation (準拠確認)

> **書くべきこと**: 本 ADR の決定が実装で守られていることを継続的に検証する手段 (fitness function)。CI/lint/test/手動レビュー/監視メトリクスのいずれか。
> **必須形式**: 「**検証手段**: 検証コマンド / ツール名」「**実行頻度**: PR ごと / 月次 / 起案時のみ」「**違反時の対応**: アラート / 自動 fail / 月次集計レビュー」の 3 要素。

- **検証手段**: <CI ルール名 / lint ルール名 / test 名 / 手動チェックリスト>
- **実行頻度**: <PR ごと | 月次 | 四半期 | 起案時のみ>
- **違反時の対応**: <自動 fail / Slack 通知 / 月次レビューで集計>

検証手段マッピング (既存 36 ADR 遡及用)

ADR 種別検証手段の典型
列参照・ヘッダー規約系 (ADR-0004, 0011)scripts/adr-lint.mjs + scripts/4_review_specs_by_gemini.js
メタデータ規約系 (ADR-0023, 0024, 0030, 0031, 0032)scripts/adr-lint.mjs の規約チェック + 手動レビュー
Decision Pipeline backend (ADR-0019, 0022, 0026, 0029, 0033)Pipeline Gate 2 (consistency) + LiteLLM ログ集計
Decision Pipeline frontend UI (ADR-0035)月次レビューで hidden field loaded-from-file の利用率測定 (Cloudflare Logs / Analytics Engine 集計) + 手動 QA
Walking Skeleton 関連 (ADR-0021, 0027)_RUNTIME_METRICS シート + Utils.measureRuntime_ 監視
GAS 業務ロジック系 (ADR-0001, 0014, 0015, 0017)既存テスト (testT* / test_{slice_id}_{condition})
純ドキュメント (ADR-0018, 0020)「N/A (実装不要のため継続検証対象外)」

検討した代替案 (Alternatives Considered)

  • 案 A (採用): ADR テンプレに Confirmation セクションを追加 + 既存 35 ADR に遡及付与 (ADR-0031 パターン)。

    • Good: RQ-043 GPT DR で確認済の業界標準 (MADR 4.x / GitLab) に準拠。
    • Good: 既存検証メカニズム (scripts/adr-lint.mjs / scripts/4_review / Pipeline Gate 2) を最大活用、新規ツール不要。
    • Good: 継続的遵守の構造化で 6 ヶ月後の追跡コスト削減 (年 [MASKED:AMOUNT]-164k 削減見込み)。
    • Bad: 既存 35 ADR の遡及追加コスト (約 2.5 時間)、形骸化リスク (月次サンプリングで監視)。

  • 案 B: 現状維持 (Confirmation セクションなし) — 不採用理由: 起案者負荷増ゼロな利点はあるが、6 ヶ月後の遵守確認コスト 3-5 分/ADR が継続し、Jr 入社後の独学コスト固定化。

  • 案 C: 新規 ADR のみ Confirmation 必須化、既存 35 ADR は遡及追加しない — 不採用理由: 遡及コストゼロだが、「新規 ADR は守られるが既存 ADR は不明」という非対称状態が継続、Jr のオンボーディングで既存 ADR の遵守確認が課題のまま。

  • 案 D: scripts/adr-lint.mjs に「全 ADR に Confirmation セクションがあるか」のルールを追加し、欠落 ADR を起案者が個別対応 — 不採用理由: lint で技術的に強制できるが、既存 35 ADR が初日から fail を起こす状態でスタート、起案者は新規 ADR でない既存修正に時間を取られる。

  • 案 E: adr-kit (RQ-038 で評価済) / ArchUnit など外部ツール導入で Confirmation を自動生成 — 不採用理由: RQ-038 で adr-kit は「補完ツール」位置づけで Confirmation 自動生成までは未対応。導入コスト過大 (推定 16 時間)、bizlp 規模に過剰投資。

影響 (Consequences)

5.1 正の影響 (Good)

  • 継続的遵守の構造化: 「決定はしたが実態は逸脱」を構造的に防止。6 ヶ月後の遵守確認時間が 3-5 分/ADR → 30 秒/ADR 以下に短縮
  • 業界標準準拠: MADR 4.x / GitLab 公開 ADR と同等構造に到達 (RQ-043 確認済)
  • 既存検証メカニズム活用: scripts/adr-lint.mjs / scripts/4_review_specs_by_gemini.js / Pipeline Gate 2 / _RUNTIME_METRICS を ADR 本文から逆引き可能化、新規ツール不要
  • Jr オンボーディング改善: 36 ADR の遵守確認に必要な探索コストを構造的に削減
  • 年間削減効果見込み: Jr 遵守確認時間 年 22-36 時間 ≈ [MASKED:AMOUNT]-144,000 削減 + 形骸化発覚事後修正 年 [MASKED:AMOUNT] 削減 = 合計 年 [MASKED:AMOUNT]-164,000 削減見込み (投資 約 5 時間/[MASKED:AMOUNT] に対し回収約 1.5-2 ヶ月)

5.2 負の影響 (Bad)

  • 既存 36 ADR の遡及追加コスト: ADR-0031 パターンで Python 一括処理可だが、各 ADR の検証手段マッピングは半自動 + 手動レビュー必要 (約 2.5 時間)
  • 記述の形骸化リスク: 「scripts/adr-lint.mjs」と書いておけば形式的に通る → 実検証が動いていないケースが発生し得る
  • 起案時の認知負荷増: 1 ADR あたり追加 5 分以内を目標とするが、典型ケースに該当しない新規 ADR では Confirmation 記述に時間を要する可能性
  • scripts/adr-lint.mjs の肥大化リスク: ルール追加が累積するとメンテコスト増

Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

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

  • 「N/A」許容の判断基準: ガバナンス ADR (ADR-0018, 0020) で「検証不要」と判定する基準が必要 → README に明示
  • 検証手段の重複: 同じ ADR を複数 CI で重複検証する非効率が発生し得る → 月次で重複検出
  • 形骸化監視の運用ルール: Review After で実際に lint が動いているか検証する運用ルール必要 (scripts/4_review_specs_by_gemini.js に「Confirmation 実効性チェック」観点追加で対応予定)

コスト試算

項目工数金額
template.md / README.md / body_generation.ts 更新1 時間$0.5
既存 36 ADR への Confirmation セクション + 注記行遡及追加 (Python 一括 + 手動マッピング)2.5 時間LLM API $1.5
Decision Pipeline 投入 + Accepted 化 + マージ1 時間$3
動作確認 (新規 ADR 1 件起案で Confirmation 自動付与確認)0.5 時間$1
合計約 5 時間約 $6 (≈ [MASKED:AMOUNT])

機会費用換算: 5 時間 × Jr 想定時給 [MASKED:AMOUNT]/h = [MASKED:AMOUNT] + LLM [MASKED:AMOUNT] ≈ [MASKED:AMOUNT] 投資

完了条件 (定量メトリクス)

  1. テンプレに Confirmation セクション存在: grep -c "^## Confirmation" docs/adr/templates/template.md → >= 1
  2. README に Confirmation ガイド節存在: grep -cE "fitness function|準拠確認" docs/adr/README.md → >= 2
  3. body_generation.ts に Confirmation 必須化追記: grep -c "Confirmation" drp/src/nodes/body_generation.ts → >= 1
  4. 既存 36 ADR に Confirmation セクション存在: for f in docs/adr/00[0-3][0-9]-*.md; do grep -q "^## Confirmation" "$f" || echo MISSING; done → 出力ゼロ
  5. 新規 ADR (本 ADR-0036 自身) の Pipeline 自動付与確認: 本 ADR 本文にも Confirmation セクションが含まれること (dogfooding)
  6. CI markdown-link-check PASS

撤退条件 (Rollback Plan)

判定指標閾値判定タイミング対応revert 手順
Confirmation の形骸化 (「scripts/adr-lint.mjs」と書くだけで実際の検証が動いていない)月次集計で形骸化 ADR が 30% 超月次 Review Afterscripts/4_review_specs_by_gemini.js に「Confirmation の実効性チェック」観点追加フィールド維持、検証強化のみ
起案時の認知負荷が大起案者の自己申告で「Confirmation 記述に 10 分超」が 3 ヶ月続く月次振り返り典型ケースのテンプレ集を README に追加revert 不要、ドキュメント追記のみ
既存検証メカニズムが追いつかない新規 ADR で「該当する検証手段なし」が月 3 件超月次集計scripts/adr-lint.mjs にルール追加 or 手動レビューチェックリスト許容フィールド維持、運用緩和
Jr 入社後「Confirmation セクションが重い」フィードバック1on1 で × 評価が 2 ヶ月連続Jr 入社後月次 1on1必須化解除、推奨化に縮退 (Light Mode は省略可)テンプレ §Confirmation を「(任意)」表記に変更、Pipeline SYSTEM_PROMPT も任意化

Review After

  • 1 ヶ月後 (2026-06-13): 新規 ADR 1-2 本で Confirmation の運用感確認
  • 3 ヶ月後 (2026-08-13): 形骸化率測定、scripts/adr-lint.mjs 拡張要否判定
  • 6 ヶ月後 (2026-11-13): Jr 入社後の運用感、業界標準 (adr-kit / ArchUnit) への移行検討

観測指標 (月次)

  • 新規 ADR の Confirmation 記述率: 目標 100%
  • 既存 36 ADR の Confirmation 遡及完了率: 目標 80% 以上 (実装不要 ADR は除外)
  • Confirmation 形骸化率 (実検証なし): 目標 10% 以下
  • Jr の ADR 遵守確認時間: 目標 < 30 秒/件 (現状 3-5 分)

Confirmation (準拠確認)

  • 検証手段:
    1. grep -c "^## Confirmation" docs/adr/templates/template.md → >= 1 (テンプレ取り込み確認)
    2. for f in docs/adr/00[0-3][0-9]-*.md; do grep -q "^## Confirmation" "$f" || echo MISSING; done → 出力ゼロ (既存 36 ADR 遡及完了確認)
    3. grep -c "Confirmation" drp/src/nodes/body_generation.ts → >= 1 (Pipeline 自動付与確認)
    4. scripts/adr-lint.mjs に「全 Accepted ADR に ## Confirmation セクションが存在するか」のルール追加 (実装後)
    5. scripts/4_review_specs_by_gemini.js に「Confirmation 実効性チェック」観点追加 (月次サンプリングで形骸化検出)
  • 実行頻度: PR ごと (1-3, lint ルール) + 月次 (4, 形骸化率サンプリング)
  • 違反時の対応: lint fail で PR ブロック (1-4) / 月次集計で形骸化率 30% 超なら scripts/4_review_specs_by_gemini.js の観点強化 (Rollback 判定指標と連動)

参照 (References)

  • 関連 ADR:
    • ADR-0019 (Decision Pipeline Gate 2): Confirmation 検証手段の主要候補
    • ADR-0023 (scripts/adr-lint.mjs): Confirmation 検証手段の主要候補
    • ADR-0029 (scripts/4_review_specs_by_gemini.js): Confirmation 形骸化チェック観点追加先
    • ADR-0031: メタデータ後付け = 誤字修正範疇の運用解釈拡張 (本 ADR の遡及追加根拠)
    • ADR-0024 / ADR-0030 / ADR-0032: メタデータ規約系 ADR (遡及追加対象)
    • ADR-0021 / ADR-0027: Walking Skeleton 関連 (遡及追加対象、_RUNTIME_METRICS で検証)
    • ADR-0011: DTO Header-based 列参照 (継続遵守確認の典型例として本文で言及)
  • 関連 PR/Issue:
    • RQ-043 (GPT Deep Research, 2026-05-13): MADR 4.x / GitLab の Confirmation / fitness function 業界標準調査
    • RQ-038: adr-kit 評価 (案 E 不採用根拠)
  • 外部資料:
    • MADR 4.x 公式テンプレ (Confirmation セクション)
    • GitLab 公開 ADR (fitness function 採用事例)