← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0058type: adrstatus: accepted
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-05-22 14:53approved_at: 2026-05-22 16:30 (Pipeline retroactive…deciders: [email protected] (単独)business: meta
型付き辺: 出 12 / 入 2
関連: ADR-0041 ADR-0060 ADR-0064 ADR-0067 ADR-0068 ADR-0039 ADR-0050 ADR-0054 ADR-0062 ADR-0063 ADR-0065 ADR-0098 部分修正された: ADR-0070 前提とされる: ADR-0123全体は INDEX →

ADR-0058: frontmatter-lint Rule Reference SSoT 確立

  • Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Existence/Property
  • Implementation Status: Done (PR #906 Phase 1: doc + nav, PR #914 Phase 2: 3 way CI + 案 a ALLOWED 拡張)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-22 14:53
  • 承認日時 (JST): 2026-05-22 16:30 (Pipeline retroactive validation 48/50 通過)
  • Deciders: [email protected] (単独)

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

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

  • 文脈: scripts/adr-lint.mjs Phase 4 が 7 ディレクトリ 78 files に frontmatter 4 rule 検証を実施している。4 rule と許容値の定義は同 script 内の直書きのみで、規約ドキュメントに集約されていない。
  • 問題: 許容値の確認に script ソース直読が必要で参照コストが高い。proxy 実測で ~45-75min (≒ ~1h) 発生し、Jr 入社時は ~2h の質問応答工数を見込む。規約改訂時の整合も崩れやすい。
  • 問題点と課題（直せる原因 → 発生を止めるためにやること）:
    • 4 rule・許容値の定義が adr-lint.mjs 内のみに存在する → docs/_internal/05_how-to/frontmatter-lint_rules.md を新規作成し、4 rule + 許容値表を 1 doc に集約する。
    • 新 type 追加時に script・ADR-0039・templates 5 ファイルの整合が崩れやすい → script / doc / templates の 3 way 整合を CI で自動検証する。
    • ADR-0054 で確立した lint の SSoT 規約 doc 化パターンが frontmatter lint に未適用 → ADR-0054 と同じ構造を踏襲して適用する。
  • 前提（解決を課題に立てない与件）:
    • 既存 ADR-0039 / ADR-0054 と整合する 10 節構造 + YAML コードブロック方式とする。
    • adr-lint.mjs Phase 4 との整合性は CI で自動検証する。
    • doc 行数は 500 以下 (CI warning 400 / error 500)。
  • 決定（対応策）: 独自構造 (案 X1)・ADR-0039 本文への追記 (案 X2)・現状維持 (案 X3) でなく、ADR-0054 確立の 10 節構造 + YAML コードブロック方式を踏襲し、frontmatter-lint_rules.md を新規作成する。
  • 目的: 4 rule + 許容値表 (ALLOWED_TYPES 13 種 + ALLOWED_STATUSES 4 種) を 1 doc に集約し SSoT を確立する。Jr 引き継ぎコストを規約説明 ~1h から 1 doc 通読に削減する。
  • 代償: 初期実装コスト ~5-8h (バッファ込み 7-10h) と継続運用 4h/年。許容値の追加時は script と doc の 2 箇所更新になり、_meta/templates/ 5 ファイルとの整合点も増える。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

1. コンテキスト

1.1 背景 (Background)

scripts/adr-lint.mjs の Phase 4 (ADR-0039 §移行計画 Phase 4-b 起源) が 7 ディレクトリ配下 78 files に対して frontmatter (YAML --- ブロック) の 4 rule 検証を実施しているが、規約ドキュメントとして集約されていない。

1.2 現状 (Current State / As-Is)

  • 対象 7 ディレクトリ: docs/domains/ (32) / docs/architecture/ (17) / docs/data/ (11) / docs/operations/ (10) / docs/_meta/ (6) / docs/_nav/ (2) / docs/research/ (0)
  • 4 rule (fm-missing / fm-required / fm-type-enum / fm-status-enum) の定義は scripts/adr-lint.mjs:188-220 内のみ に存在
  • 許容値 (ALLOWED_TYPES: 13 種 / ALLOWED_STATUSES: 4 種) も同 script に直書き
  • ADR-0039 本文には設計意図のみ、Rule Reference は不在

1.3 課題 (Problem)

  • 新規参加者の参照コスト:
    • proxy 実測 (2026-03〜05): ADR-0054 起案・実装期間中、frontmatter type/status の許容値を確認するために adr-lint.mjs ソース直読 + Claude session 内対話往復が 3〜5 回 × ~15min/回 = ~45-75min (≒ ~1h) 発生 (session log ベース)。
    • 予測: Jr 2026-10 入社時、上記が説明同伴で 5〜8 回発生想定 → ~2h 質問応答工数
    • 備考: 個人開発のため過去の規約改訂事故 history は N/A (proxy 値のみ)。Jr 入社前は AI Agent dry-run でしか定量測定不可。
  • 規約改訂時の整合性: 新 type 追加で adr-lint.mjs + ADR-0039 + docs/_meta/templates/*.md (5 ファイル) の整合が必要で、整合性が崩れやすい
  • ADR-0054 との不整合: ADR-0054 (Accepted 2026-05-19) で ADR 用 lint の SSoT 規約 doc 化を確立したが、frontmatter lint は同パターン未適用

1.4 制約・要件 (Constraints & Requirements)

  • 既存 ADR-0039 / ADR-0054 と整合する 10 節構造 + YAML コードブロック方式 (Markdown frontmatter 重複配置を回避)
  • adr-lint.mjs Phase 4 との整合性 CI 自動検証
  • doc 行数 ≤500 (CI warning 400 / error 500)

1.5 目標 (Goals / To-Be)

docs/_internal/05_how-to/frontmatter-lint_rules.md を新規作成し、4 rule + 許容値表 (ALLOWED_TYPES 13 種 + ALLOWED_STATUSES 4 種) を 1 doc に集約。ADR-0054 と同じ構造 (10 節 + YAML コードブロック + AST 整合性 CI) で SSoT 確立。

2. 決定

ADR-0054 確立の 10 節構造 + YAML コードブロック方式を踏襲 し、docs/_internal/05_how-to/frontmatter-lint_rules.md を新規作成する。

2.1 10 節構造

  1. Purpose & Scope
  2. Severity Legend
  3. Category Legend
  4. Summary Table (Discovery Layer)
  5. Validation Rules (Detail)
  6. Allowed Types Reference
  7. Allowed Statuses Reference
  8. Enforced Directories
  9. Legacy
  10. Changelog

2.2 各 rule の YAML コードブロック (8 フィールド)

id: fm-missing
severity: error
category: validation
since: 2026-XX-XX
status: active
fixable: false
description: frontmatter (---) ブロックが存在
related_adrs: [ADR-0039, ADR-0054]

2.3 各 rule の Detail

Rationale (3 文) + ❌ FAIL Example + ✅ PASS Example + References

3. 判断基準 (Decision Drivers)

ADR-0050 で確立した arc42 Q42 5 軸 + WSM + K.O. criterion を適用 (ADR-0054 に続く第三適用例)。

3.1 評価軸 (Q42 5 軸)

#軸重要度 (係数)解釈
1#maintainable[Must] (×2.0)AI Agent + 将来経営層 (Jr 2026-10 入社) が解釈・更新可能
2#suitable[Must] (×2.0)ADR-0054 確立の構造 (10 節 + YAML codeblock + AST) との整合
3#flexibleHigh (×1.0)将来 type/status 追加への耐性 (ALLOWED_TYPES 13→20 等)
4#operableHigh (×1.0)adr-lint.mjs Phase 4 との整合性 CI 自動化
5#usableMedium (×0.5)起案者・レビュアーの参照コスト

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

3.2 評価軸 × 案スコア表

軸係数採択案 (ADR-0054 構造踏襲)案 X1 frontmatter のみ別構造案 X2 ADR-0039 内に追記案 X3 何もしない
#maintainable [Must]×2.05 (ADR-0054 と同構造で学習コスト最小)3 (独自構造で学習コスト追加)2 (ADR は不変原則違反)1 (現状)
#suitable [Must]×2.05 (ADR-0054 確立規約の自然な拡張)31 (ADR Immutability 違反)1
#flexible High×1.05 (Detail/Reference 拡張可能)42 (ADR 改訂が重い)2
#operable High×1.05 (adr-lint-doc-consistency.mjs 拡張で対応)455 (現状)
#usable Medium×0.55 (Discovery / Detail 二層)33 (ADR 散逸読解)1
加重和 (満点 32.5)1.0000.6920.4610.292
K.O. 通過 (Must ≥3)✓✓❌ (#suitable=1)❌

採択案が加重和首位 + K.O. 通過 = ADR-0054 構造踏襲案。

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

  • 案 X1: frontmatter 専用の独自構造 — 不採用: ADR-0054 と異なる構造で学習コスト二重化、SSoT 統一性損失 (#maintainable=3)。
  • 案 X2: ADR-0039 本文に追記 — K.O. 不通過: 過去 ADR の本文編集は ADR Immutability 原則違反 (ADR-0054 §7 で確立)、#suitable=1。
  • 案 X3: 何もしない — K.O. 不通過: Jr 入社で属人運用崩壊、#maintainable=1。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • ADR-0039 規約の SSoT 確立、78 files 対象の品質ガードレール明文化
  • Jr 引き継ぎコスト削減 (規約説明 ~1h → 1 doc 通読で完結)
  • ADR-0054 構造の汎用性実証 (frontmatter / dev-spec / prompt と展開予定)

5.2 負の影響 (Bad)

  • 初期実装コスト ~5-8h (doc 執筆 ~3-5h + CI スクリプト拡張 ~2-3h)
  • ALLOWED_TYPES / ALLOWED_STATUSES 追加時に doc も更新必要 (2 箇所更新運用)
  • docs/_meta/templates/ 5 ファイル (current-spec / itgc / research / spec / synthesis) との整合点が増加: frontmatter-lint_rules.md の Allowed Types Reference を更新する際、templates/*.md の frontmatter 例 (id / type / status / related / legacy_id) も追随更新が必要。
    • 緩和策: §6.5 Confirmation 手段 1 で frontmatter-lint_rules.md ↔ _meta/templates/*.md の type 値整合も CI 検証対象に追加 (3 way 検証: adr-lint.mjs Phase 4 / 本 doc / templates 群)
  • (関連: PR #893 で _meta/README.md を M.01.0 として templates 群の解説ハブに移動済 — 本 ADR で SSoT 化する frontmatter 規約の入口として活用する)

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

  • adr-lint.mjs Phase 4 と doc の二重メンテ → adr-lint-doc-consistency.mjs (ADR-0054 で導入) を拡張して自動検証
  • 真の SSoT 化 (script が doc から動的 import) は本 ADR では採用せず、Review After で別 ADR として検討 (理由: 初期実装スコープ膨張回避、JSON Schema / YAML loader 設計が別検討事項)

6. 撤退条件 (Rollback Plan)

  • 3 ヶ月後 (2026-08-22): 新規 type/status 追加が発生したかと doc 構造の機能性確認
  • 6 ヶ月後 (2026-11-22): ALLOWED_TYPES 増加傾向で行数逼迫なら Progressive Disclosure 検討
  • 撤退判断の数値閾値:
    • 3 ヶ月で doc 参照ゼロ (git log + CI 整合性チェック起動回数で計測) → 撤退検討
    • 整合性 CI fail 率 > 20% (規約頻繁改訂で運用負担) → 構造見直し
  • 撤退手順:
    1. doc を _deprecated/frontmatter-lint_rules.md に移動 (~30min)
    2. adr-lint-doc-consistency.mjs の frontmatter 検証拡張部分を revert (~30min)
    3. ADR-0039 / ADR-0054 / _meta/README.md からの参照リンクを削除 (~15min)
    4. Jr 向け代替: ADR-0039 §移行計画 + adr-lint.mjs 直読ガイドを _meta/README.md に再集約 (~30min)
    5. 合計撤退コスト: ~1.5-2h

負債化リスク

  • ADR-0039 と本 doc の方針不整合発生 → CI 整合性チェック必須
  • ALLOWED_TYPES 拡張で 4→20 等になると Summary Table が長大化 (→ §10 リスク 1 参照)

6.5 Confirmation (準拠確認 / Fitness Function)

  • 検証手段 1 (機械): scripts/adr-lint-doc-consistency.mjs (ADR-0054 で実装) を拡張し、frontmatter-lint_rules.md 内 YAML コードブロックと adr-lint.mjs Phase 4 の ALLOWED_TYPES / ALLOWED_STATUSES / ENFORCED_FRONTMATTER_DIRS 整合を 3 way (script / doc / _meta/templates/) で CI 検証。実行頻度: 毎 PR (CI) / 違反時: CI fail → 起案者修正
  • 検証手段 2 (機械): npm run docs:build 成功 + 行数 ≤500 (400 warning / 500 error)。実行頻度: 毎 PR / 違反時: warning 修正 or Progressive Disclosure 分割
  • 検証手段 3 (手動 + AI dry-run):
    • 新規参加者目視テスト 1 件 (Jr 2026-10 入社時)
    • 中間検証: 2026-08-22 / 2026-11-22 時点で起案者以外の AI Agent (Claude / Gemini) に「ALLOWED_TYPES を 1 つ追加するには何をどう更新するか」を doc のみから回答させる dry-run テスト。違反時: doc 改訂

7. コスト試算 (補足)

7.1 初期実装

  • doc 執筆: ~3-5h (4 rule + 許容値表 + 10 節構造)
  • CI スクリプト拡張: ~2-3h (adr-lint-doc-consistency.mjs を frontmatter rule + 3 way 整合対応)
  • 小計: 5-8h (Standard 想定の下限)
  • レビュー / 修正バッファ +30% を加算: 7-10h (o3 改善反映)

7.2 継続運用 (12 ヶ月想定)

  • 新 type/status 追加時: ~30min/件 (YAML 表 + Confirmation 例 + _meta/templates/*.md 同期)
    • 想定発生: 3-4 件/年 → 2h/年
  • 四半期 Review After doc レビュー: ~30min × 4 = 2h/年
  • 小計: 4h/年

7.3 ROI (改定: 保守側に下方修正)

  • 削減: Jr 引き継ぎ 2h (1 回) + 規約改訂事故回避 ~30min/月 (元 1h/月 から保守的に下方修正)
    • 下方修正根拠: 元 1h/月 は希望的観測 (Claude reviewer 指摘)。個人開発で実 history が N/A なため、proxy 実測 (1h を 3 ヶ月 = ~20min/月 相当) に「規約改訂事故回避が proxy 実測の 1.5 倍程度発生する」想定で **30min/月** に保守側調整 (proxy 1.5×)。
  • 回収: (7-10h - 2h) ÷ 0.5h/月 = 10-16 ヶ月

8. 検証可能な完了条件 (補足)

  • docs/_internal/05_how-to/frontmatter-lint_rules.md が 10 節 + 4 rule + 許容値 2 表で完成 (≤500 行)
  • 各 rule に YAML コードブロック 8 フィールド存在 (AST 抽出可能)
  • scripts/adr-lint-doc-consistency.mjs で ALLOWED_TYPES / ALLOWED_STATUSES / _meta/templates/*.md type 値の 3 way 整合確認
  • docs/_config.json nav 登録
  • npm run docs:build 成功 + warning なし

9. 過去決定との関係

  • ADR-0039 (Refines): frontmatter 規約 (Phase 4-b で起源) の SSoT を本 doc に集約。ADR-0039 本文は 片方向参照のみ (Immutability 遵守)
  • ADR-0054 (Confirms 第三適用例): 10 節 + YAML コードブロック構造を踏襲
  • ADR-0050 (Confirms): Q42 9-tag MCDA を本 ADR §3 で適用

10. Review After / 負債化リスク

  • Review After: 2026-08-22 (3 ヶ月) / 2026-11-22 (6 ヶ月) / 2027-05-22 (1 年)
  • リスク 1: ALLOWED_TYPES 拡張で Summary Table 肥大化
    • 分割判断の数値閾値 (いずれか到達で Progressive Disclosure 検討):
      • ALLOWED_TYPES ≥ 20 種 (現 13 → +7)
      • Summary Table 行数 ≥ 30 行
      • doc 全体行数 ≥ 400 行 (CI warning 閾値と一致)
    • 分割方針: ADR-0054 Phase 2c で確立した _internal/05_how-to/<topic>/rules/<rule-id>.md パターンを踏襲 (PR #866 で実証済)
    • 判断主体: 6 ヶ月 Review After 時に起案者 + AI Agent dry-run
  • リスク 2: ADR-0054 構造が将来変更されたら本 doc も追随更新必要
  • リスク 3: 新規ディレクトリ追加 (ENFORCED_FRONTMATTER_DIRS 拡張) で doc 更新漏れリスク → §6.5 検証手段 1 の 3 way CI で検出
  • 将来検討事項 (別 ADR): doc を真の SSoT として adr-lint.mjs が動的 import する単方向化 (Gemini reviewer 提案) — 初期実装スコープ外、6 ヶ月 Review After で要否判断

参照 (References)

  • 関連 ADR: ADR-0039 (frontmatter lint Phase 4-b 起源) / ADR-0054 (10 節構造 SSoT 第二適用例) / ADR-0050 (Q42 9-tag MCDA)
  • 関連 PR/Issue: PR #893 (_meta/README.md を M.01.0 ハブ化) / PR #897 (retroactive validation prompt)
  • 関連 script: scripts/adr-lint.mjs:188-220 (ALLOWED_TYPES / ALLOWED_STATUSES 定義) / scripts/adr-lint-doc-consistency.mjs (ADR-0054 で導入)

11. 参照: Pipeline 審査履歴 (2026-05-22 実行時, Retroactive Validation)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案 (改善反映後の最終版) を retroactive validation した結果のログ (ADR-0052 retroactive mode、ADR-0056 で確立した §audit history パターンの第二適用例)。Pre-merge Stage 2 で 44/50 を受領し 4 改善を反映 → 本 retroactive で 48/50 (Standard 閾値 40/50 + Critical 閾値 45/50 双方クリア)。デフォルトでは折りたたまれており、▶ をクリックで展開する。

📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 48 / 50, +4 pt improvement) — クリックで展開

Gate 0 Triage

  • needsAdr: true / triageMode: Standard
  • 理由: 規約 SSoT 確立 + 78 files 横断的影響 + CI 整合性自動化が必要 + 可逆 (撤退 ~1.5-2h で復旧可能)

Gate 1 Socratic

  • pass: true (追加質問 0 件、改善反映済み起案 context が十分と判定)

Gate 2 Consistency: verdict PASS (自己参照検出 — 想定内)

  • ADR-0058 既存 (PR #895 merged) を Gate 2 が検出、retroactive validation モードと認識
  • ADR-0039 (Refines, 片方向参照で Immutability 遵守) / ADR-0054 (Confirms 第三適用例) / ADR-0050 (Confirms Q42) との整合性 OK
  • duplicate 警告なし (retroactive=true flag で正常認識)

Gate 3 Parallel Review

  • 3 vendor (Gemini Flash / Claude Sonnet / GPT-4o) からの詳細指摘は本 retroactive run では取得スコープ外 (Standard mode かつ既 merged のため audit history の主目的は score 改善効果の確認)
  • 主要指摘の要約: 後続 §改善余地 で記録 (2 件)

Gate 4 Scoring: 48 / 50 (改善反映後)

#採点項目点数コメント
1問題定義4対象範囲 (7 ディレクトリ/78 files)、proxy 実測 (1h)、Jr 予測 (2h) を明示。個人開発の限界を自覚的に開示する誠実さは評価できるが、proxy 実測の「複数回発生」が具体回数で示されておらず、~1h 換算の内訳 (何回 × 何分) が再現不能。
2代替案5案 X1/X2/X3 + K.O. 基準を明示し却下理由も具体。動的 import 案 (Gemini 提案) も §5.3/§10 で別 ADR 化として整理済で、考慮漏れではないと判別可能。
3判断基準5Q42 5 軸 + 係数 + K.O. 基準 + 加重和を表形式で明示。ADR-0050 適用第三例と位置付けも明確で再現可能。
4過去 ADR 整合性5ADR-0039 (Refines, 片方向参照で Immutability 遵守)、ADR-0054 (Confirms 第三適用例)、ADR-0050 (Confirms) と §9 に役割込みで明記。
5影響範囲57 ディレクトリ/78 files、templates 5 ファイル、scripts パス (行番号付)、ステークホルダー (Jr 2026-10) まで特定。3 way 整合の対象も明示。
6運用上の罠5二重メンテ、templates 整合点増加、緩和策 (3 way CI)、真の SSoT 化のスコープ外明示まで網羅。後任が監視すべき箇所が CI 自動化されている。
7ロールバック5撤退判断の数値閾値 (参照ゼロ/CI fail 率 >20%)、4 ステップ手順 + 各所要時間、合計 ~1.5-2h、Jr 向け代替手段まで明記。
8コスト試算4初期 5-8h (+30% で 7-10h)、運用 4h/年、ROI 10-16 ヶ月と数値化済。ただし ROI 計算の「事故回避 ~30min/月」の下方修正根拠 (元 1h/月との差分理由) が未明示で、保守側調整の妥当性が検証不能。
9完了条件5行数 ≤500、YAML 8 フィールド、3 way 整合、nav 登録、docs:build 成功すべて機械観測可能で曖昧さなし。
10長期的影響5Review After 3/6/12 ヶ月、リスク 3 つ、分割判断の数値閾値 (20 種/30 行/400 行)、別 ADR 化判断主体まで明示。

Pre-merge Stage 2 (44/50) との改善効果

改善項目Pre-merge 指摘反映先Retroactive score
(1) 痛みの実測値Jr 入社予測のみ、history N/A§1.3 proxy 実測 + 備考追加問題定義 4/5 (proxy 内訳追加で 5 へ向上余地、本 PR §1.3 で対応)
(2) _meta/templates/ 波及§5 で漏れ§5.2 + §6.5 で 5 ファイル + 3 way CI 明示影響範囲 5/5 (満点取得)
(3) 継続運用コスト月次未試算§7.2 で 4h/年明示、§7.3 ROI 下方修正コスト試算 4/5 (ROI 根拠追加で 5 へ向上余地、本 PR §7.3 で対応)
(4) PD 分割閾値抽象的§10 リスク 1 で 3 閾値 (20種/30行/400行)長期的影響 5/5 (満点取得)

改善効果: 44/50 → 48/50 (+4 pt)、4 改善のうち 2 件が満点取得、残り 2 件 (問題定義 / コスト試算) は本 PR で追加微修正済。

改善余地 (本 PR で反映済)

  1. §1.3 proxy 実測の「複数回発生」を具体回数に分解:
    • 本 PR で「3〜5 回 × ~15min/回 = ~45-75min (≒ ~1h)」と内訳明示。後任の再現性が向上。
  2. §7.3 ROI の「事故回避 ~30min/月」下方修正根拠を 1 行追記:
    • 本 PR で「proxy 実測 (~1h を 3 ヶ月 = ~20min/月) × 1.5 倍 ≒ ~30min/月」の換算根拠を明示。保守側調整の妥当性が検証可能に。

Status 遷移

  • Pre-merge Stage 2 (44/50) → 4 改善反映 → PR #895 merged (Status: Proposed)
  • 2026-05-22 retroactive validation (48/50, Standard 閾値 40 + Critical 閾値 45 双方クリア) → 本 PR で Status: Proposed → Accepted に更新