RQ-051 Lint 規約ドキュメント (Rule Reference) のベストプラクティス調査（GPT-5 Deep Research 結果）

Q1. 主要 Lint ツールの Rule Reference（業界事例）

主要ツールのルール参照ドキュメントを以下にまとめた。各ツール名、ルール数、公式ドキュメント URL、対象言語/領域、初リリース年・最新更新年、想定利用規模を示す。

出典: 公式ドキュメントやリリースノート等。

Q2. ルール参照ドキュメントの必須項目マトリクス

以下は主要ツールの Rule Reference に含まれる項目の有無比較である。

• "○" はその項目を公式ドキュメントで明示的に説明・例示していることを示す。ESLint や Stylelint はルール名/ID、説明、例示、設定例、Fixable 指定、カテゴリなどを網羅する。markdownlint では Bad/Good の例が豊富、Rationale 付きルールもある。Pylint は主にメッセージ一覧のみ、例示は少ない。RuboCop は各警告（Cop）に説明と AutoCorrect 例があり、Deprecated Cops を一覧する。Ruff はコード表だけで個別例示が少なく、Fixable と Deprecated はアイコンで示す。

Q3. Rule Reference ドキュメントの章立て・構造パターン

代表的なパターンと事例を整理する。

• カテゴリ別グループ＋サブカテゴリ: Stylelint では「Avoid errors」「enforce conventions」など大分類し、さらに「Deprecated」「Duplicate」など小カテゴリに分割。同様に ESLint も「Possible Errors」「Best Practices」等に分類し、各カテゴリ内をアルファベット順に並べる。利点は論理的なまとまりがあり、大規模なルールセットでも探しやすい。
• ID/名前順一覧: markdownlint は規則を番号（MD001 など）順に並べる。少数のルールや標準で ID 体系が明確な場合に有効。RuboCop も部門（Style, Lint など）内は字順表示。
• Deprecated ルールの先頭表示: Stylelint では「Deprecated」項目を各カテゴリ最上部に置く。類似に ESLint がルール名に ❄ アイコンで示す方法がある。重要な廃止情報を目立たせることで移行を促す。
• 説明順序（例示先行 or 説明先行）: Stylelint や ESLint は具体例を先に示し、その後ルールの詳細解説を行うパターン。これに対し、他ツールではまず説明文を書き、末尾に例を付ける場合もある。bizlp では「例（bad/good）⇒説明」の構成が理解しやすいと考えられる。

以上を踏まえ、bizlp 向け推奨は「カテゴリ別に章分けし、廃止ルールは明示的に注記し、各ルールは例示を先頭に概要・解説⇒設定例」の構成が望ましいと考えられる。

Q4. rationale（ルール必要性）の記述形式

調査では、以下のような形式が見られた:

• 一行要約: 各ルールの概要説明を兼ねている例（Stylelint や ESLint では多くが簡潔な説明文のみ）。
• 複数文構造: 問題点・ルール内容・別解の構成。あまり一般的ではないが、Markdownlint の一部（MD032 など）で「Rationale: XXX」という詳細説明が 3 文程度で記載される場合がある。
• アンチパターン＋推奨パターン: 例示部分に悪い例と良い例を並べ、「Bad/Good」で示す形式。ESLint や Stylelint はこの形式。
• 学術引用付き: 特にリンターでは稀だが、Markdownlint の幾つかではリンク付きで詳細説明を参照する例（MD004 など）。

1 人法人スケール向け推奨は、説明を簡潔にしつつ「Bad/Good」ペアで問題と対策を明示する形式である。例えば「このパターンはエラーとなる/ならない」という具合に具体例を中心に据え、必要なら短い補足説明（1〜2 行）を加える形が扱いやすい。また、ADR ドキュメント Lint の性格上、専門用語を避けて直観的に理解できる文章とするのがよいだろう。

Q5. 具体例提示形式（Good/Bad）

以下の形式が確認できた:

• コードブロック（別々提示）: ESLint 公式などで多用。本文中に「例: 間違ったコード」「例: 正しいコード」と区別し、各々を別のコードブロックで示す。メリットは視認性が高く、Diff を意識しなくて済む。
• Diff 形式: Git パッチのように差分表示。一般的な Rule Reference ではあまり用いられない。
• ペア表記: markdownlint のように「Before/After」あるいは「Bad/Good」というラベル付きで、コードブロックを上下に並べる形式。一目で違いがわかる。
• スクリーンショット: GUI 型 Lint ツール（文書校正ツールなど）で使用例あり（Vale など）があるが、テキスト主体の Lint では稀。

bizlp ADR-lint 向けには、Markdown で書かれた ADR なので、コードブロックで Bad/Good 例を別に提示する形式が適している。読者がコピペ可能で、内容比較も容易であるため、Diff ではなく純粋なコード例 2 つ（間違い例／修正例）の提示を推奨する。

Q6. 廃止/Changelog 管理慣習

調査した事例での主な管理方法は以下の通り。

• ルール内注記: 各ルール説明に「Since vX、Deprecated in vY」と記載。ESLint は設定オプション名の変更等をルールページ内で説明。
• 専用リスト/セクション: Stylelint や RuboCop は廃止ルールを一覧セクションでまとめる（Stylelint では「Deprecated」グループ）。また、Removed Rules HTML など独立ページでまとめることもある。
• Changelog/Migration Guide: 主要ツールは常に更新履歴（CHANGELOG）と移行ガイドを持つ。ESLint や Stylelint 公式サイトに「Changelog」や「Migration」ページがあり、バージョンごとの追加・削除情報を記載。

bizlp の 11 ルール（将来 30 程度）規模では、完全な Changelog 体系は過剰になる可能性が高い。最小限の実装としては、個々のルールドキュメント内に「(Optional) Deprecated: vX から廃止予定」と明示する程度で足りるだろう。サイト全体の更新履歴は簡潔にまとめてもよいが、まずはルール紹介ページで変更を言及する方法を推奨する。

Q7. fixable フラグの取り扱い

• ESLint: --fix 対応ルールにはドキュメントで「Fixable」の表示があり、GitHub 上で自動修正可能を明示。
• Stylelint: ルール定義に fixable: true をフラグで示す仕組みがあり、ドキュメントや UI でチェックマーク表示される。
• Prettier: そもそも全自動整形ツールなのでフラグ不要。
• Ruff: ドキュメントで自動修正可能なルールにアイコン(🛠)を表示する。

現状 bizlp の adr-lint では自動修正機能は未実装だが、将来追加を検討するならメタデータに fixable フラグ欄を用意しておくと良い。現段階では全て false でよいが、設計上フィールドを置いておけば機能追加時にドキュメント側の修正で済む。現状ではフラグ無しでも運用可能であるため「必須ではないが将来性を考慮して設置検討」の姿勢が妥当。

Q8. CI 統合・Severity 説明

調査例から CI 統合と Severity 設定の慣習を整理すると:

• Severity 分類: ESLint は error/warning/off、Stylelint は error/warning、Ruff はすべて error 扱い（--quiet モードで警告抑止）など、それぞれ独自だが、多くは「error は CI ビルド失敗」「warning は注意のみ」で扱われる。特に ESLint 方式に倣い、ADR-lint でも「error は規約違反で CI を止める」「warn はログに出すのみ」という区別を利用するのが一般的である。
• CI 連携: ESLint/Stylelint CLI は --max-warnings=0 などで警告もエラーに昇格させるオプションがある。ADR-lint では error/warn の 2 段階なので、例えば「警告は CI 許容」「error は CI 失敗」にすると運用しやすい。ドキュメントには「error＝必須遵守事項、warn＝改善推奨事項（必須ではない）」と説明すればよい。

推奨形式は、ツールの表記に倣って箇条書きや表で「severity の意味」を説明する形。例: "Error: 強制事項（CI エラー）、Warn: 注意事項（CI 継続）" などと記載すると開発者に分かりやすい。

Q9. AI エージェント対応構造

近年の AI 連携を意識した Rule Reference の特徴には以下がある:

• 機械可読なメタデータ: YAML/JSON FrontMatter や JSON Schema で各ルールの属性（ID、severity、fixable、説明等）を構造化して埋め込む例。GitHub Copilot や Claude などはコードブロックやタグ情報を学習に使えるため、JSON フォーマットなどで明示しておくと便利。
• プログレッシブ・ディスクロージャー: 重要度に応じて情報量を切り分け、必要時に詳細開示する手法。例えば簡潔な概要＋「詳細はここを展開」のような形で、最初に簡易解説を提示し、AI がパースしやすい JSON や Markdown 見出しで詳細を後段に記載する。
• AI 向けのヒント: Anthropic の「Skill」や OpenAI の「tool instructions」のように、Markdown 内に <!-- --> コメントや専用メタタグで AI に向けた補足説明（例: ルールの意図や参照先）を書き込むケースも考えられる。

bizlp 1 人+AI エージェント併用を想定すると、ルール文書は極力シンプルかつ構造化すべきである。具体的には「YAML フロントマターに ID/Severity/Fixable 等を記載する」「ルール本文は Markdown の固定テンプレート（h3 見出しで項目分けなど）を使う」「AI 検索やナレッジ抽出を意識し、箇条書きやコードブロックで要点を明示する」などが有効であろう。これにより AI が規則解釈や自動対応する際に情報を取り出しやすくなる。

Q10. 省略可能な項目

大企業向けの詳細を 1 人法人で省略できるか判断すると、以下が「必須ではない」可能性が高い。

• 詳細な廃止/マイグレーションガイド: ユーザー数が少ないため、厳密なバージョン管理や移行手順書は簡易化可。ルール廃止時はルールページ内に短く言及する程度で十分。
• 高度なカテゴリ/サブカテゴリ分け: 11 ルール（将来 30 程度）では大雑把なグループ分けで足りる。1000 ルール規模で必要な細かな分類は不要。
• 個別の Cross-link: 関連ルールへの注釈は親和性を高めるが、人数が少なければなくても困ることは少ない。資産が増えたときに追加検討。
• 学術的理由づけや外部引用: 参考リンクや論文レベルの裏付けは省略できる。運用方針の説明であれば簡潔な表現で充分。

MVP 必須項目としては、「ルール名/ID、説明、Bad 例/Good 例、Severity、config 例、自動修正可否」が挙げられる。特に例示と設定例は開発者が即利用できるように必要である。一方で「詳細 Rationale、廃止履歴、複雑なカテゴリ分け、関連リンク」は段階的に充実すればよい項目と考える。

Q11. bizlp ADR-lint ルールの推奨章立て案

調査結果を踏まえ、docs/_internal/05_how-to/adr-lint_rules.md の章構成例は次の通りとする:

1. はじめに – ルールドキュメントの目的と運用方法（Severity の扱い、CI 連携方法など）。
2. ルール一覧 – 「Light/Standard/Critical」×「Scope 階層」毎の章分け（例: Tier 毎のサマリ）。ここで各ルールの概要（ID、タイトル）を一覧化。
3. ルール詳細 – 各ルールごとにサブセクションを設け、以下テンプレートで記載。
   • ルール名 (ID) – 例: rule-id
   • 説明 (Description) – ルールの要点（1 文程度）
   • 例 (Examples) – 「Bad:」と「Good:」のコードブロック
   • なぜ (Rationale) – 簡潔な理由（Optional だが 1〜2 行推奨）
   • デフォルト設定 (Default/Config) – .adr-lintrc 設定例
   • Severity/自動修正 (Fixable) – デフォルトの重大度と自動修正可否
   • 関連 ADR – 必要に応じて該当する ADR 参照
   • 備考 (deprecated 等) – 廃止予定や変更点の注記（あれば）
4. マイグレーション/変更履歴 – ルール追加・廃止の履歴（オプション）。
5. 附録 – 設定ファイル記述例、Tier×Scope マトリクス説明など。

各章・ルールテンプレートの必須項目は上記太字部分（Name/説明/例/Severity/Config など、計約 6〜8 項目）、省略可能な項目は「Rationale（簡素化可）」と「リンク/廃止情報」等である。例示はコードブロックによる Bad/Good ペア形式とし、文章説明は簡潔に。AI 解析を意識して、テンプレートは固定フォーマット＆YAML FrontMatter（rule: , severity: など）付きとするとよい。関連 ADR へのリンクは、ルールの適用範囲や背景に直接関連する既存 ADR があれば追加し、それ以外は不要である。

bizlp 採用推奨案: ADR-lint ルールは全 4 節構成とし、各ルールは「名前・説明・Bad 例・Good 例・設定例・Severity/自動修正・(省略可) Rationale・関連 ADR・備考」をテンプレートとして記載する。廃止履歴は簡易化し、Tier/Scope 情報は別節で整理。構造化された FrontMatter を用い、例示先行形式で AI や開発者が解釈しやすい文書とすることで、効率的な運用を図る。