最終更新: 2026/06/22 18:56
RQ-051 メタプロンプト: Lint 規約ドキュメント / Rule Reference のベストプラクティス調査
1. 背景
bizlp-gas-accounting プロジェクトでは scripts/adr-lint.mjs で 11 ルールの ADR lint 検証を運用している (ADR-0023 / 0030 / 0032 / 0036 / 0038 / 0049 由来)。規約が 7 ADR に分散しており、運用時に「どのルールがどの ADR 由来か」が即座に分からない問題が顕在化している (PR #811 で暫定ドキュメント案 Z を起案したが、業界調査未実施で close)。
業界では ESLint Rules Reference, Stylelint Rules, markdownlint Rules 等の Lint 規約ドキュメント (Rule Reference) が長年運用されており、必須項目・章立て・自動化・deprecation 管理に確立された慣習がある。これらを調査せずに独自構造で起案するのはアンチパターン (RQ-038 / RQ-045 / RQ-046 / RQ-050 と同じ「業界調査経由で正当化」パターンを踏襲すべき)。
2. 調査の目的
- Lint 規約ドキュメント (Rule Reference) の業界ベストプラクティスを特定する
- 必須項目・章立て・運用慣習を業界標準と照合する
- bizlp の 11 ルール (adr-lint) の規約ドキュメントとして適用可能な最小実用形態 (MVP) を導出する
- 1 人法人 (Solo Founder + AI Agent) スケールでの過剰回避基準を確立する
3. 調査論点 (Research Questions)
| # | 調査論点 | 期待アウトプット |
|---|---|---|
| Q1 | Lint 規約ドキュメントを公開している主要 OSS / ツールの網羅 | 一覧 + 一次資料 URL |
| Q2 | 各事例における必須項目 (rationale / examples / fixable / config / deprecation 等) の有無比較 | 比較マトリクス |
| Q3 | 章立て・構造の業界共通パターン (early-warning / examples-first / rules-by-category) | 推奨章立て |
| Q4 | rationale (なぜそのルールが必要か) の記述深度・形式 | テンプレート例 |
| Q5 | PASS / FAIL の具体例の提示形式 (コードブロック / diff / ペア表記) | 推奨形式 |
| Q6 | deprecation / 追加・削除の changelog 管理慣習 | 例 + bizlp 適用案 |
| Q7 | 自動修正 (fixable / autofix) フラグの記述慣習 | 例 + bizlp 適用案 (現状 adr-lint は autofix なし) |
| Q8 | CI 統合・severity 説明の典型 | 例 |
| Q9 | AI Agent (Claude / Gemini) が解釈しやすい構造の特性 | 推奨パターン |
| Q10 | 1 人法人スケールで省略可能な項目と必須項目の判定 | 「MVP に含めるべき項目」リスト |
| Q11 | bizlp の 11 ルール (adr-lint) に直接適用可能な推奨章立て案の提示 | 章立て案 + 各章の必須内容 |
4. 調査対象 (最低限カバー)
Lint ツール本家
- ESLint Rules Reference (https://eslint.org/docs/latest/rules/) — JavaScript lint の業界デファクト、200+ ルール
- Stylelint Rules (https://stylelint.io/user-guide/rules) — CSS lint
- markdownlint Rules (https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) — Markdown lint
- Pylint Documentation (https://pylint.readthedocs.io/en/latest/user_guide/messages/messages_overview.html) — Python lint
- RuboCop Cops (https://docs.rubocop.org/rubocop/cops.html) — Ruby lint
- Prettier Rules (https://prettier.io/docs/en/options.html) — 自動フォーマッタの設定文書
Linter / Formatter プラットフォーム
- Biome Linter Rules (https://biomejs.dev/linter/rules/) — 新興 Rust 製 lint ツール
- Ruff Rules (https://docs.astral.sh/ruff/rules/) — 新興 Python lint、高速・統合型
- golangci-lint (https://golangci-lint.run/usage/linters/) — Go lint メタツール
ADR / ドキュメント lint
- adr-kit Rules (RQ-038 で既出) — ADR 用 lint, MIT, v0.11.0
- Vale Styles (https://vale.sh/docs/topics/styles/) — 文書 lint, スタイルガイドベース
- markdownlint-cli2 Rules
- textlint Rules (textlint.github.io) — 日本語 lint も対応
学術・規約管理
- MISRA C Rules (https://www.misra.org.uk/) — 業界標準コーディング規約 (有料だが構造は公開)
- CERT Coding Standards (https://wiki.sei.cmu.edu/) — セキュリティコーディング規約
Anthropic Skill (RQ-038 で既出)
- Anthropic 公式 Skill authoring best practices (500 行 / 5,000 トークン制約)
5. 期待するアウトプット形式
- エグゼクティブ・サマリ (200 字以内): bizlp が採用すべき Lint 規約ドキュメントの章立て・必須項目の推奨
- 業界事例マトリクス: ツール名 / 規約数 / 公式ドキュメント URL / 必須項目チェックリスト
- 章立て比較表: 各事例の章構成と共通パターン
- rationale 記述形式の比較: 「1 行説明」「3 文構造 (問題・解決・代替)」「Anti-pattern + 推奨ペア」等の分類
- PASS / FAIL 提示形式の比較: コードブロック・diff・ペア表記
- 1 人法人スケールでの MVP: 必須項目 N 個 + 省略可能項目 M 個
- bizlp 11 ルール (adr-lint) への推奨章立て案: 各ルールテンプレ + ドキュメント全体構造
6. 制約・スコープ外
- 個別ツールの機能比較 (どの lint が速い・正確 等) は対象外
- bizlp の adr-lint 実装の最適化は対象外
- AI Agent 向け 500 行制約の検証は RQ-038 で既出なので参考程度
- 学術的厳密性 > 実装速度 だが、過剰設計は避ける (1 人法人スケール)
7. 期待する調査深度
- ADR-0020 / RQ-050 と同等の業界一次資料調査
- 各事例の実物 (公式ドキュメント本体) を最低 1 件は確認 + 引用
- 3 モデル並列での得意領域:
- Gemini Deep Research: 最新事例 (Biome / Ruff 等新興ツール) のグローバル動向
- Claude Research: 論理整合性・bizlp 既存 ADR (0038 / 0049) との接続性
- GPT Deep Research: 実装観点・テンプレート構造提案
8. 後続アクション (Post-Synthesis)
3 モデルの調査結果を RQ-051_lint_rules_doc_best_practices_synthesis.md にまとめ、
adr-lint 規約ドキュメント (Rule Reference) の最終版を docs/_internal/05_how-to/adr-lint_rules.md として再起案する。再起案 PR では PR #811 のブランチ claude/adr-lint-rules-doc を参考に、業界調査根拠を盛り込んだ改訂版を提出。
9. 推奨実行モデル
| モデル | 役割 | 期待 token 量 |
|---|---|---|
| Gemini 2.5 Pro Deep Research | 業界一次資料調査・最新事例 | 20,000+ |
| Claude Opus 4.7 Research | bizlp ADR-0038 / 0049 との整合性チェック・反論検証 | 15,000+ |
| GPT-5 Deep Research | テンプレート構造設計・MVP 必須項目導出 | 10,000+ |
10. 関連 ADR / RQ
- ADR-0038: adr-lint メタデータ規約 6 ルール — 本 RQ の出力で適用する規約集合の半数
- ADR-0049: Scope 4 層分類 — 本 RQ の出力で適用する規約集合の 1/6
- RQ-038: ADR Skill Architecture — Anthropic 公式 Skill best practices で参考あり (500 行制約等)
- RQ-045: 内部運用ドキュメント組織化 — frontmatter 必須化・status 軸との接続
- RQ-046: ドキュメントインベントリ管理 — coverage tracking との接続
- RQ-050: ADR Scope 分類軸 — 本 RQ-051 と同じ 3 モデル並列パターン