← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0053type: adrstatus: accepted
pagemode: Standardkruchten: Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-05-19 00:40approved_at: 2026-05-19deciders: [email protected] (単独)business: meta
型付き辺: 出 6 / 入 1
細分化する: ADR-0023 ADR-0050 関連: ADR-0049 ADR-0099 ADR-0042 ADR-0052 前提とされる: ADR-0097全体は INDEX →

ADR-0053: ADR 本文 §3 に判断基準節 (Q42 9-tag MCDA) を必須化

  • Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Property
  • Implementation Status: Done (PR #849)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-19 00:40
  • 承認日時 (JST): 2026-05-19
  • Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

ADR-0050 で確立した arc42 Q42 9-tag MCDA は Synthesis 文書 (RQ-XXX_synthesis.md) のみに適用されており、ADR 本文 (PR 内容) には反映されていない。drp/src/nodes/body_generation.ts の FALLBACK_PROMPT (ADR テンプレ) には §3「検討した代替案」のみ存在し、判断基準 (評価軸) 専用節がない。

2026-05-18〜2026-05-19 セッションで本 ADR 起案検討に至った。

1.2 現状 (Current State / As-Is)

Gate 4 scoring が「判断基準明示せよ」と要求するが書き方規約が不在のため、起案者が独自軸で書くか省略する。CLAUDE.md / docs/_internal/05_how-to/synthesis_writing_guide.md は Synthesis 専用で ADR 起案向けの規約は未整備。

1.3 課題 (Problem)

判断基準 2/5 で停滞する構造的問題が顕在化:

  • ADR-0052 (Pipeline UI retroactive mode) v1: 44/50 通過、判断基準 2/5 (軸明文化なし、却下理由から逆引きが必要との指摘)
  • adr-nav-registration-lint v1: 34/50 差し戻し、判断基準 2/5 (評価軸暗黙、優先順位が逆引き)
  • 2 件連続で同じ指摘 → ad-hoc 評価軸を書く起案者が大半になる構造

Jr 入社 (2026-10) 後に「判断基準どう書くの？」質問が頻発するリスク。

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0050 (Synthesis Q42 MCDA) と整合性を保つこと
  • ADR-0042 (Prompt Lifecycle) の FALLBACK_PROMPT + KV active pointer 二重更新パターンを踏襲
  • 既存 ADR 1〜50 の遡及対応は YAGNI で保留可能
  • Gate 4 prompt (scripts/scoring.ts) 改修は範囲外 (テンプレ側構造化に絞る)
  • Light モードの起案コスト過大化を避ける

1.5 目標 (Goals / To-Be)

drp/src/nodes/body_generation.ts の FALLBACK_PROMPT、docs/adr/_template.md、および KV SSoT (prompts/production/body-generation/prompt.md) に §3 判断基準 (Decision Drivers) 節を追加し、Standard/Critical で必須・Light で推奨化。判断基準スコア ≥4/5 を目指す。Non-Goals: Gate 4 prompt 改修、既存 ADR 遡及。

2. 決定

ADR テンプレ (body_generation.ts FALLBACK_PROMPT + docs/adr/_template.md + KV active pointer) に §3 判断基準 (Decision Drivers) 節を追加し、ADR-0050 で確立した arc42 Q42 9-tag + WSM (加重和) + K.O. criterion を ADR 本文に組み込む。Standard/Critical は必須、Light は推奨 (省略可)。既存 ADR (1〜50) は遡及せず、本 ADR 自身に自己適用する。

追加する §3 構造

## 3. 判断基準 (Decision Drivers)

ADR-0050 で確立した arc42 Q42 9 タグ + WSM (加重和) + K.O. criterion を適用する。

### 3.1 評価軸 (Q42 9 タグから 3-5 個選定)

| # | 軸 | 重要度 (係数) | 案件特有の解釈 |
|---|---|---|---|
| 1 | `#<tag>` | [Must] (×2.0) | <この案件での意味> |
| ... | ... | ... | ... |

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

### 3.2 評価軸 × 案スコア表

| 軸 | 係数 | 採択案 | 案 A | 案 B | ... |
|---|---|---|---|---|---|
| ... | ... | 0-5 | 0-5 | 0-5 | ... |
| **加重和 (正規化)** | | X.XXX | X.XXX | X.XXX | ... |
| **K.O. 通過** | | ✓/❌ | ✓/❌ | ✓/❌ | ... |

適用範囲

  • Standard / Critical モード: §3 必須 (Gate 4 で判断基準 ≥4/5 を狙う)
  • Light モード: §3 推奨 (省略可、起案者の認知負荷とトレードオフ)
  • 既存 ADR (1〜50): 遡及対応は YAGNI で保留 (撤退条件で再評価)
  • 本 ADR 自身: 適用済 (§3 を以下に明示)

3. 判断基準 (Decision Drivers) — 本 ADR 自身に適用

3.1 評価軸 (Q42 5 軸選定)

#軸重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)AI agent + 将来経営層 (Jr 2026-10 入社) が判断基準節を解釈・再現可能
2#suitable[Must] (×2.0)ADR-0050 (Q42 MCDA) との整合、Synthesis のみ適用 → ADR 本文への拡張継続性
3#operableHigh (×1.0)Gate 4 prompt 改修なしで運用化、テンプレ拡張のみで完結
4#reliableHigh (×1.0)判断基準の機械的検証可能性 (後任が同じ判定に到達できる再現性)
5#usableMedium (×0.5)起案者の習熟コスト、Light モードでの過剰負荷 vs Standard の必須化

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

3.2 評価軸 × 案スコア表

軸係数採択案 (S/C 必須 + L 推奨)案 X1 全モード必須案 X2 何もしない案 X3 Gate 4 のみ改修
#maintainable [Must]×2.05 (mode 別運用で認知負荷段階制御)4 (Light 過剰)1 (現状の 2/5 停滞継続)3 (テンプレ未対応で起案者は迷う)
#suitable [Must]×2.05 (ADR-0050 直接拡張)41 (規約断絶)4
#operable High×1.05 (テンプレ拡張のみ ~1h)55 (現状)3 (Gate 4 改修要、影響広域)
#reliable High×1.05424
#usable Medium×0.55 (mode 別運用で柔軟)2 (Light で苦痛)5 (制約なし)3
加重和 (正規化、満点 32.5)1.0000.8000.4150.692
K.O. 通過 (Must ≥3)✓✓❌ (Must 軸 1 で 2 つとも不通過)✓

加重和首位 = K.O. 通過案 = 採択案 (Standard/Critical 必須 + Light 推奨)。

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

  • 案 X1: 全モード (Light 含む) で必須化 — 不採用理由: Light モードは「内部実装の選択 (ライブラリ採用・命名規則)」など軽量 ADR 用途で、Q42 5 軸を埋めるコストが ADR 本体より重くなる本末転倒。#usable=2、#maintainable=4 で採択案より低スコア。Light の運用が重くなると ADR 起案そのものが避けられる二次リスク。
  • 案 X2: 何もしない (現状の ad-hoc 評価軸維持) — 不採用理由: 判断基準 2/5 停滞の構造問題が解消しない。Jr 入社後の質問頻発リスク、ADR-0050 Synthesis 規約との整合性断絶 (Synthesis ADR は MCDA 必須だが ADR 本文は野放し)。K.O. 不通過 (#maintainable=1, #suitable=1)。
  • 案 X3: Gate 4 prompt 改修のみ (テンプレは変更しない) — 不採用理由: scripts/scoring.ts の 3_decision_criteria に「Q42 9-tag 必須」を明記する改修だが、テンプレ側に節がないので起案者が「どこに書く？」と迷う (#maintainable=3)。また Gate 4 改修は全モード・全起案に影響するため、影響範囲が広くロールバック難 (#operable=3)。テンプレ拡張の方が局所的・段階的。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • ADR-0052 / nav-lint で発生した判断基準 2/5 停滞の構造的解消 (新規起案分に限定)
  • Synthesis 文書と ADR 本文の MCDA 規約統合 (規約の二重管理が解消)
  • Jr 引き継ぎ容易化: 「ADR 起案するときは §3 を Q42 9-tag で書く」と 1 行で説明可能
  • LLM-as-judge の再現性向上: Gate 4 が判断基準を機械的に評価しやすくなる

5.2 負の影響 (Bad)

  • Standard/Critical の起案コスト増加 (§3 を書く ~30 分追加)
  • 既存 ADR 1〜50 との format 差分が生まれる (遡及しない場合、新旧混在期間が発生)
  • body_generation.ts FALLBACK_PROMPT が肥大化 (現状 5KB → ~7KB)

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

  • Q42 9 タグの選定が起案者にとって難しい場合あり (synthesis_writing_guide.md ベースのチートシート整備が必要)
  • KV 同期 (ADR-0042) で FALLBACK_PROMPT と active pointer の二重更新を忘れるリスク → CHECKLIST 整備

6. 撤退条件 (Rollback Plan)

6.1 再評価トリガー

  • 起案者の手戻り頻度が月 5 件超 (§3 を書くのに時間がかかり差し戻しが増える):
    • 計測: gh pr list --search "label:adr-draft" --json closed,labels を月初に実行、close 後再 open / 修正 commit 数を集計
    • 5 件超を 2 ヶ月連続 → Light 推奨化を一時撤回 (Standard/Critical のみ必須に段階適用)、Light は省略可へ正式化
  • Q42 9 タグが将来 arc42 改訂 / MADR v4 等で変わる: 移行検討、本 ADR を Superseded として新規 ADR 起案
  • Gate 4 prompt の改修なしで判断基準 5/5 が安定して取れない場合 (3 件中 2 件以下):
    • Gate 4 prompt 改修を別 ADR で起案 (案 X3 を後追い実装)
  • 既存 ADR 50 件の遡及対応 needs が顕在化: 段階的に refactor PR を起案 (Critical 優先で 3 ヶ月以内に 10 件 → 半年で 50 件)

6.2 CI / テンプレ撤去手順

対象具体手順影響範囲
body_generation.ts FALLBACK_PROMPT§3 削除 (1 コミット)ADR 新規起案テンプレ
KV active pointerprompt-kv-push.mjs で旧版に戻すPipeline 実行時の prompt
docs/adr/_template.md§3 削除手動起案テンプレ
既存 §3 持ち ADR PR§3 を残したまま (後方互換)過去 ADR の整合性

6.3 Review After

  • 2026-08-19 (3 ヶ月後): サンプル起案 3 件 (Light/Standard/Critical) の Gate 4 通過率と判断基準スコアを集計、Standard 必須化の妥当性判断
  • 2026-11-19 (6 ヶ月後): 既存 ADR 50 件の遡及 needs を再評価、撤退条件発火状況確認
  • 2027-05-19 (1 年後): arc42 / MADR の規約変更チェック、Q42 9 タグの陳腐化リスク評価

6.4 コスト試算

  • body_generation.ts FALLBACK_PROMPT 改修 (§3 追加 + 生成ルールに 1 行): ~1h
  • KV active pointer 更新 (prompt-kv-push.mjs 実行): ~0.5h
  • docs/adr/_template.md 更新: ~0.5h
  • docs/_internal/05_how-to/adr_decision_drivers_guide.md 新規 (synthesis_writing_guide の ADR 版): ~2h
  • テスト (Light/Standard/Critical 各 1 件サンプル起案で Gate 4 通過確認): ~1h
  • 合計: ~5h (Standard 想定の下限)
  • 運用コスト: 起案あたり ~30 分追加 (Standard/Critical のみ)、Light は変化なし

範囲外: Gate 4 prompt (scripts/scoring.ts) の改修 — 別 ADR / 既存 ADR 1〜50 の遡及 §3 追加 — YAGNI

Confirmation (準拠確認 / Fitness Function)

  • 検証手段:
    1. scripts/adr-lint.mjs に「Standard/Critical mode の ADR は §3 判断基準 (Decision Drivers) 見出しと評価軸表・スコア表を持つこと」のチェックを追加 (機械検証)
    2. Pipeline Gate 4 (scripts/scoring.ts の 3_decision_criteria) のスコア出力を月次集計 (LLM-as-judge による継続検証)
    3. KV active pointer と FALLBACK_PROMPT の §3 構造一致を prompt-kv-diff.mjs で確認 (ADR-0042 の二重更新検証を流用)
  • 実行頻度: adr-lint は PR 単位 (CI Gate)、Gate 4 集計は月次、KV diff は KV push 時
  • 違反時の対応: adr-lint 違反 → PR ブロック (起案者が §3 追記)、Gate 4 集計で判断基準 <4/5 が 3 件中 2 件 → 撤退条件 §6.1 の Gate 4 prompt 改修トリガー発火、KV diff 不一致 → CHECKLIST に従い再同期

6.6 検証可能な完了条件

  • drp/src/nodes/body_generation.ts の FALLBACK_PROMPT に §3 構造記載
  • prompts/production/body-generation/prompt.md (KV active pointer) を同期
  • docs/adr/_template.md に §3 セクション + 記入例 (Q42 5 軸 + 評価軸 × 案スコア表)
  • docs/_internal/05_how-to/adr_decision_drivers_guide.md で記入規約・Q42 タグ別チートシート整備
  • サンプル起案 3 件 (Light/Standard/Critical 各 1) で Gate 4 通過、判断基準 ≥4/5 確認
  • 本 ADR 自身が §3 を持つ (自己適用)
  • 既存 50 ADR の format 差分を README で明記 (新旧混在期間の位置付け)

6.7 負債化リスク

  • リスク 1: Q42 9 タグが arc42 改訂 / MADR v4 で変わる → migration コスト。事前緩和: Q42 タグを docs/_internal/05_how-to/adr_decision_drivers_guide.md に閉じ込め、テンプレ側は「Q42 タグから選定」と抽象記述
  • リスク 2: 既存 ADR 1〜50 との format 差分 → 遡及範囲の判断コスト。事前緩和: 撤退条件 §6.1 で段階適用を明示
  • リスク 3: Gate 4 prompt 改修が遅れると、テンプレ拡張だけでは判断基準 4/5 止まり (5/5 取れない可能性)。事前緩和: 別 ADR で並行起案を撤退条件 §6.1 でトリガー化

参照 (References)

  • 関連 ADR:
    • ADR-0050 (Synthesis 標準テンプレート、Q42 9-tag MCDA) を Refines: Q42 MCDA を ADR 本文にも拡張適用。ADR-0050 自身は変更しない。
    • ADR-0042 (Prompt Lifecycle 管理) を Refines: body_generation FALLBACK_PROMPT + KV active pointer の二重更新パターンを踏襲。
    • ADR-0023/0024/0030/0032/0036 (ADR テンプレ系) を Refines: §3 を新規追加、既存 §1/§2/§4以降の構造は不変。
    • ADR-0049 (Scope 4 段階) — 本 ADR の Scope は platform (Decision Pipeline 全体に影響)
  • 関連 PR/Issue:
    • ADR-0052 (Pipeline UI retroactive mode) v1 = 判断基準 2/5 (起案根拠データ)
    • adr-nav-registration-lint v1 = 判断基準 2/5 (起案根拠データ)
    • ADR-0052 v2 改訂 (Q42 9-tag MCDA を ADR 起案に適用した第一実験例)
  • 外部資料: arc42 Quality Tree (Q42) / MADR (Markdown Any Decision Records) / Weighted Sum Method (WSM)