ADR-0062: dev-spec-lint Rule Reference SSoT 確立

• Status: Accepted
• Mode: Standard
• Scope: platform
• Kruchten Type: Existence/Property
• Implementation Status: In Progress (doc-side complete, CI 拡張 main 担当)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-22 22:34
• 承認日時 (JST): 2026-05-22 22:50 (Pipeline 通常 flow v3 49/50 通過)
• Review After: 2026-08-22 (3 ヶ月), 2026-11-22 (6 ヶ月), 2027-05-22 (1 年)
• Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景

scripts/B6_consistency_check.js (ADR-0029 起源) が dev spec 仕様書 (docs/dev/dev_*.md) に対して 5 種類の整合性チェックを実施しているが、規約 doc 集約なし。

1.2 現状 (As-Is)

• 対象: docs/dev/dev_*.md (現状 0 files、移行中) + docs/implementation/legacy-dev/ (162 files、過去資産)
• 5 チェック: (1) ADR 参照 minor / (2) slice_id critical / (3) nav 登録 critical / (4) Walking Skeleton 4 要素 minor / (5) GAS 6 分制限 minor
• 判定: GO (全 pass) / CONDITIONAL GO (minor のみ) / NO-GO (critical あり)
• 規約 doc は不在、B6_consistency_check.js のコメント + ADR-0029 本文に分散

1.3 課題

痛みの定量化 (proxy 実測 + 再評価):

• proxy 実測 (n=5): B6 は ADR-0029 採択後 5 回実行、各 ~15-20min の 5 ADR 横断読解 (ADR-0010/0019/0020/0021/0029)。実測 confirm 工数 ~1.25-1.7h/3 ヶ月 (session log proxy)

• 集計データ実体 (n=5 内訳、proxy):

  #	session 起点	round 数	工数 (min)	主な確認対象 ADR
  1	2026-04 dev_spec_template 起案検討	4	~20	ADR-0029 §5 / ADR-0010 §slice 構造
  2	2026-04 Walking Skeleton 4 要素議論	3	~15	ADR-0028 §採用方針 / ADR-0021
  3	2026-05 B6 GO/NO-GO 判定基準確認	5	~25	ADR-0029 §verdict / B6 ソースコメント
  4	2026-05 legacy-dev 162 files 扱い検討	3	~15	ADR-0045 §_internal 組織化
  5	2026-05-22 本 ADR 起案時の参照確認	4	~20	ADR-0054 + 0058 同パターン
  合計		19 rounds	~95min ≈ 1.6h	(5 ADR 横断、~19min/session)

  (上記は session log + memory 内容からの再構成、PR コメント由来ではない暫定 proxy。gh pr list --search 由来の集計は新規 dev_spec PR 発生後 = Jr 入社後 (2026-12) に置換)

• 集計手順: gh pr list --search 'B6_consistency' --state merged → review コメントから ADR 参照確認往復を count → 平均 ~5min/round × 回数

• 信頼区間: ±30% (1.05-1.95h/月)

• 再評価: Jr 入社後 2 ヶ月 (2026-12) で実測 n≥10 に置換、上記表を実測データで更新

規約改訂時の整合性:

• 5 チェックの根拠 ADR が散在 (5 ADR 横断読解)
• Walking Skeleton 4 要素の定義あいまい (ADR-0028 §採用方針 が SSoT だが運用判断は属人)
• critical/minor の境界、GO/CONDITIONAL GO/NO-GO の判定基準が暗黙
• ADR-0058 (frontmatter-lint SSoT, Accepted+実装済) との不整合 (同パターン未適用)

1.4 制約・要件

• ADR-0054 (10 節 + YAML codeblock + AST 整合性) 構造踏襲
• doc 行数 ≤500 (400 warn / 500 error)
• Walking Skeleton 4 要素は ADR-0028 SSoT 経由参照のみ (memory project_walking_skeleton_4_elements)
• B6_consistency_check.js ロジック不変、本 ADR は doc 化のみ
• 既存 adr-lint-doc-consistency.mjs (ADR-0054 + ADR-0058 Phase 2 で拡張済) との整合

1.5 目標

docs/_internal/05_how-to/dev-spec-lint_rules.md 新規作成、5 チェック + 判定基準 + Walking Skeleton 4 要素参照 + legacy-dev 扱いを 1 doc に集約。ADR-0054 + ADR-0058 同パターン で SSoT 確立。

2. 決定

ADR-0054 確立の 10 節構造 + YAML コードブロック方式踏襲。docs/_internal/05_how-to/dev-spec-lint_rules.md 新規作成。ADR-0058 (Accepted+実装済) の adr-lint-doc-consistency.mjs 拡張パターンに準拠 し、第三適用例として SSoT を確立する。

2.1 10 節構造

1. Purpose / 2. Severity Legend / 3. Category Legend / 4. Summary Table / 5. Rule Details / 6. Verdict Rules / 7. Walking Skeleton 参照 (→ ADR-0028) / 8. legacy-dev 扱い / 9. Legacy / 10. Changelog

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

id / severity (critical|minor) / category (references|slice|nav|walking-skeleton|constraints) / since / status: active / fixable: false / description / related_adrs

2.3 5 checks 一覧

2.4 実装方式 (選定)

• 採用: 既存 adr-lint-doc-consistency.mjs 拡張 (ADR-0058 Phase 2 同パターン、3 way 整合 CI)
• 不採用: 新 script 新設 (保守負荷増) / regex のみ (AST 採用、ADR-0058 で実証)

2.5 Special case 除外 (allowlist)

.adr-lint-doc-consistency-allowlist.json に dev_spec_special_cases 追加: id_pattern + skip_rules + reason。初期 ≤ 3 件、超過は ADR 再評価。

3. 判断基準 (Decision Drivers)

ADR-0050 / ADR-0054 / ADR-0058 と同 Q42 5 軸 + WSM + K.O. criterion (Suhr 1999 CBA 準拠)。

3.1 評価軸

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

3.2 評価軸 × 案スコア表

採択首位 = ADR-0054 + ADR-0058 同パターン。

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

• 採用案: ADR-0054 + ADR-0058 同パターン (第三適用例) — 実証済、保守一元化
• X1: ADR-0029 本文追記 — 不採用理由: K.O. (Immutability 違反、#maintainable=2 / #suitable=1)
• X2: docs/dev/README.md 簡素版 — 不採用理由: #maintainable=3 で加重和 0.554、採択案 1.000 に対し劣後
• X3: 何もしない — 不採用理由: K.O. (#maintainable=1、Jr 入社で属人運用崩壊)
• X4: ADR-0058 doc に統合 — 不採用理由: K.O. (frontmatter と dev-spec は別系統、scope 越境、#suitable=2)

5. 影響 (Consequences)

5.1 正の影響 (Good)

• ADR-0029 / B6 ロジックの SSoT 確立、新規 dev spec 起案者の品質ガードレール明文化
• Walking Skeleton 4 要素の定義参照を ADR-0028 に正規化 (memory project_walking_skeleton_4_elements の制度化)
• Jr 引き継ぎコスト削減 (~2h → 1 doc 通読、GO/CONDITIONAL/NO-GO 判定の解釈ブレ防止)
• ADR-0054 + ADR-0058 パターンの 第三適用例として実証性向上

5.2 負の影響 (Bad)

• 初期コスト ~6-10h (doc + CI 拡張)
• B6 改修時の doc 同期負荷
• legacy-dev 162 files 扱いの明文化で「過去 spec を変えない」運用が逆に明示化

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

影響範囲:

• 改修対象: docs/_internal/05_how-to/dev-spec-lint_rules.md 新規 (~250-350 行)、scripts/adr-lint-doc-consistency.mjs 拡張 (+50-80 行)、.adr-lint-doc-consistency-allowlist.json に dev_spec_special_cases 追加
• 検証対象: docs/dev/dev_*.md (現 0 件)、legacy-dev/ 162 files は scope 外 (§8 で明示)
• 波及: Claude Code 固有 (他 AI Agent 影響なし、CLAUDE.md §開発仕様書 1 行リンク)、CI workflow paths 拡張のみ
• Decider: 代表取締役 (単独) / レビュアー: B6 結果 + sub workspace audit / 将来 stakeholder: Jr (2026-10)

運用上の罠:

コスト試算:

• 初期実装: doc 執筆 ~4-6h + CI 拡張 ~2-4h = 6-10h、レビューバッファ +30% で 8-13h
• 継続運用 (12 ヶ月): B6 同期 1-1.5h/年 + 月次 review 3h/年 + Walking Skeleton 追加 0.5-1h/年 = **5-6h/年**
• 削減: Jr 引き継ぎ 2h (1 回) + 判断迷い回避 ~30min/件 × 月 2-3 件 = ~1-1.5h/月
• ROI: (8-13h - 2h Jr 効果) ÷ 1.25h/月 = 5-9 ヶ月で回収 (Jr 入社後加速)

6. 撤退条件 (Rollback Plan)

6.1 撤退判断指標

• 3 ヶ月後 (2026-08-22): 新規 dev_spec 0 件 → 「過剰防衛」と判断、WARN 維持 or 削除検討
• false-positive 率 > 30% (allowlist 3 件超) → revert
• adr-lint-doc-consistency.mjs 維持コストが他 rule 系の 2 倍超 → 撤退

6.2 ロールバック手順 (3 段階)

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証 1 (機械): adr-lint-doc-consistency.mjs の dev-spec rule 拡張で 3 way CI (script / doc / B6 コメント) 整合検証、毎 PR、違反時は CI FAIL で merge ブロック
• 検証 2 (機械): docs:build + 行数 ≤500 (400 warn)、毎 PR、500 超過で error
• 検証 3 (手動 + AI dry-run): Jr (2026-10) onboarding 目視 + 中間検証 2026-08-22 / 11-22 に AI dry-run、Review After 時点で起案者が確認

検証可能な完了条件

7. 過去決定との関係 + namespace 分離

8. Review After / 負債化リスク

• Review After: 2026-08-22 (3 ヶ月、新規 dev_spec 1 件以上 + B6 GO 判定安定) / 2026-11-22 (6 ヶ月、Walking Skeleton 追加要素必要性 + Jr 入社後の運用) / 2027-05-22 (1 年、legacy-dev 移行進捗 + 本 doc §8 削除判断)
• リスク 1: B6 check 増加 (5 → 10+) で Detail 肥大化 → Progressive Disclosure 分割 (閾値: check ≥ 8 or doc ≥ 400 行、ADR-0054 §X5 パターン)
• リスク 2: ADR-0028 Walking Skeleton 改訂 / legacy-dev 移行戦略変更で doc 同期負荷 + §8 全面書換
• リスク 3: lint rule 群肥大化 (frontmatter + dev-spec + prompt + adr + docs-nav の 5 系統) → 1 年後 umbrella ADR (docs-lint-suite.mjs、ADR-0057 §7.2 言及) 検討
• 将来検討事項: 真の SSoT 化 (script ← doc 動的 import) は本 ADR スコープ外、Jr 入社後 6 ヶ月で別 ADR 検討 (ADR-0058 §5.3 整合)

参照 (References)

• 関連 ADR: ADR-0010 / ADR-0019 / ADR-0020 / ADR-0021 / ADR-0028 / ADR-0029 / ADR-0050 / ADR-0054 / ADR-0057 / ADR-0058 / ADR-0059 / ADR-0060 / ADR-0061
• 関連 PR/Issue: -（要追記）
• memory: project_walking_skeleton_4_elements (§7 制度化)
• 既存 script: scripts/B6_consistency_check.js (ADR-0029 起源) / scripts/adr-lint-doc-consistency.mjs (ADR-0054 + ADR-0058 Phase 2 拡張済、本 ADR で dev-spec rule 追加)
• 既存 doc: docs/_internal/05_how-to/adr-lint_rules.md (ADR-0054 実装) / docs/_internal/05_how-to/frontmatter-lint_rules.md (ADR-0058 実装、同パターン参照モデル)
• 将来統合: docs-lint-suite.mjs umbrella (ADR-0057 §7.2)

8. 参照: Pipeline 審査履歴 (2026-05-22 実行時, 通常 flow)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v1 (176 行) は audit 未実行、v2 (306 行) は Cloudflare 100s edge timeout で 524 error 発生、v3 (175 行) に圧縮して再投入 → 49/50 で Standard 閾値 40 + Critical 閾値 45 双方クリア。ADR-0056 §8 / ADR-0058 §11 / ADR-0057 §8 / ADR-0059 §11 / ADR-0060 §8 / ADR-0061 §8 で確立した §audit history パターンの 第七適用例。デフォルトでは折りたたまれており、▶ をクリックで展開する。

Status 遷移

• v1 起案 (2026-05-22 KV 投入) → audit 未実行 (Phase 1 改善判定で v2 直接 POST)
• v2 改善版投入 → Pipeline 通常 flow で 524 Cloudflare edge timeout (Phase 1 未経験の新事象)
• v3 圧縮版投入 → 49/50 通過 → auto-PR #924 生成 (Proposed)
• 本 PR で Status: Proposed → Accepted に更新、改善余地 1 件 (§1.3 集計データ表) を同時反映