RQ-051 Lint 規約ドキュメント (Rule Reference) ベストプラクティス（Deep Research プロンプト）
使い方: 以下の本文を ChatGPT (Deep Research) / Claude.ai (Research) / Gemini Deep Research に そのまま投入する。3 モデル並列で実施し、結果はそれぞれ
RQ-051_..._result_gemini.md/_result_claude.md/_result_gpt.mdに保存する。
あなたの役割
あなたは技術ドキュメント・Lint ツール・コード規約の専門家です。 1 人法人 (Solo Founder) が運用する管理会計 SaaS プロジェクトにおいて、 ADR (Architecture Decision Record) の lint 規約ドキュメントを業界ベストプラクティスに沿って設計するための調査を実施してください。
プロジェクト前提
- 規模: 1 人法人 (代表取締役氏)、AI Agent (Claude / Gemini / GPT) 併用
- 既存 lint ツール:
scripts/adr-lint.mjs(Node.js 製、11 ルール) - 既存規約の根拠: ADR-0023 / 0030 / 0032 / 0036 / 0038 / 0039 / 0049 の 7 ADR に分散
- 目的: 規約ドキュメント (Rule Reference) を 1 か所に集約しつつ、業界標準に沿った構造で設計したい
調査タスク
以下の 11 つの研究課題に順番に回答してください。
Q1. Lint 規約ドキュメントを公開している主要 OSS / ツールの網羅
業界で Lint 規約ドキュメント (Rule Reference) を公開している主要 OSS / ツールを網羅してください。それぞれについて以下を含めること:
- ツールの正式名称
- 規約数 (ルール件数)
- 公式 Rules ドキュメント URL
- 採用言語・領域 (JS / Python / CSS / Markdown / 文書 / 他)
- 初公開年・最新更新年
- 想定組織規模
最低でも以下を含めること:
- ESLint, Stylelint, markdownlint, Pylint, RuboCop, Prettier
- Biome, Ruff, golangci-lint
- adr-kit (ADR 用 lint), Vale, textlint
- 学術: MISRA C, CERT Coding Standards
Q2. 必須項目の比較マトリクス
Q1 の各事例について、Rule Reference に含まれる 必須項目 の有無を比較:
- ルール名 / ID
- 説明 (description)
- rationale (なぜそのルールが必要か)
- PASS / FAIL の具体例 (Bad/Good コードペア)
- severity (error / warning / info)
- 自動修正可否 (fixable / autofix フラグ)
- config 例 (ルール ON/OFF・パラメータ設定方法)
- 関連ルールへのクロスリンク
- deprecation 履歴 / 追加・削除 changelog
- カテゴリ分類
Markdown テーブルで網羅すること。
Q3. 章立て・構造の業界共通パターン
Rule Reference の章立て・構造の共通パターンを分類:
- カテゴリ別グループ化 (Possible Errors / Best Practices / Stylistic Issues 等)
- アルファベット順 vs ID 順
- 早期警告 (Deprecated Rules を冒頭に表示) vs カテゴリ内表記
- examples-first (具体例を rationale より先に) vs description-first
代表的な 3-5 パターンを抽出し、bizlp に適したものを推奨してください。
Q4. rationale (なぜそのルールが必要か) の記述深度・形式
各事例の rationale の記述形式を分類:
- 1 行説明
- 3 文構造 (問題 / 解決 / 代替)
- Anti-pattern + 推奨ペア
- 学術論文・規格への引用付き
bizlp の 1 人法人スケールに適した形式を推奨。
Q5. PASS / FAIL の具体例の提示形式
各事例の具体例の提示形式を分類:
- コードブロック (PASS / FAIL を別々に提示)
- diff 形式
- ペア表記 (Before / After / Bad / Good)
- スクリーンショット (Visual lint の場合)
bizlp の ADR ドキュメント (Markdown) lint に適した形式を推奨。
Q6. deprecation / 追加・削除 changelog 管理慣習
各事例での deprecation 管理方法を調査:
- 専用 changelog 章を持つか
- 各ルール内に「Since vX.Y, deprecated in vX.Z」を埋め込むか
- removed-rules.html のように別ファイルに退避
- migration guide の有無
bizlp の adr-lint (11 ルール、今後追加予定) に適した最小実装を推奨。
Q7. fixable / autofix フラグの記述慣習
各事例での autofix フラグ:
- ESLint の
--fix対応マーク - Stylelint の
fixableフラグ - Prettier の全自動修正 (フラグ不要)
bizlp の adr-lint (現状 autofix なし) で将来 autofix を導入する際の準備として、フラグ枠を入れるべきか・不要か判定。
Q8. CI 統合・severity 説明の典型
各事例での CI 統合方法と severity 説明:
- error / warn / off (ESLint)
- error / warning / info (Stylelint)
- severity ごとの CI fail 挙動
bizlp の adr-lint (error / warn の 2 段階) に適合する説明形式を推奨。
Q9. AI Agent (Claude / Gemini) が解釈しやすい構造の特性
近年の AI Agent 連携を意識した Rule Reference の特性:
- 機械可読 (frontmatter / YAML / JSON Schema)
- AI への指示 (Claude Code / Cursor 等のルール統合)
- 構造化メタデータ (Anthropic Skill の 500 行制約等)
- Progressive disclosure パターン
bizlp の 1 人法人 + AI Agent 併用ワークフローに適した構造を推奨。
Q10. 1 人法人スケールでの省略可能項目の判定
業界標準で「必須」だが、1 人法人スケールでは省略可能な項目を判定:
- 大企業前提項目 (deprecation 履歴の SemVer 厳格化 等)
- 多数ユーザ向け項目 (migration guide 等)
- 大規模リポ向け項目 (1000+ ルール用のカテゴリ分類)
bizlp の 11 ルール (将来 30 ルール程度) スケールでのMVP 必須項目リストと省略可能項目リストを提示。
Q11. bizlp 11 ルールへの推奨章立て案
以上の調査を踏まえ、bizlp の docs/_internal/05_how-to/adr-lint_rules.md の推奨章立て案を提示:
- ドキュメント全体の章構成 (1〜N 節)
- 各ルールテンプレ (1 ルールあたりの記述形式)
- 章ごとの必須・省略可能項目
- 関連 ADR とのクロスリンク方針
- changelog / deprecation 枠の有無
具体的な Markdown 構造例を 1 ルール分提示してください。
出力形式
- 各 Q への回答は H2 見出し (
## Q1. xxx) で開始 - 一次資料は 必ず URL or DOI で明示
- 表形式が適切な場合は Markdown テーブルを使用
- 最終セクションで「bizlp 採用推奨案」を 400 字以内で結論
結論には以下を含むこと:
- 推奨章立て (N 節構造)
- 各ルールテンプレの必須項目 (M 個)
- 省略可能項目 (K 個)
- rationale / examples の推奨形式
- AI Agent 解釈性のための工夫
- 関連 ADR とのリンク方針
制約
- ChatGPT / Claude / Gemini の Web 検索機能を積極的に使用してください
- 一次資料がなく憶測で書く場合は
[要追加調査]と明示 - 1 人法人スケールでの実用性を重視
- 学術的厳密性 > 実装速度 だが、過剰設計は避ける
- 既存 bizlp ADR-0038 / ADR-0049 の方針を否定しない範囲で再構成
参考情報 (bizlp 既存)
- ADR-0038: adr-lint メタデータ規約 6 ルール追加・形骸化検出
- ADR-0049: ADR Scope 分類軸の 4 層化
- 既存 11 ルール (id / severity / desc / check):
numbered-header(error, ADR-0023)context-section(error, ADR-0023)decision-section(error, ADR-0023)no-placeholder(error, ADR-0023)min-length(error, ADR-0023)filename-pattern(error, ADR-0023)template-sections(error, ADR-0024)confirmation-section(error, ADR-0036)kruchten-type-meta(error, ADR-0030)implementation-status-meta(error, ADR-0032)corrigendum-marker(warn, ADR-0031)scope-meta(error, ADR-0049)scope-meta-legacy(warn, ADR-0049)
(実際は 13 ルールあるが、運用上「11 ルール + Scope 2 ルール = 13」として扱う)