関連ADR:ADR-0126 へADR-0128 へADR-0142 へADR-0150 へ 最終更新: 2026/06/22 18:56
commonid: rq-097-adr-decision-granularity-synthe…type: researchstatus: active

RQ-097: ADR の適切な記録単位（粒度）— 3モデル調査 synthesis

調査: 2026-06-08、OpenAI o3-deep-research / Gemini deep-research / Claude managed-agent を同一プロンプトで実行。生結果は tmp/deep-research/adr-granularity/{openai,gemini,claude}_*.md（nav 非登録）。 目的: JTBD-012 のアーキ決定を DRP にかける「塊」の粒度を、確度高く定義し直すための判断基準を得る。

0. 3モデル横断の合意（高確度）

3モデルが独立して同じ結論に到達した点（＝ golden に近い確度）:

  1. 1 ADR = 1 決定（Nygard / Fowler / AWS 200+ADR 経験 / MADR が全て一致）。ただし「1決定」は抽象論。4つの発散シグナルで運用判定する: ①独立可逆性、②判断ドライバー、③ステークホルダー/承認者、④撤退条件/検証KPI。この4つが分かれたら2本に割る。
  2. 大型案件は3直交軸で分解: (A) bounded context/関心事（storage/auth/ingestion/…）× (B) 可逆性（one-way door vs two-way door）× (C) 決定フェーズ（foundational→enabling→feature）。直交積を取って枝刈り。初手は基盤(one-way door)を先に決め切る。
  3. AI レビューには小さく単一論点の ADR が経験的・理論的に優位。多論点 ADR は「lost in the middle」（中央の精度が 85-95%→76-82% に低下）と反復批評ループの in-context reward hacking（ゴールポスト現象、効果は指数的に減衰） を誘発。超過時の第一治療は要約でなく "分割"。
  4. 調査待ちの決定は ADR でなく "spike"（時間箱研究）にする。Proposed のまま放置する stub ADR は index を汚し DRP を空転させる。ADR は Definition-of-Ready（START: stakeholders/time/alternatives/requirements/template）を満たしてから書く。
  5. ADR と隣接成果物の境界は機能で引く: 要求(PRD/SR)=「何を・なぜ（前提）」/ RFC=「探索」/ ADR=「どの選択肢を・なぜ（決定＋根拠）」 / 設計仕様(EDD)=「正確にどう（スキーマ・API）」。ADR は詳細を埋め込まずリンクする。

1. 分割／統合の判定マトリクス（pre-DRP ゲート）

そのまま DRP 起案前チェックに使う。

この決定はそもそも ADR か？（significance テスト）

ECSA 2020 / Zimmermann の7基準のいずれか1つ以上を満たせば ADR: 業務価値・リスク / ステークホルダー関心 / 桁違いの品質要求 / 制御不能な外部依存 / 横断的影響 / first-of-a-kind / 過去にトラブル源。

  • ヒューリスティック: 「本番で事後にこの変更を発見したら困るか？」→ Yes なら ADR。
  • Skip（commit message / runbook / 設計仕様へ）: scope・time・risk・cost が限定的、または既存ポリシーで充足済。trivial（Tailwind vs Bootstrap）と cosmic（"クラウドネイティブにする"）の ADR を量産しない（Konishi アンチパターン）。

分割シグナル（1つでも真なら割る）

シグナル行動
Context が 1ページ / ~800語 超最長サブスレッドで 分割
独立した代替案セットが2つ以上（各々≥2案）代替案セット単位で 分割
サブ決定の可逆性コストが違う（one-way と two-way が混在）レビュー深度を変えるため 分割
主ステークホルダー/承認者が違う監査単位で 分割
検証KPI / 撤退トリガーが別々トリガー単位で 分割
決定文に「and / plus / also」or「might / probably」単一断定文に書き直す。不可なら 分割
Consequences が無関係な複数ストリームに割れる分割
ADR＋DRP プロンプトの入力が ~6,000 token 超レビュー忠実度回復のため 分割

統合シグナル（全て真なら束ねる）

同一ドライバー＆同一代替案セット／同一オーナー＆承認者／実装・撤退・supersede を常に同時／割ると中身ゼロの stub になる。

2. 設問別サマリ

  • Q1 粒度基準: 上記4発散シグナル＋significance テスト。「1文で『XでYを解決する』と要約して and が入るなら2決定」。
  • Q2 大型案件の分解: 3直交軸＋named patterns（MADR カテゴリ subfolder=ADR>20本時 / strategic-tactical-quality ティア / strangler-fig=移行1フェーズ=1ADR / typed decision-graph edges=depends_on・supersedes・conflicts_with・enables・constrains / spike→ADR エスカレーション）。過剰分割の上限: Zimmermann「AD log は100超で破綻」。総数の目安は本件規模で 10〜14本（5-15/月の枠内）。
  • Q3 ADR vs 隣接: 「10年保存が必要」=要求(SR)。「S3 Object Lock＋ハッシュチェーン台帳で保存」=ADR。「バケット命名規則・列型・OpenAPI」=設計仕様(EDD)。ADR に長い API 仕様や擬似コードが入り始めたら設計仕様へ退避のサイン。要求の再掲（代替案なし）は ADR でなく非決定。
  • Q4 AI レビュー向け粒度: 単一論点＝5回 self-consistency が同じ論点に収束＝scoped 良好のシグナル。右サイズ目安: 本文 ≤1ページ / ~1,500語 / ~2,000 token、総レビュー payload（ADR＋プロンプト＋取得した関連ADR）を model の高忠実域 ~30K token 内。改善策: ①1ファイル1決定＋front-matter に typed edges ②閉じた採点ルーブリック（自由記述「問題を探せ」でなく有限チェックリスト）③反復ループに hard stop（新規重大指摘が2連続パスで0なら凍結／3-4パス上限）。← ②③は ADR-0109 の bounded rounds と整合。
  • Q5 順序付け: foundation-first＋worst-first（one-way door を可逆コストが低いうちに先に）。typed edge で topological sort。調査待ちは spike（再評価日付つき）にして Proposed ADR を作らない。DoR（START）充足前に ADR を開かない＝ DRP 空転防止。

3. テンプレ類型（Gemini 補強）

型哲学フィールド用途
Nygard簡潔・逆ピラミッドTitle/Status/Context/Decision/Consequences基盤決定・高速チーム
MADRNygard 上位互換・却下案と pros/cons 明記＋Rejected Alternatives/Justification"なぜ不採用か"が重要な複雑案件
Y-Statement1文圧縮"In context X, facing Y, we chose Z over A, to achieve B, accepting C"軽量・高頻度ログ

4. JTBD-012 への含意（プラン D1〜D9 の補正）

調査は本プランの方向（1論点=1ドラフト・基盤先行・RQ=spike 前提）を強く追認。加えて以下の補正を示唆:

  1. 真実性/改ざん耐性（電帳法③・D7）は foundational one-way door。監査証跡フォーマットを固定するため、storage(D2) と同じ初手層で早期決定（RQ-088 spike 完了直後）。enabling 扱いより前倒し。
  2. マルチテナンシー方式（silo / pool / bridge）は認証(D4)とは別の one-way door。現プランは D4 に同居 → 分割を推奨: 「テナント分離方式」(新 D4a, one-way) と「ID/認証 IdP＝Entra OIDC フェデレーション」(D4b, enabling, D4a 依存)。Gemini の分離マトリクス（shared-schema+RLS → silo、ティア別 hybrid）が代替案根拠。
  3. RQ-088/091/092 は "spike" として正しく機能。各 RQ に再評価日付を付け、結果が出るまで該当 ADR(D7/D9/D4a) を起案しない（DoR ゲート）。
  4. 信頼度ゲート(D8) の閾値はパラメータ＝ADR 対象外（skip）。ただし「ゼロタッチ取込で自動確定/例外バッチに分岐するアーキ構造」は ADR 価値あり。D8 は "取込オートメーション・アーキ"に絞り、閾値そのものは dev spec/設計仕様へ。triage の not-adr-worthy 回避。
  5. 総数 D1〜D9（＋D4 分割で10本）は 10〜14本ガイドの範囲内で健全。
  6. DRP 運用: 起案前に本マトリクスでセルフ分割チェック → checkTriageGate → triageOnly。ADR-0109 の hard stop＋閉じたルーブリックは本調査が裏付け。

補正反映後の塊: D1 スコープ / D2 storage / D3 compute・会計境界 / D4a テナント分離方式 / D4b 認証 IdP / D5 取込アダプタ抽象 / D6 データモデル / D7 真実性（初手層へ前倒し） / D8 取込オートメーション・アーキ（閾値は spec へ） / D9 保存年限。

5. 参照（主要）

  • Nygard Documenting Architecture Decisions / Fowler ADR (bliki) / adr.github.io / MADR
  • AWS Prescriptive Guidance ADR process（200+ADR 経験・single decision・readout 1-3回）
  • Microsoft Azure WAF Maintain an ADR（phase 別に分割／decision vs design guide）
  • Zimmermann: Definition of Ready(START) / Definition of Done / ADR Creation / prioritization heuristics
  • Chen & Babar Characterizing ASR / ECSA 2020 significance 7基準
  • Nilus Architecture Decision Dependencies（typed edges）/ Konishi（trivial+cosmic アンチパターン）
  • Pan et al. Feedback Loops Drive In-Context Reward Hacking(arXiv 2402.06627) / Palavalli et al.(arXiv 2411.19043 指数的減衰) / lost-in-the-middle 各種
  • 完全な URL 一覧は各生結果 tmp/deep-research/adr-granularity/claude_*.md の References 節