ADR-0055: bizlp doc nav prefix を親フォルダ番号ベースに刷新

• Status: Accepted
• Mode: Standard
• Scope: platform
• Kruchten Type: Property
• Implementation Status: Done (PR #861)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-19 17:30
• 承認日時 (JST): 2026-05-19 23:30
• Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

bizlp の docs サイト (docs/_config.json の nav 配列、470 entries 規模) は各 page の title に letter prefix (A-G) を付与している (例: F.2.11 bizlp ADR Lint Rule Reference)。この letter prefix は元々セクション分類 (A=Architecture, F=Workflow 等) を想定して導入されたが、運用過程で多 group にまたがって混在する状態に陥っている。PR #856 (2026-05-19) で新規 nav 登録 (F.2.11) する際に「親フォルダ番号ベース」への刷新案が浮上した。

1.2 現状 (Current State / As-Is)

docs/_config.json 全 nav letter prefix と group root の対応:

C/F/G の 3 letter で計 8 group root が混在しており、letter prefix が分類軸として機能していない。

1.3 課題 (Problem)

• letter prefix の意味喪失: 新規参加者が F.2.11 を見ても「何系統の doc か」を letter から推測できない。group 名を見て初めて分類が判明する
• nav 登録時の prefix 採番が属人化: PR #856 では F.2.11 を機械的に F.2.10 の次に採番したが、本来は letter の意味との整合性検証が必要 → 検証なしで運用継続中
• 将来 30 group 超で letter 不足: A-G 7 letter は arc42 + internal + ops + meta の 4 namespace × 平均 7-8 sub-group を集約しきれない (現状 470 entries、Jr 入社後 1000 entries 規模に拡大想定)

1.4 制約・要件 (Constraints & Requirements)

• scripts/docs-nav-lint.mjs (ADR-0051) の 3 rule (orphan-md / broken-nav-entry / duplicate-nav-entry) を引き続き pass
• scripts/docs-build.mjs の anchor 生成規則 (title → kebab) を破壊しない (外部 URL/Cloudflare Pages link が壊れない)
• 既存外部参照 (Slack URL は anchor 含まず、Cloudflare Pages slug は file path ベース) への影響最小化
• 一括変換スクリプト + 目視レビューで完遂可能なこと

1.5 目標 (Goals / To-Be)

各 page の prefix は 所属 group の数字部分から機械決定できる状態にする。letter prefix を廃止し、<group数字>.<page index> 形式 (例: 05.2.11 = internal.05.2 group の 11 ページ目) に統一。group 名と prefix が機械整合する規約を確立し、新規 nav 登録時の採番判断を不要化する。

2. 決定

docs/_config.json の nav title prefix を <namespace 接頭辞>.<group 数字>.<page index> 形式 に刷新する。namespace 接頭辞を 1 文字に縮約し、衝突を回避しつつ可読性を確保する。

2.1 prefix 形式

<NS>.<group_number>.<page_index>

• NS (1 文字): namespace 接頭辞 — I = internal, A = arc42, O = ops, M = meta
• group_number: group 名の数字部分 (例: internal.05_* → 05, internal.05.5.5_* → 05.5.5)
• page_index: group 内の連番 (1 起点、ゼロ詰めなし)

2.2 適用例 (本 doc 含む 6 例)

2.3 衝突回避

internal.02_* と ops.02_* のように namespace を跨ぐと group 数字が衝突する箇所が複数存在 (調査で確認、§1.2 の混在パターンとは別問題):

• internal.02_backlog vs ops.02_routines — 両方 02
• internal.03_* vs arc42.03_* — 両方 03
• internal.04_templates vs arc42.04_solution-strategy — 両方 04

→ namespace 接頭辞 (I/A/O/M) で disambiguate。「親フォルダ番号のみ (例: 02.NN)」では衝突回避できないため本案で接頭辞を維持。

2.4 nested group の扱い

internal.05.5.5_multiyear_* のような 3 階層 nested group は group 数字をハイフン無しドット区切りでそのまま使用 → I.05.5.5.NN。階層深度に上限を設けない (現状最大 3 階層、将来拡張可能)。

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 5 軸選定、ADR-0050 §4.2 準拠)

K.O. criterion: Must 軸 (#maintainable / #operable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

加重和首位 = K.O. 通過案 = 採択案 (NS + group 数字 + page index)。案 X3 (group full name) も K.O. 通過するが、文字数が冗長 (12-15 文字 vs 8-10 文字) で #usable 2 点低い → 接頭辞 1 文字に縮約する採択案が妥当。

4. 検討した代替案 (Alternatives Considered)

• 案 X1: 番号のみ (05.11) — namespace を完全廃止、group 数字のみで識別。K.O. 不通過 (#operable=2)。internal.02 と ops.02 の衝突を docs-nav-lint で検出不能、運用上 nav title から所属 namespace を判別できない。
• 案 X2: letter prefix 維持 (F.2.11、現状) — 何もしない案。K.O. 不通過 (両 Must 軸 ≤2)。§1.2 で documented した C/F/G の混在問題が継続、letter 枯渇リスク継続。
• 案 X3: group full name prefix (internal.05.11) — namespace を省略せず冗長に書く。K.O. 通過するが nav title が長くなり (12-15 文字)、#usable で採択案より 1 点低い。将来 internal-products のような長い namespace 追加時に更に長くなるリスク。
• 案 X4: letter → 数字単純置換 (F.2.11 → 5.2.11) — letter のみ machine-readable に変換。letter 配分の混乱を継承するため §1.2 の根本問題が解決されず、検討外。

5. 影響 (Consequences)

5.1 正の影響 (Good)

• nav 登録時の prefix 採番が 機械決定可能 (group 名と page index から計算)、人間判断不要
• letter prefix の混在問題が根絶 (NS 接頭辞で機械整合)
• scripts/docs-nav-lint.mjs に「prefix が group 数字と整合するか」rule を追加可能 (将来 R4)
• 検索時に NS で範囲絞り込み可能 (例: I.05.* で internal.05 系統のみ)

5.2 負の影響 (Bad)

• 初期実装コスト ~3-5h (変換スクリプト ~1h + 470 entries 実行 + 目視レビュー ~2h + adr-lint/docs-build/docs-lint 検証 ~30 分 + PR + 修正サイクル ~30-60 分)
• 既存外部参照 (Slack で letter prefix を含む URL 共有等) が陳腐化、ただし URL は anchor を含まない slug ベースなので link 自体は壊れない
• 一時的に古い letter prefix が memory/conversation に残存し、AI Agent が古い prefix で言及する可能性 → 本 ADR Accepted 後 1 ヶ月で memory 更新

5.3 中立・トレードオフ (Neutral / Trade-offs)

• letter prefix を覚えた既存メンバーは新表記への慣熟が必要 (代表取締役 1 名のみ、現状コスト微小)
• arc42.NN namespace の A は letter 'A' の歴史的用途と重なるが、新スキーム下では NS 接頭辞として再定義

5.4 ROI 計算

• 回収期間: 3-5h ÷ (~65-115 分/月) = 2-4 ヶ月 で総回収
• Jr 入社後は機械決定可能性が引き継ぎコスト ~1h を一気に削減 → 入社月で追加回収

6. 撤退条件 (Rollback Plan)

再評価トリガー

• 3 ヶ月後 (2026-08-19): 新規 group 追加で番号衝突が発生していないか確認。NS 接頭辞 4 つ (I/A/O/M) で disambiguate 不能なケースが発生したら命名規約を改訂
• 6 ヶ月後 (2026-11-19): 既存メンバーから letter prefix 復活要望が出れば部分復元 (NS 接頭辞を letter に戻す等) を検討
• 1 年後 (2027-05-19): nav title 長が平均 15 文字超えていれば prefix 短縮再設計

撤退手順

完全撤退 (~30 分):

1. git revert <本実装 commit> で元の letter prefix を一括復元
2. 旧 letter 系統で追加された新 entry を手動で letter 採番に再割り当て (採択案運用期間中に追加された entry のみ)
3. docs/_config.json の整合性を npm run docs:lint で確認
4. 本 ADR を Superseded 化 (別 ADR で根本見直し)

負債化リスク

• リスク 1: NS 接頭辞 4 つで足りなくなる (例: product.*, customer.* 追加) → 接頭辞を 2 文字に拡張 (PR.05.*) する小規模改訂
• リスク 2: 変換スクリプトの誤動作で nav 整合性が破壊 → 実装時に dry-run mode + 差分目視レビュー + git restore で巻き戻し可能性確保
• リスク 3: docs サイト URL slug は file path ベースで本 ADR の影響を受けないが、もし将来 title-based slug に変更したら全 URL が変わる → 本 ADR 内で title-based slug は採用しない方針を明記

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証手段 1 (機械検証): 変換後の docs/_config.json に対し以下を確認 (新 CI rule prefix-group-consistency を docs-nav-lint.mjs に追加):
  • 各 page の prefix の数字部分が、所属 group の数字部分と一致する
  • NS 接頭辞が group root と一致する (internal → I, arc42 → A, ops → O, meta → M)
• 検証手段 2 (機械検証): npm run docs:lint (R1/R2/R3) + npm run docs:build 成功 + warning なし
• 検証手段 3 (手動): 変換後の nav を Cloudflare Pages preview で目視確認、prefix 表記の統一感を確認
• 実行頻度: CI 検証は PR ごと毎回、手動レビューは本 ADR 実装時 + 3/6 ヶ月後の Review After で実施
• 違反時の対応: prefix-group-consistency 違反は PR マージブロック、起案者が prefix を修正

7. 参照 (References)

• 関連 ADR:
  • ADR-0045 (docs/_internal 組織化): group root の数字付きサブディレクトリ命名規約の前提
  • ADR-0051 (docs-nav-lint): 本 ADR の検証手段 1/2 の実装基盤
  • ADR-0050 (Synthesis 標準テンプレート、Q42 9-tag MCDA): 本 ADR §3 で Q42 5 軸 + WSM + K.O. を適用
  • ADR-0054 (Lint Rule Reference): 本 ADR Accepted 後、adr-lint_rules.md の §4 Summary Table に prefix-group-consistency rule (将来 lint 化時) を追加予定
• 関連 PR:
  • PR #856 (本 ADR の起案動機): F.2.11 採番時に letter prefix 混在が再認識された
  • PR #857 (本 ADR の前段クリーンアップ、論点 4-b): docs/adr/ 日本語ファイル名 6 件を kebab-case 化
• 検証可能な完了条件:
  • docs/_config.json の全 470 entries が NS+group+index 形式 prefix を持つ
  • scripts/docs-nav-lint.mjs に prefix-group-consistency rule 追加、CI で違反検出
  • npm run docs:build 成功、warning なし
  • 本 ADR Implementation Status を Accepted 後 In Progress (PR #NNN) → Done (PR #NNN) に更新

8. 変更履歴