最終更新: 2026/06/22 18:56
bizlp ADR Lint Rule Reference
Status: SSoT (ADR-0054 で確立、2026-05-19) 対象: ADR 起案者・レビュアー・AI Agent (Claude / Gemini / GPT) 検証:
scripts/adr-lint.mjs本体 +scripts/adr-lint-doc-consistency.mjs(本 doc 整合性、Phase 3 で実装) 根拠 ADR: ADR-0054 — bizlp Lint Rule Reference 文書構造の確立
1. Purpose & Scope
本 doc は scripts/adr-lint.mjs に実装された 全 18 rule の規約を 1 箇所に集約した Single Source of Truth (SSoT) である。ADR-0023 / 0030 / 0032 / 0036 / 0038 / 0039 / 0049 / 0053 / 0088 / 0091 に分散していた規約根拠を、Discovery (Summary Table) + Detail (各 rule 深掘り) の二層構造で集約する。
対象読者:
- ADR 起案者: 新規 ADR を書く前に §4 Summary Table を読み、関連 rule の制約を把握
- PR レビュアー: CI で adr-lint が fail した時の rule 解釈根拠として参照
- AI Agent (Claude / Gemini / GPT): ADR 起案・レビュー時の規約整合性チェック根拠
Non-Goals: adr-lint.mjs 本体の autofix 実装 / 過去 ADR 本文の書き換え (本 doc から過去 ADR への片方向参照リンクのみ追加)。
2. Severity Legend
| severity | 意味 | CI 挙動 |
|---|---|---|
| error | PR マージブロック、起案者修正必須 | exit 1〜2 で fail |
| warn | 警告のみ、CI fail させない (偽陽性リスク or 移行期間) | exit 0 で pass、ログのみ |
3. Category Legend
| category | 意味 | 主な検証対象 |
|---|---|---|
| structure | ADR ファイル形式・必須セクションの存在 | H1/H2 見出し、ファイル名、テンプレート遵守 |
| content | 本文の質・最低要件 | プレースホルダー残置、最低文字数、§判断基準の MCDA 充足 |
| metadata | 構造化メタデータフィールドの存在・値 | Kruchten Type / Implementation Status / Scope |
⚠️ ADR-0054 §2.1 では 4 カテゴリ (Structure/Content/Metadata/Status) を想定していたが、現状 14 rule に「Status」専用は該当せず (
scope-meta-legacyも metadata 系)、本実装では 3 カテゴリに統合。将来 status 系 rule (例: ADR-0032 Implementation Status の値域 enum 検証) が追加された場合は §8 を再活性化する。
4. Summary Table (Discovery Layer)
| # | ID | Severity | Category | Description | Related ADR |
|---|---|---|---|---|---|
| 1 | numbered-header | error | structure | # ADR-NNNN: 形式の H1 見出しが存在 (番号が ??? でない) | ADR-0023 |
| 2 | context-section | error | structure | コンテキスト / ステータスセクションが存在 | ADR-0023 / ADR-0024 |
| 3 | decision-section | error | structure | 決定 / 理由セクションが存在 | ADR-0023 / ADR-0024 |
| 4 | no-placeholder | error | content | ADR-??? プレースホルダーが残っていない | ADR-0023 |
| 5 | min-length | error | content | 本文が 200 文字以上ある | ADR-0023 |
| 6 | filename-pattern | error | structure | ファイル名が 4 桁連番 + ハイフン区切り (NNNN-*.md) | ADR-0023 / ADR-0038 |
| 7 | template-sections | error | structure | 必須 H2 セクション 6 種が存在 (ADR-0023 以降) | ADR-0024 / ADR-0038 |
| 8 | confirmation-section | error | structure | Confirmation セクションが存在 | ADR-0036 / ADR-0038 |
| 9 | kruchten-type-meta | error | metadata | Kruchten Type フィールドが存在 (Existence/Property/Executive) | ADR-0030 / ADR-0038 |
| 10 | implementation-status-meta | error | metadata | Implementation Status フィールドが存在 | ADR-0032 / ADR-0038 |
| 11 | corrigendum-marker | warn | content | 遡及追加箇所に corrigendum 注記行が存在 | ADR-0038 (R4) |
| 12 | scope-meta | error | metadata | Scope フィールド (corporate|platform|product|ops) が存在 (ADR-0049 以降) | ADR-0049 |
| 13 | scope-meta-legacy | warn | metadata | Scope フィールドが存在 (ADR-0048 以前、Phase 2/3 遡及対象) | ADR-0049 |
| 14 | decision-drivers-mcda | error | content | Standard/Critical mode で §判断基準 + Q42 タグ + スコア表が存在 (ADR-0053 以降) | ADR-0053 |
| 15 | cost-estimation-section | error | content | Standard/Critical mode で ## コスト試算 + 数値 1 つ以上が存在 (ADR-0088 以降) | ADR-0088 |
| 16 | no-placeholder-marker | error | content | Standard/Critical mode で本文に未確定プレースホルダ (要追記/要確認/未定/後日/検討中) を残さない (ADR-0091 以降、code block / 引用 / Non-Goals 除外) | ADR-0091 |
| 17 | rollback-has-quantity | error | content | Standard/Critical mode で §撤退条件 に数値 1 つ以上が存在 (ADR-0091 以降) | ADR-0091 |
| 18 | confirmation-has-kpi | error | content | Standard/Critical mode で §Confirmation または §完了条件 に観測可能 KPI = 数値 1 つ以上が存在 (ADR-0091 以降) | ADR-0091 / ADR-0036 |
| 19 | residual-risks-status-tag | error | metadata | HITL-RATIFIED-RESIDUAL marker を持つ ADR が Accepted なら Status に accepted-with-residual-risks タグ必須 (逆方向の不整合も fail) | ADR-0109 |
| 20 | references-section | error | structure | ADR-0019+ の Standard/Critical は §参照 (References) または §関連 ADR セクションを持つ (テンプレ正規構造。grandfather 0001-0018 と Light は免除) | ADR-0024 |
| 21 | frontmatter-status-sync | error | metadata | frontmatter に status を宣言する ADR は本文太字メタ欄 Status の正規化値と一致 (二重保持 drift 防止。未宣言は対象外) | ADR-0123 / ADR-0131 |
| 22 | status-impl-no-stale-proposed | warn | metadata | Implementation Status が Done なのに Status が Proposed のまま = 昇格漏れの疑いを warn (後追い文書化の起案 PR を塞がないため表示のみ) | ADR-0032 |
| 23 | frontmatter-meta-sync | error | metadata | frontmatter の ADR メタ 7 キー (mode/kruchten/scope/implementation_status/proposed_at/approved_at/deciders) は本文太字メタ欄と一致し、値は文字列のみ = YAML 配列禁止 (二重保持期間の drift 防止。未宣言は対象外) | ADR-0137 |
| 24 | business-axis-enum | error | metadata | frontmatter の business (事業軸・INDEX ドメイン列の原本) は corp|mas|drp|meta のいずれか (未宣言は対象外 = nav グループ判定へフォールバック) | — |
| 25 | approver-meta | error | metadata | ADR-0145+ は承認者欄 (Approver Role / Approver Who) を持ち、role はちょうど 1 つ (ADR-0141 単一 Accountable) | ADR-0141 |
| 26 | approver-role-enum | error | metadata | Approver Role は corporate|platform|product|ops のいずれか (Scope 由来 4 役割。欠落は approver-meta が検出) | ADR-0141 |
| 27 | approver-role-scope-match | error | metadata | Approver Role は Scope と一致する (role は Scope から導出。注釈つき Scope は先頭トークン比較) | ADR-0141 |
| 28 | implementation-status-vocab | error | metadata | Implementation Status は正典 ADR-0032 の 6 値 (Not Started / In Progress / Done / Partial / Reverted / N/A) で始まる。フェーズ別・複数決定の併記は許容。正典外トークン (Implemented / Superseded / Deprecated 等) はドリフトとして弾く | ADR-0032 |
| 29 | followups-meta | error | metadata | ADR-0145 以降の ADR に followups: フィールドが存在する (ADR-0144 Phase b バックフィルで遡及追加済) | ADR-0144 |
| 30 | followups-structure | error | metadata | followups の構造 (schema / updated_at / on_done / none_reason) が ADR-0144 雛形に整合 + プレースホルダ残存なし | ADR-0144 |
| 31 | impl-detail-implies-short-status | error | metadata | impl_detail 節を持つ ADR は implementation_status を短縮形式 (ADR-0032 6 値のいずれかに完全一致・追加情報なし) にする (詳細は impl_detail 節へ集約・2 か所同期 lint) | ADR-0162 |
| 32 | umbrella-readonly | error | structure | base 側で status: umbrella だった ADR の本文編集 (frontmatter 以外の diff) を PR で機械的に拒否する。子 ADR で内容を更新させる。scripts/adr-lint.mjs --check-umbrella-readonly subcommand で git diff を判定 | ADR-0152 |
集計: error 29 件、warn 3 件 / structure 8 件、content 8 件、metadata 16 件。
5. Structure Rules (Detail)
個別ファイル参照 (Phase 2c X5 移行、2026-05-20): 各 rule の Detail は
adr-lint_rules/rules/<id>.mdへ分離済。§4 Summary Table の link から直接アクセス。
| § | ID | ファイル |
|---|---|---|
| 5.1 | filename-pattern | adr-lint_rules/rules/filename-pattern.md |
| 5.2 | numbered-header | adr-lint_rules/rules/numbered-header.md |
| 5.3 | template-sections | adr-lint_rules/rules/template-sections.md |
| 5.4 | context-section | adr-lint_rules/rules/context-section.md |
| 5.5 | decision-section | adr-lint_rules/rules/decision-section.md |
| 5.6 | confirmation-section | adr-lint_rules/rules/confirmation-section.md |
並び順: ADR 起案者の作業フロー (ファイル作成 → H1 → H2 骨格 → 本文記述 → Confirmation)。
6. Content Rules (Detail)
個別ファイル参照 (Phase 2c X5 移行): 各 rule の Detail は
adr-lint_rules/rules/<id>.mdへ分離済。
| § | ID | ファイル |
|---|---|---|
| 6.1 | no-placeholder | adr-lint_rules/rules/no-placeholder.md |
| 6.2 | min-length | adr-lint_rules/rules/min-length.md |
| 6.3 | corrigendum-marker (warn) | adr-lint_rules/rules/corrigendum-marker.md |
| 6.4 | decision-drivers-mcda | adr-lint_rules/rules/decision-drivers-mcda.md |
| 6.5 | cost-estimation-section | adr-lint_rules/rules/cost-estimation-section.md |
| 6.6 | no-placeholder-marker | adr-lint_rules/rules/no-placeholder-marker.md |
| 6.7 | rollback-has-quantity | adr-lint_rules/rules/rollback-has-quantity.md |
| 6.8 | confirmation-has-kpi | adr-lint_rules/rules/confirmation-has-kpi.md |
| 6.9 | residual-risks-status-tag | adr-lint_rules/rules/residual-risks-status-tag.md |
| 6.10 | references-section | adr-lint_rules/rules/references-section.md |
7. Metadata Rules (Detail)
個別ファイル参照 (Phase 2c X5 移行): 各 rule の Detail は
adr-lint_rules/rules/<id>.mdへ分離済。
| § | ID | ファイル |
|---|---|---|
| 7.1 | kruchten-type-meta | adr-lint_rules/rules/kruchten-type-meta.md |
| 7.2 | implementation-status-meta | adr-lint_rules/rules/implementation-status-meta.md |
| 7.3 | scope-meta | adr-lint_rules/rules/scope-meta.md |
| 7.4 | scope-meta-legacy (warn) | adr-lint_rules/rules/scope-meta-legacy.md |
8. Status Rules (Detail)
個別ファイル参照 (Phase 2c X5 移行): 各 rule の Detail は
adr-lint_rules/rules/<id>.mdへ分離済。
ADR-0054 §2.1 で想定していた「Status」専用カテゴリは長らく不要だったが、ADR-0032 Implementation Status の値域 enum 検証 (implementation-status-vocab) の追加で本節を再活性化した (2026-06-15)。Summary Table 上の Category は近接ルール (implementation-status-meta 等) に合わせ metadata のまま。
| § | ID | ファイル |
|---|---|---|
| 8.1 | implementation-status-vocab | adr-lint_rules/rules/implementation-status-vocab.md |
9. Subcommands
adr-lint.mjs は rule-based lint に加え、以下のサブコマンドを提供する。各サブコマンドは node scripts/adr-lint.mjs --<name> で実行。
| Subcommand | 対象 | 概要 | 関連 ADR | 追加 PR |
|---|---|---|---|---|
--check-frontmatter | docs/ 配下 (enforce 対象ディレクトリ) | YAML frontmatter 必須キー (id/type/status) + 値域検証 | ADR-0039 | — |
--check-legacy-dirs | docs/dev/ 等 legacy ディレクトリ | legacy ディレクトリへの新規ファイル追加を検出 | ADR-0039 | — |
--count-domains | docs/domains/ | current-spec.md 存在数の閾値チェック | ADR-0039 | — |
--check-jtbd-ref | research_prompts/RQ-*_prompt.md / *_meta_prompt.md | frontmatter jtbd: が _jtbd_list.md の承認済み JTBD に一致するか検証。未タグは warn | ADR-0043 | #986 |
--check-template-exists | docs/ 配下 (frontmatter enforce 対象) | frontmatter type: に対応するテンプレート docs/_meta/templates/<type>.md の存在検証。未定義 type は warn | ADR-0041 | #997 |
--check-umbrella-readonly | docs/adr/*.md | base 時点で status: umbrella だった ADR の本文 (frontmatter 以外) 編集を PR で拒否。frontmatter のみの更新 (子 ADR との両端宣言) は許容 | ADR-0152 | (本 PR) |
10. Legacy / Deprecated
該当 rule なし。本 doc 起案時点 (2026-05-19) で全 14 rule が status: active。Deprecated 化された rule が出た場合は本節に「deprecated 日付」「代替 rule への移行手順」「最終削除予定日」を記載する。
11. Changelog
| 日付 | 変更内容 | PR |
|---|---|---|
| 2026-05-19 | v1.0 Phase 1 初版 — 10 節構造 + 14 rule Summary Table + 2 rule (numbered-header / filename-pattern) Detail | #856 |
| 2026-05-20 | v1.1 Phase 2a — frontmatter (type/audience/status/related) 追加 / §5.x rule を作業フロー順に並び替え (filename → numbered-header → template → context → decision → confirmation) / Summary Table anchor link 更新 / ADR-0054 §2.2 corrigendum (severity 表記 warning → warn) 同時反映 | #864 |
| 2026-05-20 | v1.2 Phase 2b — 残 12 rule (§5.3-5.6 / §6.1-6.4 / §7.1-7.4) Detail 追加。本 doc 行数 637 行に達し、ADR-0054 §6.5 検証手段 2 (500 行 error 閾値) を超過 → Phase 2c で案 X5 (個別 YAML ファイル分割) 移行を発火 | #865 |
| 2026-05-20 | v1.3 Phase 2c — 案 X5 移行: 14 rule の Detail を adr-lint_rules/rules/<id>.md 個別ファイルへ分離 (各 ~35-45 行)。main doc を 637 → 132 行に縮小、Summary Table + Discovery layer に専任化。scripts/adr-lint-doc-consistency.mjs (Phase 3) は個別ファイル読込で対応予定 | (本 PR) |
| 2026-05-26 | v1.4 — §9 Subcommands セクション追加 (5 サブコマンド一覧)。--check-jtbd-ref (ADR-0043, PR #986) + --check-template-exists (ADR-0041, PR #997) を含む全サブコマンドを文書化。§番号を 9→11 にシフト | (本 PR) |
将来の Progressive Disclosure 移行手順 (ADR-0054 §6 撤退条件 案 X5)
本 doc 行数が 500 行に逼迫した場合、ADR-0054 §6「部分撤退」に従い以下の手順で個別ファイル分割に移行する:
- 各 rule の YAML コードブロックを
docs/_internal/05_how-to/adr-lint_rules/rules/<id>.yamlに抽出 (スクリプト化可能) - 本 doc は §4 Summary Table + 各 rule への参照リンクのみ保持 (Discovery layer 専任化)
scripts/adr-lint-doc-consistency.mjsを「コードブロック解析」→「個別 YAML ファイル読込」に変更 (両対応で互換移行)
移行発火条件は ADR-0054 §6 再評価トリガーで定義済 (6 ヶ月後 = 2026-11-19、行数 500 逼迫時)。