最終更新: 2026/06/22 18:56
commonid: rq-051-lint-rules-doc-best-practices-r…type: research-resultstatus: archived
pagemodel: gemini-2.5-pro-deep-researchaudience: agentdate: 2026-05-17

RQ-051 ADR Lint 規約ドキュメント（Rule Reference）の業界ベストプラクティスと AI Agent 統合に向けたアーキテクチャ設計調査（Gemini 2.5 Pro Deep Research 結果）

本報告書は、1 人法人（Solo Founder）規模で運用される管理会計 SaaS プロジェクトにおける Architecture Decision Record（ADR）の Lint 規約ドキュメントの最適な設計手法を、業界のベストプラクティスおよび最新の AI Agent 統合ワークフローの観点から調査・分析したものである。静的解析ツールの運用において、Rule Reference（規約ドキュメント）は単なるマニュアルの枠を超え、開発者の学習、アーキテクチャの形骸化防止、さらには AI Agent による自律的なコード修正の基盤となる極めて重要なアーティファクトとして位置付けられる。本稿では指定された 11 の研究課題に順次回答し、最終的に bizlp 固有の文脈（scripts/adr-lint.mjs を用いた 13 ルールの運用）に最適化されたドキュメントアーキテクチャを提示する。

Q1. Lint 規約ドキュメントを公開している主要 OSS / ツールの網羅

ソフトウェア工学の歴史において、コードの品質やスタイルを自動検証する Linter およびフォーマッタは、開発者の生産性を担保する上で不可欠なツールとして発展してきた。これらのツールが提供する Rule Reference の構造は、対象領域や開発コミュニティの規模によって多様な進化を遂げている。以下に、業界で広く参照されている主要な OSS および標準規格を、その特性と設計思想に基づいて分類し網羅する。

第一の分類は、汎用プログラミング言語向けの大規模 Linter 群である。この領域の代表格である ESLint (https://eslint.org/docs/latest/rules/) は、JavaScript および TypeScript エコシステムにおける事実上の標準であり、2013 年の初公開以来、継続的に更新され、現在では数百に及ぶ膨大なルールを管理している。ESLint のドキュメントは、個人開発からメガテック企業まであらゆる規模の組織を想定して設計されており、各ルールの目的、推奨設定、自動修正の可否などが極めて体系的に整理されている。同様に、Python 領域における Pylint (https://pylint.pycqa.org/en/latest/user_guide/checkers/features.html) は 2001 年から存在する老舗ツールであり、中規模から大規模な組織における厳格な静的解析を目的とし、チェッカーとメッセージの組み合わせによる詳細な規約ドキュメントを提供している。Ruby コミュニティにおける RuboCop (https://docs.rubocop.org/rubocop/latest/cops.html) は 2012 年に公開され、現在では 500 以上の Cop（ルール）を擁し、Ruby 開発の全規模において標準的なスタイルガイドラインとして機能している。Go 言語における golangci-lint (https://golangci-lint.run/docs/linters/) は 2018 年に登場し、100 以上の個別の Linter を統合的に実行するメガ Linter として、利用可能な Linter の一覧とその設定方法を詳細にドキュメント化している。

第二の分類は、開発体験（DX）と処理速度を極限まで追求した次世代ツール群である。Prettier (https://prettier.io/docs/options) は 2017 年に公開されたフォーマッタであり、「コードスタイルに関する議論を終わらせる」という強烈な哲学のもと、規約（オプション）の数を意図的に数個レベルに制限している。そのドキュメントは個別のルール説明よりも、ツールの哲学（Philosophy）の解説に重きを置いているのが特徴である。近年台頭している Biome (https://biomejs.dev/linter/rules/) は、Rome プロジェクトからフォークして 2023 年に誕生したツールであり、502 ルールを管理しつつ、ESLint と Prettier の役割を単一の高速なツールで代替することを目指している。Python 領域における Ruff (https://docs.astral.sh/ruff/rules/) も同様に、Rust 実装による圧倒的な実行速度を武器に 2022 年に登場し、900 以上の Flake8 互換ルールなどを機械可読性の高いモダンなドキュメント構造で提供している。

第三の分類は、自然言語、ドキュメント、およびマークアップ向けの Prose Linter 群である。CSS や Sass のための Stylelint (https://stylelint.io/user-guide/rules/) は 2015 年に登場し、100 以上のルールを通じてスタイルシートの記述の一貫性を強制している。Markdown 文書に特化した markdownlint (https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) は約 50 のルールを提供し、文書の構造的整合性を保つためのシンプルなフラットドキュメントを採用している。さらに高度な自然言語解析を提供する Vale (https://vale.sh/docs/) は 2017 年に公開され、Elastic や GitLab などのエンタープライズ企業が自社のスタイルガイド（例: 差別的用語の排除、ブランド名の統一）を強制するために活用しており、拡張性の高い YAML ベースのルール定義ドキュメントを特徴とする。日本語コミュニティにおいても広く利用されている textlint (https://textlint.org/docs/rule.html) は 2015 年に登場し、プラグインアーキテクチャを通じて無数の自然言語ルールを適用できるエコシステムを形成している。

第四の分類は、人命に関わるミッションクリティカルなシステムや高度なセキュリティが要求される領域における学術的・高信頼性規格である。C 言語向けの MISRA C:2012 (https://www.misra.org.uk/) は 1998 年に初版が公開されて以来、自動車や航空宇宙産業における絶対的な基準となっており、143 の Rules と 16 の Directives に対し、違反時の例外処理（Deviation）に関する厳格な正当化ドキュメントを要求する。同様に、SEI CERT C Coding Standard (https://wiki.sei.cmu.edu/confluence/display/c/Rules) は 2006 年から続くセキュリティ特化の規格であり、80 以上のルールそれぞれについて、脆弱性の根本原因から解決策までを学術論文レベルの緻密さで記述している。

最後に、これらとは毛色の異なる特殊な領域として adr-kit (https://github.com/kschlt/adr-kit) のような Architecture Decision Record 専用の支援ツールが存在する。これらはプロジェクト固有の文脈に応じてルールを動的に生成し、ドキュメント化するというアプローチを採用しており、継続的なアーキテクチャ管理の新しい形を提示している。本調査は、これら多岐にわたるツールの設計思想を統合し、ADR の Lint 規約として最適な形を模索するものである。

Q2. 必須項目の比較マトリクス

前述の各主要 OSS および規格が、自らの公式 Rule Reference においてどのような情報を「必須項目」として扱っているかを分析し、以下の比較マトリクスとして整理した。この表は、現代の Lint ドキュメントが単なる仕様書から、開発体験を向上させるためのインターフェースへと進化している過程を明確に示している。

ツール名ID / 名前説明 (Desc)RationaleGood/Bad 例SeverityAutofix フラグConfig 例クロスリンクDeprecationカテゴリ分類
ESLint✅ 名前✅✅✅❌ (Config依存)✅ (🔧)✅✅✅ (❄️)✅
Stylelint✅ 名前✅❌ (内包)✅❌✅✅✅✅✅
markdownlint✅ ID+名前✅✅✅❌✅✅❌❌✅ (Tag)
Pylint✅ ID+名前✅❌ (内包)❌ (一部のみ)✅❌❌✅❌✅
RuboCop✅ 名前✅✅ (内包)✅✅✅ (Safe/Unsafe)✅✅✅✅
Prettier✅ 名前✅✅ (Philosophy)❌ (Philosophy)❌N/A✅❌✅❌
Biome✅ 名前✅✅✅✅✅ (Safe/Unsafe)✅✅❌✅
Ruff✅ ID+名前✅❌✅❌✅✅✅✅✅
golangci-lint✅ 名前✅❌❌❌✅✅❌✅❌
Vale✅ 名前✅✅❌✅❌✅❌❌❌
textlint✅ 名前✅❌✅✅✅✅❌❌❌
MISRA C✅ ID✅✅✅ (準拠/非準拠)✅ (Req/Adv)❌❌✅✅✅
CERT C✅ ID✅✅✅ (準拠/非準拠)✅ (L1~L3)❌❌✅❌✅

分析結果から示唆される最も重要な傾向は、静的解析ツールの進化に伴い、単なる「ルールの説明」にとどまらず、「なぜそのルールが必要か（Rationale）」と「具体的な Good/Bad のコードペア」の提示が、事実上の業界標準として定着していることである。特に MISRA C や CERT C のような高信頼性が求められる学術・産業分野の規格においては、ルールが存在する論理的背景（Rationale）と、違反した場合のリスク（例外条件を含む）の明記が厳格に義務付けられている。これは、ルールが形骸化することを防ぐための最も強力な抑止力となるからである。

一方で、近年台頭している Prettier や Biome のような開発体験（DX）を最優先するツールにおいては、対照的なアプローチが見られる。Prettier は「コードスタイルに関する議論そのものを消滅させる」ことを目的としているため、個々のルールに対する微細な Rationale を記述する代わりに、ツール全体のグローバルな Philosophy（哲学）として Rationale を抽象化し、個別の説明を削ぎ落としている。しかしながら、ADR のようなアーキテクチャの意思決定を Lint する場合は、単なるフォーマットの統一ではなく「なぜその構造で記述しなければならないのか」という歴史的経緯が重要になるため、Prettier 型の抽象化は適さない。したがって、ADR Lint のドキュメントにおいては、ESLint や RuboCop、MISRA C が採用しているように、各ルールに対して明確な Rationale と Good/Bad の具体例を明記するアプローチが必須項目であると結論付けられる。

Q3. 章立て・構造の業界共通パターン

Rule Reference の情報アーキテクチャ（目次構成やナビゲーション構造）は、そのツールが管理するルールの総数や、ユーザーがドキュメントを検索する際のメンタルモデルに応じて、いくつかの明確なパターンに収斂していることが確認された。本調査では、業界で共通して見られる代表的な構造を以下の 4 つのパターンに分類する。

第一のパターンは、「カテゴリ別グループ化（Semantic Grouping）」である。ESLint はルールを「Possible Problems」「Suggestions」「Layout & Formatting」といった意図ベースのカテゴリに分割しており、RuboCop も「Style」「Lint」「Metrics」「Security」といった部門（Department）ごとに Cop を整理している。Biome も同様に「Correctness」や「Suspicious」といったグループを採用している。この構造は、ルールの総数が 100 を超えるような大規模なツールにおいて、ユーザーが「特定の種類の問題を解決したい」という目的に基づいてルールを探索する際に極めて有効である。

第二のパターンは、「ID 順によるフラット構造（Flat Indexing）」である。markdownlint は MD001 から MD050 といった連番の ID をルールに付与し、階層を深くせずに単一のページまたはシンプルなリストとして提示している。Pylint も E1101 のような英数字の ID ベースの管理を行っている。このパターンの最大の利点は、ブラウザのページ内検索（Ctrl+F）などを用いた検索性が極めて高いことである。ルールの総数が数十程度までの小規模から中規模なツールに最適化された構造と言える。

第三のパターンは、「哲学・原理原則の先行（Philosophy First）」である。Prettier は前述の通り、ドキュメントのトップレベルでツール自体のスタンスを強烈に宣言し、ルールの微細な分類や説明を極力排除している。これは、設定の柔軟性を意図的に奪うことで運用コストを下げるという特殊なアーキテクチャである。

第四のパターンは、近年のモダンなツールに見られる「セマンティックメタデータ主導（Examples & Metadata First）」である。Ruff や Biome では、長い文章による説明（Rationale）よりも先に、「Safe/Unsafe」といった自動修正に関するフラグ情報や、エラーを引き起こす Bad コードの具体例を視覚的に先行させる構成を採用している。これは、人間がドキュメントを上から下へ熟読するのではなく、IDE のポップアップや AI Agent の文脈として機械的に解釈されることを強く意識した現代的な構造である。

bizlp への推奨構成： bizlp が運用する adr-lint は、現状で 11 ルール（スコープを含め 13 ルール）、将来的にも 30 ルール程度に収まる小規模なエコシステムであると想定される。このスケールにおいて、第一のパターンのような複雑な「カテゴリ別グループ化」を導入することは、ドキュメントの階層を無駄に深くし、認知的負荷を上げるだけのオーバーエンジニアリングとなる。したがって、bizlp に最も適した構造は、「ID 順によるフラット構造（パターン 2）」をベースとしながら、各ルールの内部記述においては AI Agent が解釈しやすいように「メタデータと具体例を先行させる（パターン 4）」ハイブリッド型のアーキテクチャであると推奨する。

Q4. rationale (なぜそのルールが必要か) の記述深度・形式

Lint 規約が時間の経過とともに形骸化し、開発チーム内で無視されるようになる最大の要因は、開発者（あるいは数ヶ月後の過去の自分）が「そもそもなぜこのルールが存在するのか」という背景と理由を忘却することにある。ルールへの順守を促すためには、「これをやってはいけない」という命令だけでなく、その背後にある Rationale（論理的根拠）への深い納得が必要不可欠である。調査の結果、Rationale の記述形式は情報の深度に応じて以下の 4 段階に分類できることが判明した。

第一の形式は、「1 行説明（One-liner）」である。「このルールは未使用の変数を禁止します」といったように、ルールが何をするか（What）の事象記述のみにとどまり、なぜそれが必要か（Why）は説明しない。これは初期の Linter に多く見られた形式であるが、現代の複雑な開発環境においては不十分とされている。

第二の形式は、「3 文構造(問題 / 解決 / 代替または影響)」である。ESLint のドキュメント等で標準的に用いられているアプローチであり、「どのような問題やバグを引き起こすか(Problem)」「このルールがそれをどう防ぐか(Solution)」「代わりにどのようなコードを書くべきか(Alternative/Impact)」を論理的に簡潔に記述する。この形式は認知的負荷が低く、かつ説得力が高い。

第三の形式は、「Anti-pattern と推奨のペアによる暗黙的 Rationale」である。RuboCop の一部のドキュメントのように、文章による理由の説明を最小限に抑え、代わりにコードの Before/After（Bad/Good）を視覚的に対比させることで、「なぜ元のコードが悪いのか」を直感的に悟らせるアプローチである。

第四の形式は、「学術論文・外部規格への引用付き解説」である。CERT C コーディングスタンダードのように、ルールの背景にある脆弱性の根本原因（Root Cause）や、CWE（Common Weakness Enumeration）などの外部規格へのポインタを含め、セキュリティインシデントの具体的なリスクと紐付けて詳細に解説する形式である。

bizlp への推奨形式： 1 人法人というリソースが限定されたスケールにおいて、第四の形式のような過度な学術的記述や長大なドキュメントの維持は、運用上の多大なオーバーヘッドとなる。しかし一方で、第一の形式（1 行説明）を採用してしまうと、数ヶ月後に自身で策定した ADR（例えば ADR-0023 の命名規則や必須セクションの根拠）の背景を忘れ、ルールの存在意義を疑うリスクが極めて高い。

したがって、bizlp に最適なアプローチは、**「なぜこのルールがないと bizlp のアーキテクチャ管理が破綻するのか（アーキテクチャ上の影響）」を明確に記述する「3 文構造（Problem, Solution, Impact）」**を標準フォーマットとして採用することである。この構造により、将来の自身や AI Agent に対してルールの正当性を端的に説明することが可能となる。

Q5. PASS / FAIL の具体例の提示形式

ドキュメントにおける PASS / FAIL の具体例の提示は、人間の開発者がルールを即座に理解するための手段であると同時に、AI Agent（LLM）が文脈を学習し、Few-shot prompting としてコードを生成・修正するための最重要データとして機能する。具体例の提示形式は、以下の 3 つの主要なパターンに大別される。

第一の形式は、「分離コードブロック方式」である。ESLint に代表されるこの形式は、✅ 正しいコード（Good）と ❌ 誤ったコード（Bad）を完全に別々の Markdown コードブロックとして明示する。このアプローチは機械可読性が極めて高く、LLM が正例と負例の境界を明確にパースできるという点で、現代的なドキュメントアーキテクチャの最適解の一つとされている。

第二の形式は、「Diff 形式」である。Git の差分表示のように + と - を用いて変更箇所を直接表現する。人間にとってはどこが修正されたのかが一目で分かるという利点があるが、コードをそのままコピー＆ペーストして実行できないため、自動化スクリプトや一部の単純な AI プロンプト抽出においてはノイズとなる課題がある。

第三の形式は、「ペア表記（コメント併記方式）」である。RuboCop で頻繁に見られるこの形式は、単一のコードブロック内に # bad と # good というインラインコメントを挿入し、連続してコードを提示する。同一ブロック内で比較できるため視認性は高いが、Markdown やテキストベースの仕様書を対象とする Lint の場合、ドキュメント言語のコメント構文に依存するため汎用性に欠ける。

bizlp への推奨形式： ADR は本質的に Markdown 形式で記述されるドキュメントである。Markdown の中に Markdown の Lint 例をインラインコメントで記述すること（第三の形式）は、エスケープやパースの観点から非常に困難かつ不自然である。さらに、AI Agent に「この正しい形式で ADR を出力せよ」という厳格なコンテキストを与えるためには、正例と負例が論理的に完全に分断されている必要がある。

結論として、bizlp の ADR Lint 規約ドキュメントにおいては、**「分離コードブロック方式」**を強く推奨する。具体的には、Markdown のコメントとして <!-- ❌ Bad --> と <!-- ✅ Good --> を各ブロックの直前に配置し、物理的に独立したコードブロックを使用することで、人間と AI の双方にとって誤読の余地がない厳密な仕様提示が可能となる。

Q6. deprecation / 追加・削除 changelog 管理慣習

ツールの成熟やプロジェクトの要件変更に伴い、過去のルールを非推奨（Deprecation）にしたり削除したりする際のライフサイクル管理は、運用基盤の安定性を保つための重要なテーマである。業界事例を調査すると、プロジェクトの規模に応じた明確な管理慣習が存在する。

大規模なエコシステムを持つ Stylelint などのツールでは、破壊的変更や非推奨化の履歴を管理するために「専用の Changelog 章」や「マイグレーションガイド」という独立したページを用意している。これにより、数千規模のユーザーがアップグレード時の影響を事前に調査できる。一方、ESLint のようなツールは、非推奨となったルールを物理的に削除するのではなく、各ルールのドキュメント内に ❄️（Frozen / Deprecated）マークを付与し、目次の「Deprecated Rules」セクションに退避させるアプローチをとっている。さらに、golangci-lint では、メタデータレベルで削除された Linter を管理し、ユーザーが古い設定を使用した場合に実行時の WARN メッセージとして「この Linter は削除された」旨を通知するフェイルセーフ機構を実装している。

bizlp への推奨形式： bizlp は 1 人法人であり、現状 11 ルール、将来的に拡張しても 30 ルール程度という限られたスコープで運用されている。この規模において、外部ユーザー向けの巨大な Changelog ページや、詳細なマイグレーションガイドの作成・維持を行うことは、明らかな過剰設計（YAGNI: You Aren't Gonna Need It）である。

したがって、最小かつ最も効果的な実装として、Markdown の YAML Frontmatter にフラグを持たせることを推奨する。具体的には、各ルールの先頭に deprecated: true および必要に応じて superseded_by: "新しいルールID" というシンプルなキー・バリュー値を埋め込む。このメタデータを AI Agent が読み取ることで、Agent が古いフォーマットの ADR を検知した際に、「このルールは廃止され、新しいルールに置き換わっているため、一括でフォーマットを更新しますか？」という自動修正のプロンプトを自律的に構成することが可能となる。

Q7. fixable / autofix フラグの記述慣習

コードの自動修正（Autofix）が可能かどうかというメタデータは、現代の静的解析ツールにおいて、開発者の時間を節約するための最も価値のあるシグナルである。

ESLint では、自動修正が可能なルールには 🔧（レンチ）アイコンがドキュメント上で明示され、CLI の --fix オプションを用いることで抽象構文木（AST）レベルの安全な変換が適用されることが保証されている。一方、Biome ではこの概念をさらに一段階進化させ、自動修正を「Safe（安全）」と「Unsafe（安全とは限らない）」の二つに厳密に分類している。Safe な修正はプログラムの意味論（Semantics）を絶対に変更しないことが保証されており、保存時の自動適用が可能である。対して Unsafe な修正は、動作が変わるリスクがあるため開発者の手動レビューを必ず要求する。Prettier に至っては、全てのフォーマット変更が強制的に自動適用されるアーキテクチャであり、フラグという概念自体が存在しない。

bizlp への推奨形式： 現状の scripts/adr-lint.mjs には Autofix 機能が実装されていないとのことだが、ドキュメントの設計段階において fixable: false | "safe" | "unsafe" というフラグ枠を即座に導入することを強く推奨する。

その理由は、将来的なツールの拡張性のためだけではない。Claude 3.5 Sonnet や Gemini のような AI Agent に Lint エラーの出力を渡して修正を依頼する際、このフラグが AI の行動に対する強力な境界条件（Guardrails） として機能するからである。Agent がドキュメントを読み込み、ある違反ルールが fixable: "safe" であると認識すれば、Agent にファイルの自律的な上書きを許可することができる。逆に fixable: "unsafe" または false と定義されていれば、Agent は「勝手に修正せず、修正案の提示にとどめて人間のレビューを待つ」という安全な振る舞いを遵守するようになる。

Q8. CI 統合・severity 説明の典型

Lint ツールが検出した違反に対する Severity（深刻度）の定義は、Continuous Integration（CI）パイプラインの振る舞いを決定づけ、開発プロセスのゲートキーパーとしての役割を果たす。

ESLint では、ルールの設定として主に error、warn、off の 3 段階が用意されている。error に設定された違反が一つでも存在する場合、プロセスの終了コードは 1（Exit 1）となり、CI はフェイルし、プルリクエストのマージがブロックされる。一方、warn は警告を標準出力に表示するものの、終了コードは 0（Exit 0）のままであり、CI を通過させる。これは、既存の巨大なレガシーコードベースに新しいルールを段階的に適用していく際のリファクタリング手法として多用される。Biome においても同様に、error は CI をブロックし、warn は --error-on-warnings フラグが明示的に渡されない限りブロックしないという設計となっている。

bizlp への推奨形式： bizlp には既に ADR-0038 や ADR-0049 において、error（例: 必須メタデータの欠如）と warn（例: レガシーな Scope 記述）という 2 段階の Severity 方針が存在している。この方針は業界標準の振る舞いと完全に一致しており、変更する必要はない。

Rule Reference ドキュメントにおいては、冒頭のインデックス部分で以下のように Severity と CI 統合の振る舞いの関係を明示的に定義することを推奨する。

  • Error: アーキテクチャの整合性を維持するための必須要件。違反した場合、GitHub Actions 等の CI は直ちにブロックされ、マージは不可となる。
  • Warn: 非推奨となったレガシーな規約（scope-meta-legacy 等）。CI の通過は妨げないが、技術的負債として蓄積されるため、AI Agent による定期的なクリーンアップ・バッチ処理の対象とする。

Q9. AI Agent (Claude / Gemini) が解釈しやすい構造の特性

近年の大規模言語モデル（LLM）の進化により、API やツールのドキュメントの「読者」は、人間の開発者だけでなく、自律的にコードを生成・修正する AI Agent へと劇的に拡大している。AI Agent がドキュメントを正確に解釈し、確実にタスクを実行できるようにするための「Agent-friendly」なドキュメント設計には、いくつかの重要な特性が求められる。

第一の特性は、マシンのためのエントリポイントとなる llms.txt プロトコルの採用である。Agent に対して「システムのどこにどのような情報が存在するか」を示す目次のような役割を果たし、Agent は複雑なナビゲーションを巡回することなく、必要な高価値なドキュメントへ直接アクセスできる。

第二の特性は、情報アーキテクチャにおける「プログレッシブ・ディスクロージャー（Progressive Disclosure：段階的開示）」パターンの実装である。AI Agent のコンテキストウィンドウには上限があり、また不要な情報を大量に詰め込むことは「Context Rot（コンテキストの劣化）」を引き起こし、出力精度の低下やハルシネーションの原因となる。これを防ぐため、最初は軽量なメタデータのみのリスト（Layer 1: Discovery）を提供し、Agent が特定のタスクに該当する機能を発見した場合にのみ、詳細な手順やルール定義（Layer 2: Activation）をフェッチさせる設計が必要となる。

第三の特性は、YAML Frontmatter や JSON Schema による構造化されたメタデータと、明確な境界条件の明示である。Agent は自由形式の散文よりも、型付けされたデータや、「Always do（必ずやる）」「Ask first（事前に人間に尋ねる）」「Never do（絶対やらない）」といった厳密な制約（Boundaries）を正確に遵守する傾向がある。

bizlp への推奨構造： 1 人法人と AI Agent の併用ワークフローにおいて、これらを踏まえた最適なアプローチは、**「Agent Context に特化した Frontmatter 駆動設計とプログレッシブ・ディスクロージャーの組み合わせ」**である。

具体的には、Rule Reference のトップレベルに全 11 ルールの ID、Severity、1行 Description をまとめたインデックス表（Discovery Layer）を配置する。そして、各ルールの詳細は物理的に分割するか、厳密な見出し構造で分離し、各ルールの冒頭に YAML Frontmatter 的な構造化メタデータ（severity, fixable, deprecated）を持たせる。AI Agent のシステムプロンプトには、「Lint エラーに遭遇した際は、まずインデックスを参照し、関連するルールの Rationale と Good/Bad 例だけを部分的にフェッチして修正案を作成せよ」という指示を組み込む。これにより、トークン消費を最小限に抑えつつ、極めて精度の高い自動修正ループを確立できる。

Q10. 1 人法人スケールでの省略可能項目の判定

業界標準とされる Linter のドキュメントには、数千人のコントリビュータと数百万のユーザーを抱える大企業や巨大 OSS エコシステムを前提とした機能や要件が多数含まれている。1 人法人（Solo Founder）のスケールにおいて、これらすべてを実装・維持することは、アジリティを損なう致命的なオーバーヘッドとなる。現状の 11 ルール（将来的に 30 ルール程度への拡張を想定）の規模において、構築すべき「MVP 必須項目（Keep）」と、切り捨てるべき「省略可能項目（Omit）」を明確に判定する。

【 MVP 必須項目リスト (Keep) 】

  • Rule ID (ルール名): numbered-header のような一意の識別子。AI と人間がコミュニケーションする際の共通言語となる。
  • Severity (深刻度): error または warn。CI のブロック判定や AI Agent の優先順位付けに直結する。
  • Description (概要説明): 1 行で表されるルールの内容。インデックス（Discovery Layer）として不可欠である。
  • Rationale (論理的根拠): 「なぜこのルールが必要か」を 3 文構造（問題 / 解決 / 影響）で示す。個人開発におけるルールの形骸化を防ぐ最重要要素である。
  • PASS / FAIL の具体例: <!-- ✅ Good --> と <!-- ❌ Bad --> で論理的に分離されたコードブロック。AI Agent への Few-shot プロンプトとして直接機能する。
  • Related ADRs (関連する意思決定へのリンク): ADR-0023 などの根拠となる元ドキュメントへのクロスリンク。文脈の追跡性を担保する。
  • Fixable / Autofix フラグ: safe, unsafe, false。AI Agent の自律的なファイル書き換え許可をコントロールする境界条件（Guardrails）となる。

【 省略可能項目リスト (Omit) 】

  • 厳密な SemVer による Deprecation 履歴管理: 大規模なライブラリが後方互換性を保証するために用いる「バージョン X.Y で非推奨化」といった詳細な履歴は不要である。YAML Frontmatter の deprecated: true フラグの存在だけで十分機能する。
  • 詳細なマイグレーションガイド: 古いルールから新しいルールへの移行手順を長文で用意する必要はない。AI Agent が superseded_by フラグと fixable フラグを解釈できれば、LLM に任せるだけで自動的なコード修正・移行が完了する。
  • 大規模なカテゴリ分類 (Grouping): ルール数が 30 未満のスケールにおいて、「Style」「Metrics」のような階層構造を作ることは、かえって情報の検索性を低下させる。フラットなリスト構造で十分である。
  • 複雑な Config オプションの例: ルールの挙動をパラメータで細かく制御する巨大な設定ファイル（例: eslint.config.js の複雑なオプション）の記述はアンチパターンである。アーキテクチャの複雑化を避けるため、ルールの挙動は静的に固定することが望ましい。

Q11. bizlp 11 ルールへの推奨章立て案

前章までの徹底した調査とアーキテクチャ分析に基づき、bizlp の docs/_internal/05_how-to/adr-lint_rules.md に適用すべき最終的な推奨構造と Markdown のテンプレート案を提示する。この構成は、AI Agent のプログレッシブ・ディスクロージャーを前提としつつ、人間の開発者にとっても高い可読性を維持する設計となっている。

推奨されるドキュメントの章構成 (3 節構造)

# ADR Lint Rule Reference

ADR の品質とアーキテクチャの整合性を担保するための静的解析（scripts/adr-lint.mjs）規約一覧です。
AI Agent は本インデックスを参照し、Lint 違反発生時に該当ルールの詳細定義をフェッチ（Fetch）してください。

## 1. Severity Levels (深刻度の定義と CI 統合)

- **Error**: アーキテクチャの整合性に関わる必須要件。違反時、CI（GitHub Actions 等）は直ちに失敗し、マージをブロックします。
- **Warn**: 非推奨のレガシー規約。CI は通過しますが、技術的負債となるため AI Agent のクリーンアップ対象とします。

## 2. Rule Index (Discovery Layer)

※AI Agent への指示: 本リストから対象ルールの ID を抽出し、必要に応じて次節の詳細情報を検索すること。

| Rule ID | Severity | Autofix | 根拠 ADR | Description |
|---|---|---|---|---|
| numbered-header | Error | Safe | ADR-0023 | ヘッダに採番プレフィックスが存在すること |
| context-section | Error | Unsafe | ADR-0023 | Context セクションが存在すること |
| corrigendum-marker | Warn | Safe | ADR-0031 | 訂正履歴のマーカーが存在すること |
| scope-meta-legacy | Warn | Safe | ADR-0049 | レガシーな Scope 記述（非推奨） |
| （※計13ルールをカテゴリ分けせず、フラットに羅列する） |  |  |  |  |

## 3. Rule Details (Activation Layer)

（※各ルールの詳細を以下に展開する。AI がパーシングしやすいよう、Frontmatter 的なメタデータをリスト形式で冒頭に配置する）

### numbered-header

- **Severity**: error
- **Fixable**: safe (Agent による自律的な自動修正を許可)
- **Related ADR**: [ADR-0023](../02_architecture/ADR-0023.md)
- **Deprecated**: false

#### Rationale

**[Problem]** ドキュメントのファイル名やメタデータ領域にのみ番号が存在すると、テキスト全文検索時や外部ツールで参照した際にコンテキストが完全に喪失する。
**[Solution]** トップレベルの H1 ヘッダの先頭には、必ず ADR-XXXX: というプレフィックスの付与を強制する。
**[Impact]** これにより、LLM や Agent がドキュメントを細かいチャンクに分割・抽出した際にも、テキスト片単体からアーキテクチャ決定事項の出所を確実に追跡可能になる。

#### Examples

**❌ Bad (Fail)**
` ` `markdown
# 認証プロバイダの選定
Date: 2026-05-17
Status: Accepted
` ` `

**✅ Good (Pass)**
` ` `markdown
# ADR-0050: 認証プロバイダの選定
Date: 2026-05-17
Status: Accepted
` ` `

bizlp 採用推奨案

bizlp の ADR Lint 規約（13 ルール）は、AI Agent の文脈解釈に最適化された**「プログレッシブ・ディスクロージャー型」のフラットな 3 節構造（定義・一覧・詳細）**を推奨する。各ルールは機械可読なメタデータ（Severity, Fixable, Related ADR）を冒頭に持ち、Agent が一覧から必要な規約のみを文脈展開する構成とする。

必須項目は「1 行説明」「3 文構造の Rationale（問題/解決/影響）」「論理ブロック分離型の PASS/FAIL 例」に厳選し、マイグレーションガイド等の大企業向け機能は MVP 化して省略する。特に、関連 ADR への静的リンクによる「根拠の追跡性」と、将来の AI による修正判断基準となる Fixable: safe/unsafe フラグの導入は、規約の形骸化を防ぎ、自律的な運用を可能にする要の工夫である。