ADR-0054: bizlp Lint Rule Reference 文書構造の確立

• Status: Accepted
• Mode: Standard
• Scope: platform
• Kruchten Type: Existence/Property
• Implementation Status: Done (PR #856, #864, #865, #866, #867)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-19 00:56
• 承認日時 (JST): 2026-05-19 01:45
• Deciders: [email protected] (単独)

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

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

• 文脈: scripts/adr-lint.mjs の 11 個の Lint ルールは 7 つの ADR に分散して定義され、規約集約ドキュメントが存在しない。RQ-051 の 3 モデル並列調査と Synthesis で採択方針は確定済み。
• 問題: 「bizlp の ADR 規約」を 1 箇所で見れず、7 ADR を横断して読み解く必要がある。Jr 入社 (2026-10) で属人運用が崩壊するリスクがある。AI Agent の規約整合性チェックも甘くなる。1 ルール変更で 2-3 ADR の同時編集が必要になり、片肺更新の不整合が発生しやすい。
• 問題点と課題（直せる原因 → 発生を止めるためにやること）:
  • 規約が 7 ADR に分散し SSoT がない → 11 rule + 関連 ADR 7 件を 1 doc に集約し、ADR 規約の SSoT を確立する。
  • 規約改訂のたびに複数 ADR の同時編集が要る → doc 中心の更新に変え、関連 ADR は参照リンクのみ管理する。
• 前提（解決を課題に立てない与件）:
  • Anthropic Skill 500 行制約を遵守する。
  • adr-lint.mjs 本体の autofix 実装と過去 ADR 本文の書き換え (リンク追加のみ) は Non-Goals とする。
• 決定（対応策）: Claude 10 節構造のみ (X1) や Gemini Progressive Disclosure のみ (X2) でなく、Claude 10 節構造を基礎に Gemini Progressive Disclosure 思想で補強した bizlp informed synthesis を採用する。docs/_internal/05_how-to/adr-lint_rules.md を新規作成し、各 rule は YAML コードブロック 8 フィールド + Rationale (Ruff 3 文形式) で記述する。
• 目的: ADR 規約の SSoT を確立する。Discovery (Summary Table) と Detail (深掘り) の二層構造で目的別アクセスを実現し、新規参加者と AI Agent の参照コストを下げる。
• 代償: 初期実装コスト 13-22h。新規 rule 追加時 30-60 分/rule、既存 rule 改訂時 15-30 分/rule、6 ヶ月ごとレビュー ~1h の運用コストを受け入れる。
• 詳細は本文の影響・撤退条件セクションを参照のこと

1. コンテキスト

1.1 背景 (Background)

bizlp の scripts/adr-lint.mjs は 11 個の Lint ルールを実装するが、それぞれが 7 つの ADR (ADR-0023/0030/0032/0036/0038/0039/0049) に分散して定義されており、規約ドキュメントとして集約されていない。過去に PR #811 で adr-lint_rules.md を業界未調査で起案したが「業界 FW 照合なし」を理由に close (2026-05-17)。その後 RQ-051 (PR #812 / #818) で 3 モデル並列調査 (Gemini/Claude/GPT) を実施し、ADR-0050 (Synthesis 標準テンプレート) に基づく Synthesis で採択方針が確定した。本 ADR は RQ-051 Synthesis の決定を ADR として正式化する位置付け (ADR-0050 の Synthesis → ADR 起案フロー実証例)。

1.2 現状 (Current State / As-Is)

adr-lint.mjs の 11 ルールは ADR-0023 / 0030 / 0032 / 0036 / 0038 / 0039 / 0049 の 7 ADR に分散定義されている。Single Source of Truth (SSoT) としての規約集約ドキュメントは存在しない。

1.3 課題 (Problem)

• 新規参加者の参照コスト: 「bizlp の ADR 規約」を 1 箇所で見れず、7 ADR を横断して読み解く必要がある。Jr 1 名が 2026-10 入社予定で属人運用が崩壊するリスク
• AI Agent の解釈困難: Claude/Gemini/GPT が adr-lint の根拠を理解しづらく、ADR 起案時に規約整合性チェックが甘くなる
• 規約改訂時の整合性維持: 1 ルール変更で 2-3 ADR を同時編集する必要があり、片肺更新による不整合が発生しやすい

1.4 制約・要件 (Constraints & Requirements)

• Anthropic Skill 500 行制約遵守
• 業界 FW (ESLint 10 節 / Pylint / Ruff Rationale 3 文 / markdownlint) との整合
• adr-lint.mjs CI との整合性自動検証可能
• YAML frontmatter による機械可読性確保
• 将来 rule 数増加 (11 → 30 超想定) への耐性

1.5 目標 (Goals / To-Be)

docs/_internal/05_how-to/adr-lint_rules.md を新規作成し、11 rule + 関連 ADR 7 件を 1 doc に集約して ADR 規約の SSoT を確立する。Discovery (Summary Table) と Detail (深掘り) の二層構造で目的別アクセスを実現する。Non-Goals: adr-lint.mjs 本体の autofix 実装、過去 ADR 本文の書き換え (リンク追加のみ)。

2. 決定

Claude 10 節構造を基礎 + Gemini Progressive Disclosure 思想で補強した bizlp informed synthesis を採用し、docs/_internal/05_how-to/adr-lint_rules.md を新規作成する。

2.1 10 節構造

1. Purpose & Scope — 本 doc の目的、対象 (ADR 起案者・レビュアー・AI Agent)
2. Severity Legend — error / warning / info の意味
3. Category Legend — Structure / Content / Metadata / Status の 4 カテゴリ
4. Summary Table (Discovery Layer) — 11 rule の一覧 (Gemini Progressive Disclosure)
5. Structure Rules (Detail) — §4 から深掘り
6. Content Rules (Detail)
7. Metadata Rules (Detail)
8. Status Rules (Detail)
9. Legacy / Deprecated — 過去 rule の経歴
10. Changelog — rule 追加・改訂履歴

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

各 rule のメタデータは、Markdown frontmatter (--- 区切り) ではなく、本文中の YAML コードブロック (```yaml ... ```) として記述する。理由:

• parsing 安全性: 1 Markdown ファイル内に複数の frontmatter ブロックを配置する仕様は標準 Markdown parser (gray-matter / remark-frontmatter 等) が想定しておらず、parsing エラーや先頭 frontmatter 以外の無視リスクが高い (Gate 3: Gemini + o3 が高優先指摘)
• AST 抽出容易性: コードブロックは remark / unified で言語タグ (yaml) で抽出可能、CI スクリプトでパース可能
• 将来移行性: 後述 §6 撤退条件で言及する「rules/.yaml 個別ファイル分割」への移行も容易 (コードブロック → 個別ファイル抽出スクリプト)

各 rule 本文の先頭に以下の YAML コードブロックを配置する:

id: <rule-id>           # 例: numbered-header
severity: <error|warn>  # corrigendum (v3.1): "warning" → "warn" (コード SSoT 整合)、"info" は未実装のため削除
category: <structure|content|metadata>  # corrigendum (v3.1): "status" は該当 rule なしのため削除
since: <YYYY-MM-DD>
status: <active|deprecated>
fixable: <true|false>   # autofix 対応有無
description: <one-line summary>
related_adrs: [ADR-NNNN, ADR-NNNN]

2.3 各 rule 本文構造

• Rationale (Ruff 3 文形式): 1 文目「何を守るルール」、2 文目「なぜ重要」、3 文目「違反時の影響」
• ❌ FAIL Example: 違反例コード
• ✅ PASS Example: 修正後コード
• References: 関連 ADR / 業界 FW (ESLint / Ruff / markdownlint)

3. 判断基準 (Decision Drivers)

ADR-0050 で確立した arc42 Q42 9 タグ + WSM + K.O. criterion (CBA Suhr 1999) を本 ADR にも適用する (ADR-0052 v2 に続く ADR 起案への第二適用例)。

3.1 評価軸 (Q42 5 軸選定、ADR-0050 §4.2 準拠)

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

3.2 評価軸 × 案スコア表

加重和首位 = K.O. 通過案 = 採択案 (Claude 10 節 + Gemini Progressive Disclosure)。純粋 Claude (X1) や純粋 Gemini (X2) も K.O. 通過するが、採択案より 0.18〜0.29 ポイント低い → 両者の advantage を統合する bizlp informed synthesis が妥当。

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

• 案 X1: Claude 10 節構造のみ (Gemini Progressive Disclosure なし) — 10 節で網羅性は確保できるが、Discovery (Summary Table) と Detail (深掘り) の二層分離がない。不採用理由: 新規参加者が「rule 一覧をざっと見たい」用途と「特定 rule の根拠を読みたい」用途で同じ doc を上から読む必要がある (#flexible=3, #usable=3)。将来 30 超で 500 行制約に逼迫した時の分割戦略も曖昧。
• 案 X2: Gemini Progressive Disclosure のみ (Detail なし) — Discovery layer (Summary Table) は強力。不採用理由: 各 rule の Rationale (Ruff 3 文) / FAIL / PASS Example が省略され、AI Agent が adr-lint の根拠を深掘りできない (#maintainable=3)。「規約ドキュメント」としての完備性に欠ける。
• 案 X3: GPT 案 (フラットな rule リスト + 業界 FW 引用なし) — 不採用理由: 業界 FW 照合がなく PR #811 の close 理由を踏襲する形になる (#suitable=2)。K.O. 不通過。RQ-051 Synthesis でも採点最下位。
• 案 X4: 何もしない (現状の分散規約継続) — 不採用理由: 7 ADR に分散したままで新規参加者の参照コスト最大 (#usable=1)、規約改訂時の不整合リスク継続。Jr 入社 (2026-10) で属人運用が崩壊する想定 (#maintainable=1)。K.O. 不通過。本 ADR の起案動機を根本否定。
• 案 X5: rules/<id>.yaml 個別ファイル分割 (Gate 3 で o3 提案、将来オプション) — 各 rule を docs/_internal/05_how-to/adr-lint_rules/rules/<id>.yaml の個別ファイルとして配置し、Discovery layer (adr-lint_rules.md) は Summary Table + 各 rule への参照リンクのみ持つ案。完全な parsing 安全性 + Schema validation 容易だが、初期実装で 11 ファイル + index の構造は MVP として過剰 (#operable 5 だが #usable 3、初期工数 +50%)。本 ADR では 採用しないが §6 撤退条件で将来移行パスとして正式採用。500 行逼迫 (6 ヶ月後 Review After) で移行発火。

5. 影響 (Consequences)

5.1 正の影響 (Good)

• ADR 規約の Single Source of Truth (SSoT) 確立: 11 rule + 関連 ADR 7 件を 1 doc に集約、AI Agent 解釈性向上
• 新規参加者 (Jr 2026-10 入社) の引き継ぎコスト削減: 7 ADR 横断読解 → 1 doc 通読で完結
• 規約改訂時の整合性: doc 中心更新で関連 ADR は参照リンクのみ管理
• ADR-0050 の Synthesis → ADR 化フローの第二実証例 (ADR-0052 に続く)

5.2 負の影響 (Bad)

• 初期実装コスト 13-22h (内訳: doc 初期実装 8-12h、本 doc から過去 ADR への片方向参照リンク整備 7×10 分 = ~1h、adr-lint.mjs と doc 整合性 CI 化 ~4-9h ← v3 で Gate 3 o3 指摘を反映し過小見積もりを是正)
• 規約改訂時に「doc 編集 (本 doc が SSoT)」の単一運用 (v3 で双方向同期負荷を解消、Immutability 遵守)
• 運用コスト: 新規 rule 追加時 30-60 分 / rule、既存 rule 改訂時 15-30 分 / rule、6 ヶ月ごとレビュー ~1h

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

• fixable: フィールドが現状すべて false (autofix 未実装) → 視覚的 clutter、ただし future-proof として受容
• ADR-0050 v1 暫定値 (重要度ラベル係数 Must ×2.0 / High ×1.0 / Medium ×0.5) の影響を受ける可能性 → ADR-0050 v2 で見直し時に追従

5.4 ROI 計算 (v3 で論理整合化、Gate 3 Claude 指摘反映)

初期 13-22h の回収シナリオ:

• 回収期間: 13-22h ÷ (~2h/月、Jr 入社前) = 6-11 ヶ月 (保守的見積もり)
• Jr 入社後 (2026-10) は ~4.5h/月削減 で回収速度倍増 → 実質 3-5 ヶ月で総回収
• v2 が「半年で回収」と書いたのは Jr 入社後の月次削減を暗黙前提にしたため。v3 で削減の内訳を明示

6. 撤退条件 (Rollback Plan)

再評価トリガー

• 3 ヶ月後 (2026-08-19): 新規 rule 追加が 1 件以上発生し、doc 構造が機能したか確認。10 節構造で表現困難なら案 X2 (Progressive Disclosure 中心) へ寄せる検討
• 6 ヶ月後 (2026-11-19): doc 行数が 500 行に逼迫していれば Progressive Disclosure 分割を実施 (Discovery / Structure / Content / Metadata / Status の 5 ファイル分割)
• 1 年後 (2027-05-19): Gemini の superseded_by 等の未採用 metadata フィールドの追加検討、業界 FW (markdownlint v2 等) の規約改訂を反映
• いずれかで構造に深刻な問題があれば ADR-0050 §6.1 に従い v2 改訂検討

撤退手順

完全撤退時 (~1.5h、v3 で双方向リンク巻き戻し作業を解消):

1. docs/_internal/05_how-to/adr-lint_rules.md を docs/_internal/_deprecated/ に移動 (git mv)
2. docs/_config.json nav から本 doc を削除
3. 過去 ADR の本文は 不変 (Immutability 原則、v3 で双方向リンク廃止により巻き戻し不要)
4. 本 doc を前提に追加された CI スクリプト (scripts/adr-lint-doc-consistency.mjs 等) を if (existsSync(...)) ガードで無効化、または削除

部分撤退 (500 行逼迫時、案 X5 への移行 ~6-10h):

1. 各 rule の YAML コードブロックを docs/_internal/05_how-to/adr-lint_rules/rules/<id>.yaml に抽出 (スクリプト化可能)
2. adr-lint_rules.md は Discovery layer (Summary Table) + 各 rule への参照リンクのみ保持
3. CI スクリプトを「コードブロック解析」→「個別 YAML ファイル読込」に変更 (両対応で互換移行可能)

負債化リスク

• リスク 1: rule 数 30 超で 500 行逼迫 → 上記「部分撤退 = 案 X5 移行」で対応 (再評価トリガーで発火)
• リスク 2: AI Agent モデル更新で YAML パース互換性問題 → 主要 3 モデル (Claude / Gemini / GPT) で YAML コードブロック解釈テストを四半期実施 (Gate 3 Claude 提案)
• リスク 3: 業界 FW (markdownlint 等) の規約改訂 → 6 ヶ月ごとレビューで反映、本 doc の related_adrs フィールドが孤立しないよう CI で参照整合性チェック追加
• リスク 4 (v3 新規): §3 評価軸スコアの confirmation bias (Gate 3 Claude 指摘) — 採択案がほぼ全軸 4-5 点を取る根拠は §3.1 解釈と §3.2 注釈で裏付けたが、起案者バイアスは完全排除困難。3 ヶ月後 Review After で第三者 (Jr 入社後の代表取締役 + Jr 2 名体制) による re-scoring を実施し、加重和の安定性を検証

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証手段 1 (機械検証): scripts/adr-lint.mjs の rule id と docs/_internal/05_how-to/adr-lint_rules.md 内の YAML コードブロックから抽出した rule id・Severity の照合 CI スクリプトを追加 (scripts/adr-lint-doc-consistency.mjs、§5.2 初期実装の ~4-9h に含む)。remark + unified で AST 解析、yaml タグ付きコードブロックを抽出して機械検証 (Gate 3 o3 提案、JS モジュール側も AST 解析でハードコードとの差異検出)。
• 検証手段 2 (機械検証): npm run docs:build 成功 + warning なしを CI ゲートに組み込む。本 doc 行数 ≤ 500 行を CI で検証 (Anthropic Skill 制約遵守)。400 行で warning、500 行で error の二段階閾値で運用 (Gate 3 Claude 指摘の現実性確保)。
• 検証手段 3 (機械検証 + 手動): 関連 ADR 7 件 (ADR-0023/0030/0032/0036/0038/0039/0049) と本 doc の 片方向参照 (本 doc → 過去 ADR) 整合性を CI で確認 (v3 で双方向同期負荷を解消、ADR Immutability 遵守)。Discovery layer (§4 Summary Table) のみ読んで 11 rule の存在を把握可能か、新規参加者目視テスト 1 件実施 (手動)。
• 実行頻度: CI 検証は PR ごと毎回、手動レビューは ADR 起案・改訂時、構造レビューは 3 / 6 / 12 ヶ月の Review After トリガーで実施。
• 違反時の対応: CI 失敗時は PR マージブロック、起案者が修正。500 行逼迫 (warning レベル) なら §6 部分撤退に従い案 X5 (個別ファイル分割) への移行を検討。参照リンク欠落は adr-lint warning を追加し、修正 PR を即時起票。

7. 参照 (References)

• 関連 ADR (Refines + 集約参照、片方向参照): ADR-0023 / ADR-0030 / ADR-0032 / ADR-0036 / ADR-0038 / ADR-0039 / ADR-0049 — 本 doc から各 ADR への片方向参照のみ (ADR Immutability 原則遵守、v3 で双方向リンクを廃止)。過去 ADR の本文・関連節は不変。本 doc 内の各 rule の related_adrs: フィールド + 「References」節で根拠 ADR を明示。将来、規約集約が完全に doc 中心になった場合は、過去 ADR を Superseded 化する別 ADR を新規発行する選択肢 (Gate 3 Gemini 提案、1 年後 Review After で判断)。
• 関連 ADR (Confirms 運用化第二例): ADR-0050 (Synthesis 標準テンプレート、Q42 9-tag MCDA) — 本 ADR §3 で Q42 5 軸 + WSM + K.O. criterion を適用、ADR-0050 のフレームワークが ADR 起案に有効であることを実証 (第一例は ADR-0052 v2、2026-05-19)
• 関連 PR/Issue: PR #811 (close、業界 FW 未調査 → 本 ADR で根本対応) / PR #812 (RQ-051 3 モデル並列調査) / PR #818 (RQ-051 Synthesis、本 ADR の直接の根拠) / PR #847 (本 ADR Pipeline 自動 PR、Gate 4 47/50 で Gate 3 Gemini + o3 から YAML frontmatter parsing リスク指摘 → v3 で対応)
• 検証可能な完了条件:
  • docs/_internal/05_how-to/adr-lint_rules.md が 10 節 + 11 rule で完成 (行数 500 以内)
  • 各 rule に YAML コードブロック (```yaml ... ```) 8 フィールド がすべて存在 (scripts/adr-lint-doc-consistency.mjs で remark/unified AST 解析による機械検証)
  • 本 doc から関連 ADR 7 件への片方向参照リンクが各 rule の related_adrs: + 「References」節に存在 (CI で参照整合性確認)
  • npm run docs:build 成功、warning なし、行数 400/500 二段階閾値
  • adr-lint.mjs CI 動作と doc 内容の整合性確認 (rule id 一致、Severity 一致を CI で検証、JS モジュール側も AST 解析でハードコード差異検出)
  • Discovery layer (§4 Summary Table) のみ読んで 11 rule の存在を把握可能 (新規参加者目視テスト 1 件)
• 外部資料: ESLint Rule Reference (10 節構造) / Ruff Rationale 3 文形式 / Pylint / markdownlint / CBA Suhr 1999 (K.O. criterion) / arc42 Q42 9 tags / remark + unified (AST 解析、v3 で採用)

8. 変更履歴