RQ-051 Lint 規約ドキュメント ベストプラクティス（Synthesis: 3 モデル突合 + bizlp 採択方針）

本 Synthesis の位置付け: ADR-0050 (Synthesis 標準テンプレート、案 C ハイブリッド) の 第一適用例。RQ-051 段階 2 (3 モデル並列調査) は既に PR #813 で merged 済のため、Decision Drivers の pre-registration は本 Synthesis PR と同時に行う retroactive 形式となる。詳細は §9.1。

1. Context & Problem Statement

1.1 顕在化した問題

bizlp の scripts/adr-lint.mjs は 11 個の Lint ルール を実装するが、 それぞれのルールが 7 つの ADR (ADR-0023 / 0030 / 0032 / 0036 / 0038 / 0039 / 0049) に分散 して定義されており、規約ドキュメントとして集約 されていない。

• 新規参加者 (将来の経営層) が「bizlp の ADR 規約」を一覧できない
• AI Agent (Claude/Gemini/GPT) が adr-lint の根拠を理解しづらい
• 規約改訂時に複数 ADR の更新が必要で、整合性維持が困難

過去の試み:

• PR #811 (close): docs/_internal/05_how-to/adr-lint_rules.md を新規 作成しようとしたが、業界の Lint Rule Reference (ESLint / Stylelint / markdownlint / Ruff / RuboCop / adr-kit / Vale 等) の標準構造を未調査で 起案、close
• RQ-051 段階 1-2 (PR #812 / #813 merged): 3 モデル並列で業界 best practice を調査済

1.2 解決すべき問題

1. 11 Lint rule の集約: 1 つの reference doc に整理
2. 業界フレームワーク照合: ESLint / markdownlint / Ruff 等の標準構造に従う
3. 1 人法人スケール: MVP minimum、年 50 件規模で運用可能な粒度
4. AI Agent 解釈性: Anthropic Skill 500 行制約、Progressive Disclosure
5. 将来拡張対応: rule 追加・廃止・autofix の段階導入

2. Decision Drivers (Pre-registered, 5 軸採用)

2.1 採用軸 (5 軸、arc42 Q42 完全固定)

満点係数合計 = 2.0 + 2.0 + 1.0 + 0.5 + 0.5 = 6.0 案件素点満点 = 5 × 6.0 = 30.0

2.2 [Must] 2 個の justification

#maintainable と #suitable の両方を Must とする:

• #maintainable 単独: 業界 FW 照合せず独自構造を作るリスク (PR #811 と 同じアンチパターン再生)
• #suitable 単独: 業界 FW 完全準拠で AI Agent 解釈性が二の次になる可能性
• 両方が同時に満たされる必要がある

5 軸中 Must 2 個 = 軸数の半分以下、ADR-0050 §4.2 ルール適合。

2.3 省略軸 justification (Triage = Standard につき 1-2 行)

3. Considered Options (3 モデル並列調査結果)

3.1 Claude Opus 4.7 Research の提案

推奨: YAML+Markdown ハイブリッド、10 節構造 (markdownlint pattern B

• RuboCop pattern D 統合)

主な特徴:

• 10 節: Purpose / Severity Legend / Category Legend / Summary Table / 4 カテゴリ別ルール詳細 (Structure / Content / Metadata / Status) / Legacy / Changelog
• 各ルール必須 10 項目: id, severity, category, since, status, fixable, description, rationale, FAIL/PASS examples, related_adrs
• Rationale: Ruff 3 文構造 (What/Why/Alternative) + ADR リンク
• Examples: ❌ FAIL → ✅ PASS の 2 コードブロック
• 各ルール ≤30 行、総文書 ≤500 行 (Anthropic Skill 制約)

強み:

• YAML frontmatter で AI Agent 機械処理に最適化 (metadata → prose の順序)
• 業界 3 FW (markdownlint + RuboCop + Ruff) を informed synthesis として統合
• fixable: フィールドを事前配置、将来の autofix 採用にスムーズ
• 1 ページ scannability (category anchors) + 詳細 lookup の両立
• SemVer は ADR 番号で代用、バージョン管理オーバーヘッドゼロ

弱み:

• 500 行制約は rule 数 30 超で逼迫 → progressive disclosure 分割戦略が必要
• since: ADR-XXXX は ADR 採番安定性に依存 (bizlp では問題ないが外部依存)
• Deprecation-at-end-of-doc は新規参加者の legacy 認識でアンカー必須

3.2 Gemini 2.5 Pro Deep Research の提案

推奨: YAML inline + Markdown、3 節構造 (Progressive Disclosure "Discovery / Activation / Details")

主な特徴:

• 3 節: Severity Levels / Rule Index (Discovery Layer) / Rule Details (Activation Layer)
• 各ルール必須 7 + optional 3: Rule ID, Severity, Fixable, Related ADR, Description, Rationale (Problem/Solution/Impact), PASS/FAIL examples / optional: Deprecated, Superseded_by, Category
• YAML metadata は inline key-value (frontmatter ブロック不使用)
• コードブロック: <!-- ❌ Bad --> / <!-- ✅ Good --> コメント区切り

強み:

• Progressive disclosure で AI Agent token 負荷削減 (Discovery ≤2KB、 Activation ≤50KB on demand)
• Fixable フラグが Agent 自律判断の guardrail として機能 (safe vs unsafe rewrites)
• Flat index で深い階層の認知負荷を排除、13-30 rule スケール最適
• Rationale の 3 層構造 (Problem/Solution/Impact) で 1 人法人での form ossification 防止
• YAML metadata は人間 (scan) と機械 (parse) 両対応

弱み:

• Agent system prompt 調整必要 (「Discovery 先 → Activation」を教える)
• superseded_by は廃止が稀な前提、多数廃止時に維持困難
• llms.txt プロトコル採用の価値は単一 11-rule 文書では不明瞭

3.3 GPT-5 Deep Research の提案

推奨: Pure Markdown (YAML optional)、4 節構造 (lightweight MVP)

主な特徴:

• 4 節: Introduction (purpose / Severity / CI behavior) / Rule Summary (one-liner list) / Rule Details / Migration / Changelog (≤1 page)
• 各ルール必須 6 + optional 2: id, description, bad_example, good_example, severity, fixable / optional: rationale (1-2 行), related_adr, deprecated
• Examples-before-explanation (visual-first parsing)
• 11 rule ≤ で ESLint 級のカテゴリ複雑性を意図的に省略

強み:

• 絶対最小限の MVP、2-3 時間で執筆可能、ツール不要
• Examples 先 = visual scanning と copy-paste 自然
• Rationale / Config 等の追加は incremental、リファクタ不要
• Schema lock-in なし、将来 ESLint 級への進化が低摩擦
• 1 人法人の現実を踏まえた prose narrative、rigid templating 否定

弱み:

• machine-readable metadata 不在、Agent 解析に custom parsing or 人手必要
• Rationale を ADR body に委ねる → rule form erosion リスク (Claude/Gemini は両方とも明示 rationale を優先)
• fixable フィールドは現状ほぼ未使用、視覚的 clutter リスク
• Deprecation 管理を「必要時に追加」、Claude/Gemini の forward-planning に劣る

4. Evaluation Matrix (下位層: 加重和 + 正規化)

代表取締役氏が手動採点 (Critic agent 未実装):

計算詳細

Claude:  5×2.0 + 5×2.0 + 5×1.0 + 5×0.5 + 4×0.5
       = 10 + 10 + 5 + 2.5 + 2
       = 29.5 / 30.0 = 0.983

Gemini:  4×2.0 + 4×2.0 + 4×1.0 + 5×0.5 + 5×0.5
       = 8 + 8 + 4 + 2.5 + 2.5
       = 25.0 / 30.0 = 0.833

GPT:     3×2.0 + 3×2.0 + 4×1.0 + 3×0.5 + 4×0.5
       = 6 + 6 + 4 + 1.5 + 2
       = 19.5 / 30.0 = 0.650

加重和首位: Claude (0.983) > Gemini (0.833) > GPT (0.650)

5. K.O. Criterion 判定 (上位層: CBA、Standard につき 1 ラウンド)

代表取締役氏が手動で K.O. 判定。

5.1 [Must] 軸 1: #maintainable

5.2 [Must] 軸 2: #suitable

5.3 K.O. 統合判定

• Claude: 両 Must 完全通過 + 加重和首位 (0.983) → 採択候補
• Gemini: #maintainable 通過 + #suitable 部分通過、加重和 2 位 (0.833) → 補強要素として検討
• GPT: #maintainable / #suitable とも Fail → 除外

6. Decision Outcome

6.1 採択案

Claude 案を基礎 + Gemini の Progressive Disclosure 思想で補強した bizlp informed synthesis

純粋 Claude (10 節) は完全通過し加重和首位だが、Gemini の Progressive Disclosure (Discovery → Activation → Details の 3 層思想) は #efficient (Anthropic Skill 500 行制約) において Claude と並ぶ最高評価。両者を統合 することで、Claude の 10 節構造の「Section 4 Summary Table」と「Section 5-8 詳細」の関係を 明示的に Discovery → Activation 階層 として位置付ける。

6.2 採択案の構成

基礎フレームワーク (業界調査済):
- 全体構造: Claude 案 (10 節)
  → markdownlint (pattern B: 1 ページ集約) + RuboCop (pattern D: 構造化
    metadata) + Ruff (3 文 rationale) の informed synthesis
- Progressive Disclosure 思想: Gemini 案
  → Section 4 (Summary Table) を Discovery layer、Section 5-8 (Detail) を
    Activation layer として明示

bizlp 特色での informed extension:
- 11 ルールの具体カテゴリ分割: ADR-0023/0030/0032/0036/0038/0039/0049 への
  紐付け
- ファイル配置: docs/_internal/05_how-to/adr-lint_rules.md
- Anthropic Skill 500 行制約への適合 (現時点 11 rule で十分余裕、
  将来 30 rule 超で分割戦略を ADR-0050 §6.1 に従い検討)
- bizlp 既存 ADR との整合 (Kruchten Type / Triage / Scope 等のメタフィールド)

6.3 採用する 10 節構造 (詳細)

# bizlp adr-lint Rule Reference

## 1. Purpose & Scope
adr-lint の目的、bizlp ADR への適用範囲、本 reference の役割

## 2. Severity Legend
Critical / Error / Warning / Info の定義、CI 動作との対応

## 3. Category Legend
4 カテゴリ (Structure / Content / Metadata / Status) の定義

## 4. Summary Table (Discovery Layer)
| Rule ID | Severity | Category | Fixable | Description (1 行) | Related ADR |
|---|---|---|---|---|---|
| 11 行 (rule ごと) |
> 全 11 rule の一覧、Activation layer (§5-8) へのアンカーリンク

## 5. Structure Rules (Activation Layer)
(YAML frontmatter + 詳細記述 × N rule)

## 6. Content Rules (Activation Layer)
(同上)

## 7. Metadata Rules (Activation Layer)
(同上)

## 8. Status Rules (Activation Layer)
(同上)

## 9. Legacy / Deprecated Rules
廃止予定または supersede 済 rule の一覧

## 10. Changelog
ADR 番号と rule 追加・変更履歴の対応表

6.4 各 rule の必須 metadata (YAML frontmatter 形式)

id: <rule-id>
severity: critical | error | warning | info
category: structure | content | metadata | status
since: ADR-NNNN  # 導入元 ADR
status: active | deprecated
fixable: true | false
description: <1 行 description>
related_adrs: [ADR-NNNN, ...]

その後の Markdown 本文:

• Rationale (Ruff 3 文形式: What / Why / Alternative)
• ❌ FAIL Example (コードブロック)
• ✅ PASS Example (コードブロック)
• Notes (optional)

6.5 Justification

最優先 Decision Drivers (#maintainable + #suitable) に対して:

• Claude 案は #maintainable (5/5) で AI Agent 解釈性最強の Advantage
• Claude 案は #suitable (5/5) で markdownlint + RuboCop + Ruff の 3 業界 FW 統合という決定的 Advantage
• Gemini の Progressive Disclosure 思想は #efficient (5/5) で Claude と同等、純粋 Claude では #efficient が 5/5 になる余地を、Gemini の階層 化思想で言語化することで担保

GPT は両 Must で Fail のため除外。Gemini 純粋採用は #suitable が部分通過 のため Claude 採択が筋。

6.6 数値検証

正規化加重和: Claude 0.983 (首位) + 両 Must 通過 → 加重和と K.O. が同じ案を 指す → 結論の確信度最大。

6.7 長期方針

• 現時点 11 rule → 将来 30 rule 超で 500 行制約に逼迫した場合、ADR-0050 §6.1 に従い ADR-0050 v2 改訂検討 (Progressive Disclosure 分割戦略)
• Gemini の superseded_by フィールドは future-proof として §9 Legacy 章 で運用、廃止 rule が増えた段階で別途検討
• GPT 推奨の「examples-first」アプローチは採用しないが、§5-8 各 rule 内で FAIL → PASS の順序は維持 (visual-first parsing と整合)

7. Consequences

7.1 Positive (Good)

• 業界 FW (markdownlint + RuboCop + Ruff) に照合済の Rule Reference doc → PR #811 のアンチパターン (業界未照合の独自合成) を根本対応
• 11 rule の集約により 1 文書で全規約を把握可能 → 新規参加者の学習負荷低減
• YAML frontmatter で AI Agent 機械処理に最適化
• Progressive Disclosure 思想で Anthropic Skill 500 行制約への適合
• bizlp 既存 ADR (0023/0030/0032/0036/0038/0039/0049) との明示的紐付け
• ADR-0050 (Synthesis 標準テンプレート) の 第一適用例 として運用検証 の材料に

7.2 Negative (Bad)

• 10 節構造は 4 節 (GPT 案) より執筆工数大 (推定 8-12 時間)
• YAML frontmatter の各 rule への追記が必要 (11 rule × 8 フィールド = 88 項目)
• 500 行制約は将来の rule 数 30 超で逼迫する制約

7.3 Neutral / Trade-offs

• Claude の fixable: フィールドを事前配置するが、現状すべて false (autofix 未実装) → 視覚的 clutter になるが future-proof として受容
• Gemini の <!-- ❌ Bad --> コメント形式は採用せず、Claude の ❌/✅ emoji 直書きを採用 (可読性優先)

8. Confirmation (Standard 必須)

8.1 実装確認方法

8.2 レビュー期日

• 段階 4.1-4.5 (Rule Reference doc 実装): 1 週間以内
• 段階 5 (adr-lint.mjs と doc の双方向整合性 CI 化): 2 週間以内
• 振り返り: 3 ヶ月後に doc 使用感を評価

8.3 振り返り (Standard 推奨)

• 3 ヶ月後: 新規 rule 追加時に doc 構造が機能したか
• 6 ヶ月後: 500 行制約に余裕があるか、Progressive Disclosure 分割の必要性
• 1 年後: Gemini の superseded_by 等の未採用フィールドの追加検討

8.4 蓄積する組織知 (Standard 推奨)

• Rule 追加時のテンプレ運用が形骸化していないか
• AI Agent が doc を読んで rule 違反を正確に説明できるか
• synthesis_anti_patterns.md に Rule Reference doc 運用の誤り事例追加

9. Caveats / 限界条件

9.1 Pre-registration の状態 (本 Synthesis 固有)

本 Synthesis は ADR-0050 (Synthesis 標準テンプレート) 確立後の 第一適用例 であり、以下の特殊状況下にある:

• RQ-051 段階 1 (PR #812) と段階 2 (PR #813) は ADR-0050 確立前に merged
• Decision Drivers (§2) は本 Synthesis PR 内で初めて pre-register
• 段階 2 の 3 モデル結果を読んだ後で Driver を選定したことになる (理想的な pre-registration ではない)

informed synthesis として legitimate と判断する理由:

1. 業界調査 (段階 1-2) は完了済、本 Synthesis では既存知見を活用するのみ
2. Explicit grounding: markdownlint / RuboCop / Ruff / arc42 Q42 を明示
3. Justification: bizlp 11 rule + AI Agent パイプライン + Anthropic Skill 500 行制約という識別可能な特徴に紐付け

RQ-053 以降は段階 1 PR で Driver pre-register → 段階 2 並列調査 → 段階 3 Synthesis の順序を厳守する。

9.2 暫定値の明示

• 「11 rule → 30 rule 超で 500 行制約逼迫」の閾値は v1 暫定
• Gemini の Progressive Disclosure 階層境界 (Discovery ≤2KB / Activation ≤50KB) は文書サイズ次第で見直し対象

9.3 Confirmation bias 緩和策

採点を逆方向で試行:

• もし Claude #maintainable = 3 (5 → 3 に下げる) と仮定 → Claude 加重和 = 25.5、Gemini 25.0 と僅差。しかし #suitable の K.O. 判定でも Claude が完全通過、Gemini が部分通過 → 採択は Claude のまま変わらず
• もし GPT を #suitable = 4 (3 → 4) と仮定 → GPT 加重和 22.5、依然 3 位 かつ K.O. Fail で除外は変わらず
• → 採点バイアスがあっても結論は安定

9.4 ADR-0050 適用の妥当性検証

本 Synthesis は ADR-0050 の第一適用例であり、テンプレートの実用性を検証 する重要な事例。観察された改善余地:

• §2.4 省略軸の数 (4 軸) が想定通り 4-6 個 → 規約と整合
• §4 Evaluation Matrix の採点根拠が長文化 → writing_guide §4.2 で 「短くて良いので 1-2 文」と再強調する余地あり
• §5 K.O. 判定の手動実施は writing_guide §5 で「Critic agent 未実装時の 手動代行手順」として既に明記済 → 問題なし

これらの観察を synthesis_anti_patterns.md または synthesis_rationale.md に運用知見として追記する余地があるが、本 Synthesis では指摘のみ留め、別途 ADR-0050 v2 改訂で対応検討。

10. References

bizlp 既存 ADR

• ADR-0023: ADR ドキュメント構造 (Nygard + MADR 4.0 ミニマル統合)
• ADR-0030: Kruchten 3 分類ラベル
• ADR-0032: Implementation Status メタデータ
• ADR-0036: Confirmation セクション
• ADR-0038: adr-lint メタデータ規約
• ADR-0039: arc42/C4/MADR/feature-folder ドキュメント構造
• ADR-0049: ADR Scope 4 層分類
• ADR-0050: Synthesis 標準テンプレート (案 C ハイブリッド、本 Synthesis の規約)

業界フレームワーク (一次資料)

• markdownlint: https://github.com/DavidAnson/markdownlint
• RuboCop: https://docs.rubocop.org/rubocop/cops.html
• Ruff: https://docs.astral.sh/ruff/rules/
• ESLint: https://eslint.org/docs/latest/rules/
• Stylelint: https://stylelint.io/user-guide/rules/
• Anthropic Skill authoring: 500-line constraint, Progressive Disclosure

関連 RQ / PR

• RQ-051 (本 Synthesis の根拠 RQ)
• RQ-052 (ADR-0050 確立)
• PR #811 (close): adr-lint_rules.md 起案、業界未調査で close
• PR #812 (merged): RQ-051 段階 1 起案
• PR #813 (merged): RQ-051 段階 2 — 3 モデル並列調査
• PR #814 (close): 旧 RQ-051 Synthesis、評価軸独自合成で close

段階 2 結果ファイル

• RQ-051_lint_rules_doc_best_practices_result_claude.md
• RQ-051_lint_rules_doc_best_practices_result_gemini.md
• RQ-051_lint_rules_doc_best_practices_result_gpt.md