型付き辺: 出 10 / 入 1
ADR-0030: ADR テンプレートに Kruchten 3 分類ラベル (Existence / Property / Executive) を追加 — AKM 検索漏れ防止
- Status: Superseded by ADR-0031 (部分)
- Mode: Standard
- Kruchten Type: Property
- Scope: platform
- Implementation Status: Done (PR #663、テンプレ/README/body_generation.ts)
- 起案者: [email protected]
- 起案日時 (JST): 2026-05-13 18:59
- 承認日時 (JST): 2026-05-13 19:10
- Deciders: [email protected] (単独)
2026-05-13 部分 Supersede 通知: ADR-0031 で §決定の「既存 ADR 本文不変」制約のみが上書きされた。Kruchten 3 分類定義・判定ロジック・裁定ルール・撤退条件・観測指標は本 ADR で維持。詳細は ADR-0031 §決定セクションを参照。 Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は ADR-0031 §決定セクションおよび docs/adr/README.md の Kruchten 3 分類ガイドを参照。 Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。
決定の早わかり（Y-statement）
本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。
- 文脈: ADR が 30 本 (ADR-0000〜0029) まで蓄積し、構造の業界標準化 (ADR-0023) と番号統一 (PR #660) が完了した。次に必要なのは意思決定の主題索引化。
- 問題: 過去 ADR を主題で検索する手段が本文 grep のみで、検索漏れが起きる。過去 30 本中 4-5 件 (15-17%) が Pipeline 審査で「事前検索すれば回避できた指摘」を受けた。
- 問題点と課題（直せる原因 → 発生を止めるためにやること）:
- 主題索引がなく、起案前の関連 ADR 検索が記憶ベース (約 10%) → Kruchten 3 分類ラベルをテンプレートに追加し、grep で網羅検索できるようにする。
- 主題索引なしでは Jr が 30 本全件読み (推定 2.5-5 時間) を強いられる → README に 3 分類ガイドと判定フローチャートを置き、ラベル即視で主題把握できるようにする。
- Pipeline 3 LLM のラベル分類が不一致になりうる → 優先順位付きの裁定ルール (起案者明示 → 過半数一致 → Slack 通知で手動裁定) で 1 ラベルに決める。
- 前提（解決を課題に立てない与件）:
- 既存 Mode (Light/Standard/Critical) と直交する別軸として共存させる。
- Jr の学習コストは 30 分以内 (README ガイドで完結) とする。
- Decision Pipeline (body_generation.ts) との連携を必須とする。
- 決定（対応策）: 現状維持・Nygard 5 領域・独自タグ・検索ツール導入 (案 B〜E) でなく、Kruchten 3 分類 (Existence / Property / Executive) を ADR テンプレートのメタデータ欄に追加する (案 A)。日常運用では英語 3 用語のみ使う。
- 目的: 索引化率を 0% → 100% に、起案前の関連 ADR 検索網羅率を 10% → 100% にする。Consistency Gate 後追い差し戻し率 15-17% → 0%、Jr の主題把握時間 < 1 分/本を目指す。
- 代償: 起案者の判定時間が 1 ADR あたり 2-3 分増える。学術用語のため Jr の初期学習コスト 30 分が発生する。3 分類すべて該当する場合は影響範囲の記述が冗長になる。
- 詳細は本文の影響・撤退条件セクションを参照のこと
コンテキスト
1.1 背景 (Background)
bizlp-gas-accounting の ADR は 30 本 (ADR-0000〜0029) まで蓄積し、ADR-0023 で構造の業界標準化 (Nygard/MADR 準拠の 4 桁ハイフン形式)、PR #660 で 3 桁→4 桁の番号統一が完了した。次に必要なのは 意思決定の主題索引化。Philippe Kruchten (2004) "An Ontology of Architectural Design Decisions" の 3 分類 (Existence/Property/Executive) は学術文献で 20 年の蓄積があり、Capilla et al. (2016) "10 years of Software Architecture Knowledge Management" で「ADR の knowledge loss 防止策」の代表として位置付けられている。
1.2 現状 (Current State / As-Is)
- 総 ADR 数: 30 本 (ADR-0000〜0029)
- 主題索引化率: 0/30 (0%)
- 各 ADR は Mode (Light/Standard/Critical) フィールドのみ保有 (12/30 本、40%)、残 18/30 本は旧形式で Mode 未記載
- 「過去 ADR を主題で検索する手段」は本文 grep のみ。例: 技術選定系 ADR を網羅する単一クエリは存在しない
- 起案前に関連 ADR を本文に明記したケース: 約 3/30 本 (10%)、残 27 本は記憶ベース
1.3 課題 (Problem)
- 検索漏れによる Consistency Gate 後追い差し戻し: 過去 30 本中 4-5 件 (15-17%) が Pipeline Parallel Review / Consistency Gate / Policy Alignment で「事前検索すれば回避できた指摘」を受けた (ADR-0024/0029 等で実例あり)
- Jr 入社 (2026-10) 後の独学コスト累積: 主題索引なしで 30 本全件読み = 推定 2.5-5 時間
- 暗黙知の蒸発リスク: Capilla 2016 が指摘する "ADR-based knowledge get lost over time" が個人開発でも顕在化
1.4 制約・要件 (Constraints & Requirements)
- ADR-0001〜0029 の本文は不変 (イミュータブル原則、CLAUDE.md L92 準拠)
- 既存 Mode (Light/Standard/Critical) と直交する別軸として共存
- Jr の学習コスト ≤ 30 分 (README ガイドで完結)
- Decision Pipeline (body_generation.ts) との連携必須
1.5 目標 (Goals / To-Be)
Kruchten 3 分類を ADR テンプレートのメタデータ欄に新規追加し、各 ADR に該当する 1-3 個のラベルを付与する。これにより:
- 索引化率を 0% → 100% (30/30 本) に
- 起案前関連 ADR 検索の網羅率を 10% (記憶ベース) → 100% (grep ベース) に
- Consistency Gate 後追い差し戻し率を 15-17% → 0% に
- Jr の ADR 主題把握時間を 5-10 分/本 → < 1 分/本 に
決定
Philippe Kruchten (2004) ontology の 3 分類を docs/adr/templates/template.md のメタデータブロックに **Kruchten Type**: Existence | Property | Executive (複数可) フィールドとして追加する。各分類の定義:
| 分類 | ギリシャ語語源 | 意味 | bizlp 例 |
|---|---|---|---|
| Existence (Ontocrises) | onto-(存在) + krisis(判断) | 新しい要素・コンポーネント・データ構造を導入する決定 | ADR-0001 SSoT Invoice / ADR-0021 UC Slice |
| Property (Diacrises) | dia-(区別) + krisis | システム全体に適用される横断ルール・規約・制約 | ADR-0011 DTO Header-based / ADR-0017 Bank Filter |
| Executive (Pericrises) | peri-(周辺) + krisis | 技術・プラットフォーム・プロセス・組織選定 | ADR-0007 Gemini OCR / ADR-0019 LangGraph |
複数該当 (例: OAuth 採用 = Executive + Existence + Property) の場合は影響範囲セクション (5.1/5.2/5.3) で分解記述する。判定フローチャート (Q1: 新要素導入? → Existence / Q2: 横断ルール? → Property / Q3: 技術選定? → Executive) を README に配置。
学術用語の取り扱い: 日常運用では英語 3 用語 (Existence / Property / Executive) のみ使用。ギリシャ語原語 (Ontocrises / Diacrises / Pericrises) は README 解説セクション内の語源説明と外部資料リンクのみで言及し、メタデータ欄や検索クエリでは使わない (起案者の認知負荷低減)。
Pipeline 3 LLM ラベル不一致時の裁定ルール (単純化): Consistency Gate に新ノードは追加しない。代わりに以下の優先順位で 1 ラベルを自動採用:
- 起案者が input に明示した Kruchten Type があればそれを最終採用 (起案者裁量優先)
- 起案者明示なしで Pipeline body_generation が生成した場合、3 LLM (Gemini/Claude/GPT-4o) の Parallel Review で過半数 (2/3 以上) が一致したラベルを採用
- 過半数不一致 (3 LLM が全て異なるラベルを提案) の場合、起案者に Slack 通知して手動裁定を促す (Pipeline は INFO で通過させる)
既存 Mode との関係 — 直交する分類軸
| 軸 | Mode (Light/Standard/Critical) | Kruchten Type (新規) |
|---|---|---|
| 何を表現 | 規模・重要度・スコア閾値 | 主題・決定の種類 |
| 用途 | Pipeline scoring 判定 | 検索・索引・関連 ADR 発見 |
| 検索クエリ | grep "Mode.*Critical" | grep "Kruchten.*Executive" |
組み合わせで立体検索可能 (例: Critical かつ Executive な過去決定の網羅)。
実装スコープ
docs/adr/templates/template.md: メタデータブロック更新 (+4 行)docs/adr/README.md: 3 分類ガイド + 判定フローチャート + 既存 30 本一覧表に Kruchten 列追加 (+90 行)drp/src/nodes/body_generation.ts: SYSTEM_PROMPT に Kruchten ラベル必須化追記 (+5 行)- 既存 ADR-0001〜0029: 本文不変 (README 一覧表に補助索引として後付け、本文編集なし)
検討した代替案 (Alternatives Considered)
案 A【採用】Kruchten 3 分類 (Existence/Property/Executive) を ADR テンプレに新規メタデータとして追加
- Good, because 学術業界標準 (Kruchten 2004 / Capilla 2016 / ISO/IEC/IEEE 42010) で 20 年の蓄積あり
- Good, because 既存 Mode 軸と直交し立体的検索が可能
- Good, because 既存 ADR 本文不変 (イミュータブル原則準拠、README 補助索引で対応)
- Bad, because 学術用語のため後任 30 分の学習コストが必要
- Bad, because Pipeline body_generation.ts 改修 (0.5 時間) が発生
案 B【不採用】現状維持 (ラベルなし)
- Good, because 起案者の負荷増ゼロ
- Bad, because 索引化率 0% が固定化、Jr 独学コスト 2.5-5 時間が継続
- Bad, because Consistency Gate 後追い差し戻しによる年間 LLM API [MASKED:AMOUNT] 浪費が継続
案 C【不採用】Nygard 5 領域 (structure/NFR/dependencies/interfaces/construction) を採用
- Good, because AWS Prescriptive Guidance / Microsoft Azure WAF も採用の業界デファクト
- Bad, because 5 領域は対象ドメイン軸で、決定の「種類」(存在/性質/環境) を区別しない
- Bad, because 検索ユースケース (過去の技術選定網羅等) に直接対応しない
案 D【不採用】独自タグを自由記述で運用
- Good, because 軽量、bizlp 文脈に即した分類
- Bad, because 自由記述は時間経過で揺れる (tag 重複・誤記)
- Bad, because 学術背景なしで Jr が外部知識から類推できない
案 E【不採用】Backstage / adr-manager 等の検索ツール導入で代替
- Good, because ラベル付与の手作業ゼロ
- Bad, because 30 ADR 規模・個人開発には過剰投資 (RQ-041 結論)
コスト試算
| 項目 | 工数 | 金額 |
|---|---|---|
| template.md / README.md / body_generation.ts 更新 | 1.75 時間 | $0.5 |
| 既存 ADR 30 本を Kruchten 分類して README 補助索引追加 | 2 時間 | $1.5 (LLM 30 × $0.05) |
| Decision Pipeline 投入 + Accepted 化 + マージ | 1 時間 | $3 |
| 動作確認 + 検索ユースケース実走 | 0.5 時間 | $1 |
| 合計 | 5.25 時間 | $6 (≈ [MASKED:AMOUNT]) |
機会費用換算: 5.25 時間 × Jr 想定時給 [MASKED:AMOUNT]/h = [MASKED:AMOUNT] + LLM API [MASKED:AMOUNT] = [MASKED:AMOUNT] 投資
年間削減効果 (想定値・未検証: 過去 30 本実績の Pipeline ログから定量検証していない、仮定ベース):
- Consistency Gate 差し戻し削減: 年 12 件想定 (= 月 1 件、過去 30 本 / 推定 2 年運用 → 月 1.25 件と整合) × 1 件あたり 1 時間機会費用 + LLM API $4 ≈ 数万円規模 + $48 削減
- Jr 独学時間削減: 1 回のみ 2.25 時間機会費用削減
- 起案時検索時間削減: 年 24 件想定 (= 月 2 件、過去 30 本 / 推定 2 年運用 → 月 1.25 件 × 2 倍の余裕想定) × 13 分機会費用 ≈ 十万円規模 削減
- 合計: 年 十万円規模 + LLM API $48 (≒ 数千円) 削減見込み
投資回収期間: 約 3-4 ヶ月 (想定ベース、6 ヶ月後 Review After で実績検証)
想定根拠の弱点 (Policy Alignment 指摘事項 #1 への対応): 上記の「年 12 件 / 24 件想定」は Pipeline 過去ログから定量集計せず、過去 30 本の運用ペース (約 2 年) から推定した値。6 ヶ月後 Review After で「実差し戻し件数」「実起案件数」を実績集計し、本 ADR の前提を上書きする。撤退条件にも投資回収未達閾値を追加 (下記)。
影響 (Consequences)
5.1 正の影響 (Good)
- ADR 索引化率 0% → 100% で関連 ADR 検索漏れを構造的に防止
- Consistency Gate 後追い差し戻し率 15-17% → 0% でレビューサイクル短縮
- Jr 独学コスト 2.5-5 時間 → 1-2 時間 で人材立ち上げ高速化
- Pipeline の body_generation.ts に Kruchten ラベル必須化を組み込み、新規 ADR で自動付与
5.2 負の影響 (Bad)
- メタデータ 1 行増加で起案者の負荷がわずかに増 (1 ADR あたり 2-3 分の判定時間)
- 学術用語のため Jr の初期学習コスト 30 分が発生
- 1 ADR が 3 分類すべて該当する場合の影響範囲記述が冗長化
5.3 中立・トレードオフ (Neutral / Trade-offs)
- 運用上の罠:
- 「とりあえず全部該当」と書かれて形骸化 → Pipeline scoring node で 3 該当時は 5.1/5.2/5.3 全節必須化
- 起案者が 3 分類を誤分類 → README の判定フローチャートで Q1-Q3 順次判定
- Pipeline Parallel Review 3 モデル間のラベル分類不一致 → Consistency Gate に整合性チェック追加
完了条件 (定量メトリクス)
- テンプレートに Kruchten Type フィールド存在:
grep "Kruchten Type" docs/adr/templates/template.md→ match - README に 3 分類ガイド存在:
grep -cE "Ontocrises|Diacrises|Pericrises" docs/adr/README.md→ >= 3 - README 一覧表に Kruchten 列追加済 (空欄ゼロ)
- Pipeline 新規 ADR で Kruchten ラベル自動付与: 次回 ADR メタデータに Kruchten Type 行存在
- 既存 ADR-0001〜0029 本文不変:
git diff main..HEAD -- 'docs/adr/00[0-2][0-9]-*'→ 0 byte - CI markdown-link-check PASS
撤退条件 (Rollback Plan)
| 判定指標 | 閾値 | 判定タイミング | 対応 |
|---|---|---|---|
| Kruchten ラベル誤分類率 | 6 ヶ月後 50% 超 | 6 ヶ月後 Review After | ラベル必須化解除、README ガイドのみ残す |
| Jr 学習コスト評価 | 1on1 で × 評価 2 ヶ月連続 | Jr 入社後の月次 1on1 | 3 分類を Existence / Other の 2 分類に簡略化 |
| Pipeline 自動付与失敗率 | 20% 超 | 月次 Pipeline ログ集計 | 独立 Kruchten ラベリング node 分離 |
| 投資回収未達 (Policy Alignment 指摘事項 #2) | 6 ヶ月後の実回収額 < 投資額 × 0.5 (実差し戻し削減 + 実検索時間削減の合算が ¥10,000 未満) | 6 ヶ月後 Review After (2026-11-13) | 本 ADR の必須化を解除、README ガイドのみ残し任意運用へ縮退 |
| 3 LLM ラベル不一致頻発 | Pipeline ログで「過半数不一致 → 起案者裁定」が月 3 件超 | 月次 Pipeline ログ集計 | 起案者が input で必ず明示する運用に切替 (Pipeline 自動付与をオフ) |
誤分類率の測定方法 (Claude #4 指摘への対応): サンプリング方式で運用。月次で新規 ADR 3 本を起案者本人 (主観) + Pipeline LLM (客観) の 2 者で独立にラベル付け、不一致を「誤分類疑い」としてカウント。閾値判定は 3 ヶ月累計 9 本のうち不一致が 5 本 (≈ 50%) 超で発火。単独 Decider 体制の限界として「自己採点による過小評価リスク」は受容し、6 ヶ月後 Review After で Jr 入社後の第三者検証 (Jr が独立に分類した結果との一致率) で精度確認。
長期影響
6 ヶ月後の負債化リスク:
- Kruchten 用語日本語訳の揺れ → glossary 整備
- 既存 30 ADR 索引と本文の 2 重メンテ → back-link 自動生成検討
- 業界が他分類軸に移行した場合の移行コスト
観測指標 (月次):
- ADR 索引化率: 目標 100%
- 起案前関連 ADR 検索の到達率: 目標 100%
- Consistency Gate 差し戻し率: 目標 0%
- Jr ADR 読解時間: 目標 < 1 分/本 (ラベル即視)
Review After:
- 1 ヶ月後 (2026-06-13): 新規 ADR 1-2 本で運用感確認
- 3 ヶ月後 (2026-08-13): 過去 ADR 索引の利用率測定 (検索ユースケース実走)
- 6 ヶ月後 (2026-11-13): Jr 入社後の学習コスト定性ヒアリング
Confirmation (準拠確認 / Fitness Function)
本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。
- 検証手段: scripts/adr-lint.mjs の規約チェック + 手動レビュー
- 実行頻度: PR ごと
- 違反時の対応: 自動 fail
参照 (References)
- 関連 ADR: ADR-0023 (構造業界標準化 Nygard/MADR 準拠), ADR-0024 (§1.1-1.5/§5.1-5.3 サブ見出し正式採用), ADR-0029 (Consistency Gate 実例), ADR-0001 (SSoT Invoice - Existence 例), ADR-0007 (Gemini OCR - Executive 例), ADR-0011 (DTO Header-based - Property 例), ADR-0017 (Bank Filter - Property 例), ADR-0019 (LangGraph - Executive 例), ADR-0021 (UC Slice - Existence 例)
- 関連 PR/Issue: PR #660 (3 桁→4 桁番号統一), RQ-041 (検索ツール導入評価)
- 外部資料:
- Philippe Kruchten (2004) "An Ontology of Architectural Design Decisions"
- Capilla et al. (2016) "10 years of Software Architecture Knowledge Management: Practice and Future"
- ISO/IEC/IEEE 42010
- CLAUDE.md L92 (イミュータブル原則)