← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0031type: adrstatus: accepted
pagemode: Criticalkruchten: Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-05-13 19:40approved_at: 2026-05-13 19:52deciders: [email protected] (単独)business: meta
型付き辺: 出 7 / 入 1
部分修正する: ADR-0030 関連: ADR-0033 ADR-0130 ADR-0131 ADR-0133 ADR-0032 ADR-0107 前提とされる: ADR-0038全体は INDEX →

ADR-0031: 既存 ADR 本文への Kruchten Type 遡及追加を許可 — ADR-0030 §決定を部分 Supersede

  • Status: Accepted
  • Mode: Critical
  • Kruchten Type: Property
  • Scope: platform
  • Implementation Status: Done (PR #665、31 ADR Kruchten Type 遡及追加)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-13 19:40
  • 承認日時 (JST): 2026-05-13 19:52
  • Deciders: [email protected] (単独)

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

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

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

  • 文脈: ADR-0030 で Kruchten 3 分類ラベルを導入したが、§決定で既存 ADR 本文は不変とし、README 一覧表への補助索引の後付けのみとした。
  • 問題: docs サイトの個別 ADR ページに Kruchten ラベルが表示されず、確認には README への往復 (1 ADR あたり推定 30 秒) が要る。主目的「検索漏れ防止 / AKM」の半分しか機能していない。
  • 問題点と課題（直せる原因 → 発生を止めるためにやること）:
    • 「本文不変」制約のため個別ページのメタデータ欄に分類が出ない → 既存 ADR のメタデータ欄に Kruchten Type 行を遡及追加する。
    • イミュータブル原則「誤字修正のみ」で、メタデータ後付けの可否が曖昧 → 業界標準準拠のメタデータ後付けを誤字修正範疇として CLAUDE.md で明確化する。
  • 前提（解決を課題に立てない与件）:
    • ADR-0030 は完全 Supersede せず「本文不変」部分のみ上書きする (分類定義・判定ロジック・裁定ルール等は維持)。
    • イミュータブル原則本体 (CLAUDE.md L92) は維持する。
  • 決定（対応策）: Kruchten 撤回・HTML 自動注入・README 往復運用の徹底でなく、ADR-0030 §決定を部分 Supersede し、既存 ADR-0001〜0029 のメタデータ欄へ Kruchten Type 行と注記行を 1 commit で遡及追加する。
  • 目的: 個別 ADR ページから Kruchten 分類が即視可能になる (往復コスト 30 秒/ADR → 0 秒/ADR)。
  • 代償: イミュータブル原則の運用解釈拡大という認知負荷が後任に生じる。30 ファイル 1 commit で git history のノイズになる。「業界標準準拠なら後付け OK」の拡大解釈リスクが残る。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

1.1 背景 (Background)

ADR-0030 (2026-05-13 Accepted, PR #662) で Kruchten 3 分類ラベル (Existence/Property/Executive) を導入したが、§決定で「既存 ADR-0001〜0029 本文不変 (README 一覧表に補助索引として後付け、本文編集なし)」と明記。実装 PR #663 でも README 一覧表のみへの追記となった。

しかし運用開始後、docs サイトで個別 ADR ページ (例: http://localhost:8080/adr/0028-adopt-6-stage-workflow-uc-slice-dev-cd-gas-mvp.html) を開いた際に Kruchten ラベルがメタデータ欄に表示されないことが判明。README 一覧表を別タブで参照する必要があり、ADR-0030 の主目的「検索漏れ防止 / AKM」のうち「個別 ADR を開いた際の即時分類確認」が機能していない。

1.2 現状 (Current State / As-Is)

  • ADR-0030 実装後の表示状況:
    • docs/adr/templates/template.md: ✅ 新規 ADR でメタデータ欄に Kruchten Type 表示
    • docs/adr/README.md 一覧表: ✅ 既存 30 本に Kruchten 列で索引化済
    • docs/adr/00NN-*.md 個別ファイル (既存 30 本): ❌ メタデータ欄に Kruchten Type なし
    • docs/adr/00NN-*.html 個別ページ: ❌ 同上 (本文不変のため)
  • イミュータブル原則 (CLAUDE.md L92): 「Accepted 後の本文編集は誤字修正のみ」
  • ADR-0030 完了条件 #5: 「既存 ADR-0001〜0029 本文不変: git diff main..HEAD -- 'docs/adr/00[0-2][0-9]-*' → 0 byte」

1.3 課題 (Problem)

  1. 個別 ADR ページから分類が見えない: AKM 検索漏れ防止という ADR-0030 の主目的の半分しか機能していない。Jr が ADR-0028 を開いて読む際、Kruchten 分類を確認するには別途 README に戻る往復が必要 (1 ADR あたり推定 30 秒の往復コスト)
  2. イミュータブル原則の運用解釈の曖昧さ: 「誤字修正のみ」とあるが、「業界標準準拠のメタデータ後付け」は誤字相当か実質改変かが ADR で明確化されていない
  3. ADR-0030 設計の不完全性: README 補助索引のみで完結する設計は、サイトナビゲーションが現状のフラット構造 (各 ADR ページが独立) であることを考慮していなかった

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0030 を完全に Supersede せず、§決定の 「本文不変」部分のみ部分上書き (他の決定 = Kruchten 3 分類定義・判定ロジック・裁定ルール・撤退条件等は維持)
  • 遡及追加は 1 commit で一括実施し、追跡可能性を確保
  • 各 ADR の本文に「Kruchten Type は ADR-0031 で遡及追加」と注記を残し、誰がいつ追加したかを明示
  • イミュータブル原則本体 (CLAUDE.md L92) は維持。ただし「業界標準準拠のメタデータ後付け」を 誤字修正範疇 として運用解釈上明確化

1.5 目標 (Goals / To-Be)

  • 個別 ADR ページから Kruchten 分類が即視可能になる (Jr の往復コスト 30 秒/ADR → 0 秒/ADR)
  • 既存 ADR 30 本のメタデータ欄に Kruchten Type 行を 1 件ずつ追加 (README 一覧表の分類値と一致)
  • 遡及追加 commit は「docs(adr): Kruchten Type 遡及追加 (ADR-0031 準拠)」で一括
  • ADR-0030 を Status: Superseded by ADR-0031 (部分) に更新

決定

ADR-0030 の §決定のうち「既存 ADR 本文不変 (README 一覧表に補助索引として後付け、本文編集なし)」の制約を 部分 Supersede し、以下を採用:

  1. 既存 ADR-0001〜0029 のメタデータ欄に Kruchten Type 行を遡及追加: README 一覧表の Kruchten 列で既に分類済の値をそのまま本文 metadata block にコピー
  2. 追加位置: 既存メタデータ行のうち Mode の直下 (templates/template.md と同位置)
  3. 形式: - **Kruchten Type**: Existence | Property | Executive (例: - **Kruchten Type**: Existence/Property)
  4. 注記行: メタデータ直後に > Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は本 ADR §決定セクションを参照。 を 1 行追加
  5. commit メッセージ: docs(adr): Kruchten Type 遡及追加 (ADR-0031 準拠、30 ファイル一括) で 1 commit
  6. ADR-0030 の Status 更新: Superseded by ADR-0031 (部分) に変更し、§決定セクションに「2026-05-13 ADR-0031 で本文不変制約を部分上書き」追記
  7. イミュータブル原則の運用解釈明確化: CLAUDE.md L92 に「業界標準準拠のメタデータ後付け (Kruchten/Nygard 等の分類軸の遡及追加) は誤字修正範疇として許容」を追記

ADR-0030 から維持される決定

  • Kruchten 3 分類定義 (Existence/Property/Executive + ギリシャ語原語)
  • 判定チェックリスト (Q1-Q3 独立判定)
  • 複数該当時の §5.1/§5.2/§5.3 分解ルール
  • Pipeline 3 LLM ラベル不一致時の単純裁定ルール
  • 撤退条件・観測指標・Review After 計画
  • 学術用語の取り扱い (日常運用は英語 3 用語のみ)

ADR-0030 から上書きされる決定

  • 「既存 ADR-0001〜0029 本文不変」→ メタデータ欄への Kruchten Type 追加を許可
  • 「README 一覧表に補助索引として後付け」→ README 一覧表 + 本文 metadata の二重表示を採用 (整合性は ADR-0031 注記行で担保)

コスト試算

項目工数金額
29 ADR 本文への遡及追加 (sed/Edit で一括) + 注記追加1 時間0 円
ADR-0030 の Status 更新0.25 時間0 円
CLAUDE.md イミュータブル原則注記追記0.25 時間0 円
Decision Pipeline 投入 + Accepted 化 + マージ0.75 時間$3
動作確認 (個別 ADR ページで Kruchten 表示確認)0.25 時間0 円
合計約 2.5 時間約 $3 (≈ [MASKED:AMOUNT])

完了条件

  1. 既存 ADR 29 本 (0001-0029) すべてに Kruchten Type 行存在: for f in docs/adr/00[0-2][0-9]-*.md; do grep -q '^- \*\*Kruchten Type\*\*:' "$f" || echo "$f: MISSING"; done → 出力ゼロ
  2. ADR-0030 の Status が Superseded by ADR-0031 (部分) に更新: grep -E '^- \*\*Status\*\*: Superseded by ADR-0031' docs/adr/0030-*.md → match
  3. CLAUDE.md にイミュータブル原則の運用解釈追記済: grep -c "業界標準準拠のメタデータ後付け" CLAUDE.md → >= 1
  4. README 注記行が更新済: grep -c "本文 metadata の二重表示" docs/adr/README.md → >= 1
  5. 個別 ADR HTML ページで Kruchten Type が表示される: 任意の 1 ADR (例: 0028) を docs site で開いてメタデータ欄に Kruchten 行を目視確認

検討した代替案 (Alternatives Considered)

  • 案 A (採用): ADR-0030 §決定を部分 Supersede し、既存 ADR 29 本のメタデータ欄に Kruchten Type 行を遡及追加 + 注記行で追加経緯を明示。
    • Good: 個別 ADR ページから即時に分類が見える (Jr の往復コスト ゼロ)。
    • Good: README 一覧表との二重表示で整合性検証も可能。
    • Good: CLAUDE.md イミュータブル原則の運用解釈を明確化し、将来の類似議論を回避。
    • Bad: イミュータブル原則の運用解釈拡大という認知負荷が後任に発生。
    • Bad: 30 ファイルを 1 commit で編集するため git history のノイズになる。
  • 案 B: ADR-0030 を完全 Supersede し、Kruchten 採用そのものを撤回 — 不採用理由: Kruchten 採用の主目的 (AKM 検索漏れ防止) を放棄、投資 5.25 時間が無駄。
  • 案 C: ADR-0030 維持、docs-build.mjs を改修して個別 ADR HTML ページに README 一覧表から Kruchten 値を自動注入 — 不採用理由: docs-build.mjs の改修コスト (推定 3 時間) が本案 A の遡及追加コスト (1 時間) より重い。HTML 自動注入は静的サイトビルド時のみ機能し、リポジトリ内 grep では発見できない (検索利便性が中途半端)。
  • 案 D: ADR-0030 維持、個別 ADR を読む時は別タブで README を開く運用ルールを徹底 — 不採用理由: Jr 入社後の運用負担が継続 (往復コスト固定化)、AKM 検索漏れ防止の効果が半減。
  • 案 E: 既存 ADR 30 本の本文を完全に書き換え、Kruchten Type だけでなく Mode・Status・Deciders 等も統一形式に揃える — 不採用理由: イミュータブル原則を本格的に破壊する、変更範囲が ADR-0031 のスコープを大きく超える。

影響 (Consequences)

5.1 正の影響 (Good)

  • 個別 ADR ページから Kruchten 分類が即時可視化される (Jr の往復コスト 30 秒/ADR → 0 秒/ADR)
  • README 一覧表 + 本文 metadata の二重表示により整合性検証が可能になる
  • CLAUDE.md イミュータブル原則の運用解釈が明確化され、将来の類似議論 (業界標準準拠メタデータ後付け) を回避できる
  • ADR-0030 の主目的 (AKM 検索漏れ防止) の片肺機能が完全機能化される
  • 影響範囲が限定的: 既存 ADR-0001〜0029 (29 ファイル) は各 +2 行、ADR-0030 は +3 行、CLAUDE.md / README.md は各 1 行追記

5.2 負の影響 (Bad)

  • イミュータブル原則の運用解釈拡大という認知負荷が後任に発生する
  • 30 ファイルを 1 commit で編集するため git history のノイズになる (blame が ADR-0031 commit に収束)
  • 注記行「ADR-0031 で遡及追加」が ADR 一覧の視覚的ノイズになる可能性
  • 「業界標準準拠なら後付け OK」が拡大解釈され、Mode/Status 以外の任意メタデータが後付けされるリスク

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

  • 6 ヶ月後の負債化リスク:
    1. 遡及追加した Kruchten Type が後の分類体系変更時 (例: Kruchten から Nygard へ) に再度遡及編集を要求される → メタデータ欄が肥大化
    2. 「業界標準準拠なら後付け OK」が拡大解釈され、Mode/Status 以外の任意メタデータが後付けされる → ADR の改変履歴が追えなくなる
    3. 注記行「ADR-0031 で遡及追加」が ADR 一覧の視覚的ノイズになる
  • 観測指標:
    • 個別 ADR ページから Kruchten 分類確認までの所要時間: 目標 < 5 秒 (ページを開いてメタデータ欄を見るだけ)
    • 遡及追加の commit が main にマージされた後、ADR-0030/0031 の整合性 (一覧表 = 本文 metadata) を月次で検証
  • Review After:
    • 1 ヶ月後 (2026-06-13): 遡及追加後の運用感確認 (個別ページ閲覧時の有用性、注記の視覚的影響)
    • 6 ヶ月後 (2026-11-13): Jr 入社後の使用感ヒアリング、撤退条件 #2 (拡大解釈) の発火数集計

撤退条件 (Rollback Plan)

判定指標閾値判定タイミング対応revert 手順
遡及追加で本文がレンダリング崩れ1 ADR でも markdown-link-check / build エラー即時 (PR CI)該当 commit を revert + ADR-0030 の補助索引のみ運用に戻るgit revert <遡及追加 commit SHA> → push → CI 緑確認
イミュータブル原則の他用途への適用拡大要求が頻発6 ヶ月で 2 件超の「業界標準準拠なら後付け OK」議論6 ヶ月後 Review AfterADR-0032 で「業界標準後付け可」のスコープを正式定義revert 不要、新 ADR 起案で対応
個別 ADR ページの Kruchten 表示が誤分類で混乱Jr 入社後 1on1 で × 評価 2 ヶ月連続Jr 入社後月次 1on1遡及追加を revert、README 一覧表のみに戻す (ADR-0030 §決定復活)git revert <遡及追加 commit SHA> + ADR-0030 の Status を Accepted に戻す + ADR-0031 を Status: Reverted に更新

ロールバックの簡潔さ (メタ ADR の特性): 本 ADR は決定の内容自体を変えず、メタデータ表記方法のみを変更する単発 commit (30 ファイル一括 +2 行) のため、データ復旧・運用システム影響なし。git revert <commit SHA> で 1 ステップ復旧可能。

監視ポイントの自動化について (メタ ADR の特性): 単発 commit 完了型のため、ランタイム監視・CI 監視対象外。Review After (1 ヶ月後 / 6 ヶ月後) の運用感確認・誤字遡及追加の拡大解釈件数集計のみで十分。月次集計フックや GitHub Actions チェックは不要 (継続的な状態遷移がないため)。

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

  • 検証手段: scripts/adr-lint.mjs の規約チェック + 手動レビュー
  • 実行頻度: PR ごと
  • 違反時の対応: 自動 fail

参照 (References)

  • 関連 ADR: ADR-0030 (部分 Supersede 対象、Kruchten 3 分類導入元、2026-05-13 Accepted, PR #662)
  • 関連 PR/Issue: PR #663 (ADR-0030 実装、README 一覧表への Kruchten 列追加)
  • 外部資料: CLAUDE.md L92 (イミュータブル原則: 「Accepted 後の本文編集は誤字修正のみ」)、docs/adr/templates/template.md (新規 ADR メタデータ欄テンプレート)、docs/adr/README.md (Kruchten 列補助索引)