RQ-051 bizlp ADR Lint Rule Reference 設計のための業界ベストプラクティス調査（Claude Opus 4.7 結果）

TL;DR (本レポートが導いた 3 結論)

• 10 節構成 + 各ルール 10 必須項目の YAML+Markdown ハイブリッドを採用すべき。1 ページ集約型 (markdownlint 流) を骨格とし、各ルール冒頭に YAML メタ (id / severity / category / since / status / fixable) を置く RuboCop/Anthropic Skill 流の構造化メタを併用する。これにより AI Agent (Claude / Cursor) は決定論的に処理でき、人間も 1 画面で全体俯瞰できる。
• rationale は Ruff 形式の 3 文構造 (What it does / Why is this bad? / Example) を 1 ルール 3-5 行に短縮、例示は ❌ FAIL → ✅ PASS の 2 Markdown ブロック (ESLint/CERT 流の Bad/Good ペア)。詳細根拠は ADR 本体に委ね Rule Reference からは 1 行リンクのみ — 二重メンテを回避し、1 人法人の運用負荷を最小化する。
• Deprecation 履歴 / Migration guide / Risk Assessment / Bibliography は省略可能。1 人法人 + 30 ルール未満のスケールでは、ESLint/RuboCop 流の SemVer 厳格化や MISRA C 流の引用付き rationale は過剰設計。代わりに since: ADR-XXXX メタ 1 行 + 末尾 Changelog 節 + 末尾 Legacy 節の 3 か所だけで履歴管理が完結する。

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

同名異プロジェクトに注意: 「adr-kit」は kschlt 版 (Python + MCP + lint enforcement) と rvdbreemen 版 (Claude Code plugin) の少なくとも 2 つが並立。markdownlint も Ruby 版 (MD001-MD042) と DavidAnson 版 (MD001-MD060) で別系統。

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

凡例: ✅ あり、△ 部分的、— なし、n/a 該当しない

観察:

1. ID + description + 具体例 + severity + rationale は 事実上全ツールが必須として備える ("five universal fields")。
2. fixable フラグ・config 例・関連ルールリンクは中規模以上でほぼ全採用。
3. Deprecation 履歴は ESLint・Stylelint・RuboCop が SemVer 連動で厳格化、一方 MISRA / CERT は Amendment 連動。
4. Risk Assessment (Likelihood / Severity / Repairable) は CERT 固有で、安全クリティカル領域特有の項目。

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

パターン A: カテゴリ別グループ + 各ルール 1 ページ (ESLint / Biome / Stylelint)

• インデックスページに「Possible Problems / Suggestions / Layout & Formatting / Deprecated / Removed」のカテゴリ別グループ + 個別ルール詳細ページの 2 階層。
• 絵文字バッジ (Recommended / 🔧 Fixable / 💡 Has Suggestions) で一覧性確保。
• 個別ページ定型: タイトル → リード文 → Rule Details → Options → When Not To Use It → Version ("This rule was introduced in ESLint x.x.x") → Resources (Rule source / Tests source へのリンク)。

パターン B: 全ルール 1 ページ集約 + アンカー (markdownlint / 小規模ツール)

• RULES.md 1 つに ## MD### - rule name 形式で全 60 ルールを連結、スクロール 1 ページ。
• 各ルールは「triggered when / fix / Rationale」の 3 セクション固定、Rationale はインラインで「Rationale:」と書く流儀。
• 〜60 ルール規模に最適。

パターン C: ID 階層 + 大量サブページ (CERT C / MISRA C)

• 14 chapter (PRE / DCL / EXP / INT … CON / MSC / POS / WIN) × 数十 rule、各 rule が独立ページ。
• 個別ページ定型: タイトル + ID → Description → Noncompliant Code Example → Compliant Solution → Exceptions → Risk Assessment (Likelihood / Severity / Remediation Cost / Priority / Level) → Related Vulnerabilities → Bibliography。
• 数百〜数千規模・規制準拠ツール連携前提。

パターン D: Department/Tag ベース YAML 駆動 (RuboCop / golangci-lint)

• 規約定義そのものが YAML (config/default.yml)。Description / Enabled / VersionAdded / VersionChanged / Safe / SafeAutoCorrect を構造化メタとして保持。
• ドキュメントは YAML から自動生成、SSoT (Single Source of Truth) はコード/YAML。

パターン E: Frontmatter + Markdown 本文の 2 層 (Anthropic Skill / Cursor Rules / AGENTS.md / adr-kit)

• 機械可読 YAML frontmatter (name / description / metadata) + 人間向け Markdown 本文。
• Progressive disclosure (L1: metadata 常時ロード / L2: SKILL.md 本文 ≤500 行 起動時ロード / L3: bundled references 要求時ロード) で AI Agent のコンテキスト消費を抑制。

bizlp への推奨

パターン B (1 ページ集約) を骨格に、各ルールに YAML 構造化メタ (パターン D 由来) を加えるハイブリッド。理由:

• 現状 13 ルール・将来 30 ルール程度のスケールでは、1 ページ集約のスクロール可読性が高い (markdownlint Ruby 版が前例)。
• カテゴリは bizlp の lint 特性で 5 ジャンル (Structure / Content / Metadata / Status / Legacy) に分け、目次から飛ぶ構造。
• アルファベット順より 「重要度高い順 + カテゴリ内 ID 昇順」 が ADR ドメインに適合。
• Deprecated は冒頭ではなく 末尾の Legacy 節にまとめる (ESLint 流)。
• examples-first ではなく description-first (rationale → bad/good)。Markdown ドキュメントは「読む」より「探す」が優位。

Q4. rationale の記述深度・形式

bizlp への推奨: Ruff の 3 文構造 (What / Why / Alternative) + ADR-XXXX への 1 行リンク。

理由:

• 1 人法人で運用負荷を最小化しつつ、AI Agent (Claude / Cursor) が解釈しやすい順序 (Ruff の ruff rule コマンド出力と同形)。
• 「なぜ必要か」の詳細根拠は ADR 本体に既に書かれているため、Rule Reference 上は 1〜3 文要約 + クロスリンクで十分。これにより rationale の二重メンテを回避。
• MISRA C 並みの引用付き形式は過剰設計、規制対応の必要なし。

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

bizlp への推奨: 「❌ FAIL → ✅ PASS の順、Markdown コードブロック (```markdown) で 2 ブロック、見出しは ### ❌ FAIL / ### ✅ PASS」。

理由:

• ADR は Markdown 文書なので、FAIL/PASS 例も Markdown ブロックで提示、シンタックスハイライト互換性を保てる。
• 絵文字 (❌ / ✅) は ESLint Rule Reference の慣習を踏襲、視覚的スキャン性を向上。
• diff 形式は構造的 lint には冗長 (Prettier 系の formatter 向け)。

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

bizlp への推奨 (最小実装):

• (a) 各ルール枠に since: ADR-XXXX / status: active|deprecated|legacy の YAML メタ 1 行を埋め込む (各ルールで完結)。
• (b) ドキュメント末尾に「Changelog」「Legacy / Deprecated Rules」の 2 節を追加 (現状 scope-meta-legacy は warn なのでここに移動)。
• (c) ADR 連番がそのまま since になるので SemVer の二重管理は不要。bizlp は ADR 番号が SemVer の役割を果たす。
• migration guide は当面不要 (1 人法人スケール)、必要になった時点で「Legacy Rules」節に「Replaced by: rule-name (ADR-XXXX)」の 1 行を足すだけで十分。

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

bizlp への推奨:

• 将来 autofix を導入する可能性が低くなく、また RuboCop / Biome / Ruff の safe/unsafe 区別がベストプラクティス化している。
• 各ルール枠に fixable: no (現状) という 1 行メタを今から入れておく。導入時に fixable: safe / fixable: unsafe へ書き換えればよい。
• 「枠を作らず後追いで全 30 ルールに追記」より、「最初から枠を置き 30 件中ほぼすべてが no」のほうがマイグレーション安全。
• ただし Fixable という独立節は過剰、YAML メタ 1 行で十分。

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

bizlp への推奨 (error / warn の 2 段階):

• error = CI fail (PR merge ブロック)、現状 11 ルール (将来も大半)。
• warn = CI 通過、ローカル警告のみ。現状 2 ルール (corrigendum-marker, scope-meta-legacy)。
• ドキュメント内で 「Severity の凡例」を冒頭 1 節置く (Biome の説明文を踏襲):

• error: CI を fail させる。マージ前に必ず修正。
• warn: CI は通過する。後日修正もしくは記録のための flag。

• 各ルール枠に severity: error / severity: warn の YAML メタ 1 行を置く。

将来 info (例: お薦め記述スタイル) を導入する余地は残すが、現時点では 2 段階で十分。

Q9. AI Agent が解釈しやすい構造の特性

調査から抽出した 4 つの設計原則:

1. 機械可読メタを冒頭に置く: Anthropic Skill / Cursor Rules / adr-kit / AGENTS.md はいずれも YAML frontmatter で name / description / 適用条件を構造化。Anthropic Engineering blog いわく Skill の description フィールドは「This metadata provides just enough information for Claude to know when each skill should be used without loading all of it into context」(第一級情報)。
2. Progressive disclosure: Anthropic 公式 Skill authoring best practices に「Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier」と明記。3 階層:
   • L1 metadata (常時ロード、name + description)
   • L2 SKILL.md body (≤500 行、起動時ロード)
   • L3 bundled references (要求時のみロード、無制限サイズ)
3. 言及順は「機械→人間」: 各ルールの先頭に id / severity / fixable / since を 4 行で固定し、その後に人間向け説明。AI が見出し直下のメタを最初に読むので、決定論的に処理できる。
4. AGENTS.md / Cursor Rules / Claude Skills 互換: OpenAI 公式発表 (openai.com/index/agentic-ai-foundation/) によれば、「AGENTS.md は 2025 年 8 月のリリース以降、Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules, VS Code を含む 60,000 以上のオープンソースプロジェクトとエージェントフレームワークに採用された」。bizlp docs/_internal/05_how-to/adr-lint_rules.md を AGENTS.md から相互リンクすれば、AI 連携が自然に成立。

bizlp への推奨構造:

---
id: numbered-header
severity: error
fixable: no
since: ADR-0023
status: active
category: structure
---

• 本文セクション (Description / Rationale / FAIL / PASS / Related ADRs)。

docs/_internal/05_how-to/adr-lint_rules.md 全体は 500 行以下 を目標 (Anthropic Skill 推奨)。将来 30 ルールで超過する場合は、カテゴリ別サブファイル (adr-lint_rules/structure.md 等) に Progressive disclosure 化する。

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

MVP 必須項目 (10 項目):

1. ルール ID (kebab-case、既存 13 ルール踏襲)
2. Severity (error / warn)
3. Since (どの ADR で導入されたか、SemVer の代替)
4. Status (active / deprecated / legacy)
5. Description (1〜2 行)
6. Rationale (Ruff 形式 3 文構造、ADR への 1 行リンク)
7. FAIL 例 (Markdown コードブロック)
8. PASS 例 (Markdown コードブロック)
9. Related ADRs (関連 ADR 番号リスト)
10. Category (Structure / Content / Metadata / Status / Legacy の 5 種)

省略可能項目 (現時点では不要、必要時に追加):

1. Options / Parameters (現状 ADR lint には設定オプションなし、不要)
2. Migration guide (1 人法人スケールでは過剰、移行は ADR 本体で記述)
3. Risk Assessment (CERT C 由来、ADR ドメインには不要)
4. Bibliography / 学術引用 (MISRA C 由来、ADR ドメインには過剰)
5. 多言語版 (日本語のみで十分)
6. 詳細な changelog ページ (末尾 1 節で十分、SemVer 非運用)
7. API スキーマドキュメント (内部ツールで対外 API なし)
8. Plugin 開発ガイド (外部 contributor なし)
9. Deprecated Rules 専用ページ (末尾 1 節で十分)
10. Risk Assessment テーブル (CERT C 流の Likelihood × Severity × Remediation Cost × Priority × Level の 5 軸メタは過剰)

注: fixable: no のメタ 1 行は省略候補だが、将来 autofix 導入時の追記コストを下げるため MVP に含めるのが安全 (Q7 推奨と整合)。

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

docs/_internal/05_how-to/adr-lint_rules.md の章構成 (10 節)

---
title: ADR Lint Rule Reference
related_adrs: [ADR-0023, ADR-0024, ADR-0030, ADR-0031, ADR-0032, ADR-0036, ADR-0038, ADR-0039, ADR-0049]
since: ADR-0038
status: living
last_rule_id_assigned: scope-meta-legacy
---

# ADR Lint Rule Reference

## 1. このドキュメントの目的とスコープ
- 既存 13 ルールの根拠を 1 か所に集約
- 各ルールの ID/Severity/根拠 ADR を機械可読に提示
- AI Agent (Claude / Cursor / Gemini) がそのまま読める Progressive disclosure 構造

## 2. Severity の凡例
- `error`: CI を fail させる (`scripts/adr-lint.mjs` exit code ≠ 0)
- `warn`: CI は通過、ローカルで警告のみ

## 3. カテゴリの凡例
- **Structure** (見出し / セクション構造): numbered-header, context-section, decision-section, template-sections
- **Content** (本文の最低品質): no-placeholder, min-length, filename-pattern
- **Metadata** (frontmatter / メタ情報): kruchten-type-meta, implementation-status-meta, scope-meta
- **Status** (ADR ライフサイクル): confirmation-section, corrigendum-marker
- **Legacy** (互換性のための過渡的ルール): scope-meta-legacy

## 4. ルール一覧 (サマリ表)
| ID | Severity | Category | Since | Status |
|---|---|---|---|---|
| numbered-header | error | Structure | ADR-0023 | active |
| context-section | error | Structure | ADR-0023 | active |
| ... | ... | ... | ... | ... |

## 5. Structure カテゴリ
### 5.1 numbered-header
### 5.2 context-section
### 5.3 decision-section
### 5.4 template-sections

## 6. Content カテゴリ
### 6.1 no-placeholder
### 6.2 min-length
### 6.3 filename-pattern

## 7. Metadata カテゴリ
### 7.1 kruchten-type-meta
### 7.2 implementation-status-meta
### 7.3 scope-meta

## 8. Status カテゴリ
### 8.1 confirmation-section
### 8.2 corrigendum-marker

## 9. Legacy / Deprecated カテゴリ
### 9.1 scope-meta-legacy

## 10. Changelog
- ADR-0023: ルール 1-6 (numbered-header / context-section / decision-section / no-placeholder / min-length / filename-pattern) を導入
- ADR-0024: template-sections を追加
- ADR-0030: kruchten-type-meta を追加
- ADR-0031: corrigendum-marker (warn) を追加
- ADR-0032: implementation-status-meta を追加
- ADR-0036: confirmation-section を追加
- ADR-0038: Rule Reference 設計の基本方針
- ADR-0039: lint ツール採用方針
- ADR-0049: scope-meta (error) + scope-meta-legacy (warn) を追加

各ルールテンプレ (1 ルールあたりの記述形式、numbered-header の例)

### 5.1 numbered-header

```yaml
id: numbered-header
severity: error
category: structure
since: ADR-0023
status: active
fixable: no
```

**Description**
ADR ファイルの先頭は `# ADR-NNNN: タイトル` 形式の H1 見出しで始まる必要がある。

**Rationale**
- *What it does*: 全 ADR のファイル先頭 H1 の形式を `# ADR-NNNN: <title>` に統一する。
- *Why is this bad?*: ADR 番号が見出しから機械的に抽出できない場合、index 生成や AI Agent の参照 (例: 「ADR-0042 を参照」) が破綻する。Nygard 形式 ADR の慣習にも準拠 (cf. ADR-0023)。
- *Alternative considered*: frontmatter で番号管理する案は、Markdown viewer での視認性低下と二重管理リスクから却下。

**❌ FAIL**

```markdown
# ADR: Use React Query
```

**✅ PASS**

```markdown
# ADR-0042: Use React Query for data fetching
```

**Related ADRs**: ADR-0023 (起点), ADR-0038 (Rule Reference 方針)

関連 ADR とのクロスリンク方針

1. 各ルール枠の since: メタ は根拠 ADR を 1 つだけ指定 (最初に導入された ADR)。
2. Related ADRs 節 に追加的なクロスリンクを列挙 (重複可)。
3. ADR-0038 / ADR-0049 の方針を Rule Reference に転記しない (二重管理回避)。代わりにヘッダの related_adrs: で参照のみ。
4. ADR 本体から Rule Reference への逆リンクは推奨しない (ADR は append-only 原則、Rule Reference は living document なので一方向リンクが安全)。

Changelog / Deprecation 枠の方針

• 末尾 1 節 (第 10 節) に時系列で「ADR-XXXX で追加 / 廃止」を 1 行ずつ追記。
• Deprecated ルールは category=Legacy 節 (第 9 節) に移動、status: legacy に変更、本文に「Replaced by: rule-name (ADR-XXXX)」の 1 行を追加。
• ルール削除は基本行わない (ESLint の deprecation policy に準拠)。scripts/adr-lint.mjs から removed されても、ドキュメントには履歴として残す。

Recommendations (段階的導入計画と判断基準)

Stage 1 (即時、1〜2 日)

1. 既存 7 ADR (ADR-0023/0030/0032/0036/0038/0039/0049) のうち、ルール定義部分のみを抽出し、上記章立てに沿って docs/_internal/05_how-to/adr-lint_rules.md に転記。
2. 各 ADR 側は変更せず、Rule Reference 側で since: ADR-XXXX メタを 1 行付けるだけにする (ADR-0038 の append-only 方針を尊重)。
3. 既存 13 ルール × 上記テンプレ (約 30 行 × 13 = 約 400 行、500 行制約内) で完結。

Stage 2 (Stage 1 完了後 1 週間以内)

1. AGENTS.md (なければ新規作成) と CLAUDE.md / .cursor/rules/ から、Rule Reference への 1 行リンクを張る (See @docs/_internal/05_how-to/adr-lint_rules.md for ADR lint rule reference)。
2. scripts/adr-lint.mjs の各ルール implementations 内に、対応する Rule Reference アンカーへの URL を meta.url 相当のコメントで埋め込む (ESLint の meta.docs.url 流)。

Stage 3 (ルール数 20 件 / 500 行超過時)

1. 判断基準: 全体行数が 500 行を超えたら、カテゴリ別サブファイル化 (adr-lint_rules/structure.md 等) に Progressive disclosure 移行。
2. ルール数 30 件超過、または autofix 導入時には、fixable: メタの実値化 + 「Autofix Safety」節を末尾に追加。

Stage 4 (1 人法人スケールを超えた場合のみ)

1. 判断基準: 外部 contributor が 1 人でも入った、または bizlp の lint 規約を他社が参照するようになったら、ESLint 流の「個別ルール 1 ページ」構造 (パターン A) に分割。それまでは過剰設計。

採用しない選択肢 (積極的に却下)

• MISRA C / CERT C 流の Risk Assessment: 安全クリティカル領域用。ADR には不適合。
• migration guide の専用ページ: 「Legacy 節 + Changelog 節」で十分。
• SemVer / バージョン番号管理: ADR 番号が代替するので不要。
• 多言語ドキュメント: 日本語のみ。
• Prettier 流「No options」哲学: ADR lint は構造規約なのでオプション化の余地が少なく、Prettier の哲学はそのまま当てはまらない。

Caveats (留意点)

1. adr-kit には同名異プロジェクトが複数存在。kschlt 版 (policy block → ESLint/Ruff 自動生成) と rvdbreemen 版 (Claude Code plugin、4 verification gates) は別物。bizlp が将来 adr-kit を導入する場合は、どちらの哲学を採用するか明示が必要。
2. Biome / Stylelint のルール件数は表記揺れあり。Biome 公式サイトは「502 rules」、Stylelint は公式サイトと GitHub README で「over 100」「over 170」と差がある。正確な件数は導入直前に再確認するのが安全。
3. Anthropic Skill の 500 行制約は best practice であり hard limit ではない。bizlp で 600 行になっても即座に問題化はしないが、超えた段階で Progressive disclosure 化を検討すべきベンチマーク。
4. MISRA C:2025 の正確な rule/directive 数は無料情報源で 223 / 224 / 225 と揺れあり (公式 PDF は有料)。本レポートでは「223-225」と幅で記載。bizlp が MISRA C を参照する必要は実質ないが、引用時は注意。
5. ESLint Rule Reference の見出し定型は公式に厳密な「テンプレート」として文書化されていない (PR #5446 で議論段階のまま)。Rule Details / Options / When Not To Use It / Version / Resources の順は 慣習として確立しているが、強制ではない。
6. textlint v15 (2025/06) は MCP サポート を導入済み。bizlp の adr-lint を将来 MCP サーバ化する場合の参考実装になる (今回の Rule Reference 設計とは直接関係ないが、将来の AI 連携の入り口)。
7. 本レポートは公開 OSS のドキュメント構造を網羅したが、社内ドキュメント・有料規格 (MISRA 公式 PDF、ISO/IEC 17961 等) は参照できていない。とくに MISRA C:2025 の Rationale 節の最新書式は要追加調査。
8. 「1 人法人 + AI Agent 併用」のスケールでの best practice は確立途上。本レポートの推奨は ESLint / RuboCop / Anthropic Skill の知見の合成であり、bizlp の 6-12 か月後の運用経験に基づく再評価が推奨される。

bizlp 採用推奨案 (結論、400 字以内)

推奨章立て: 10 節構造 (目的 / Severity 凡例 / Category 凡例 / サマリ表 / 4 カテゴリ別ルール本体 / Legacy / Changelog)。各ルールテンプレの必須項目は 10 個 (id, severity, category, since, status, fixable, description, rationale, FAIL/PASS, related_adrs)。省略可能項目は 5 個以上 (options, migration guide, risk assessment, bibliography, plugin guide)。rationale は Ruff 形式の 3 文構造 (What / Why / Alternative) で 3-5 行、ADR への 1 行リンクを併記。examples は ❌ FAIL → ✅ PASS の 2 ブロック で Markdown コードブロック。AI Agent 解釈性: 各ルール冒頭に YAML メタブロック (機械可読)、本文 ≤500 行 (Anthropic Skill 準拠)、AGENTS.md (OpenAI 公式発表で 60,000+ プロジェクト採用) から相互リンク。関連 ADR リンクは一方向 (Rule Reference → ADR)、since: で起点 ADR を 1 つ指定、Related ADRs 節で補足。Deprecation は末尾 Legacy 節 + Changelog 節の 2 か所で管理、移行ガイドは作成しない。