• Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Existence/Property
  • Implementation Status: Done (PR #959 — Phase B1-B3 全 deliverable 完成: glossary.md +26 term / scripts/lib/glossary.mjs 新規 / scripts/docs-build.mjs glossary injection 統合 / templates/page.html CSS hover popup; PR #965 — モバイル tooltip 表示不可問題の追加修正)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-25 14:03
  • 承認日時 (JST): 2026-05-25 14:40 (Pipeline 通常 flow v2 Standard 46/50 通過)
  • Review After: 2026-08-25 (3 ヶ月), 2026-11-25 (6 ヶ月), 2027-05-25 (1 年)
  • Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

docs site (Cloudflare Pages) には bizlp ドメイン用語 + 技術用語が頻出 (phantom dependency / OAuth / SSoT / INV / monorepo / Cloudflare Queues 等)。docs/architecture/glossary.md (arc42 ch.12 SSoT) に term + 定義の表が既に存在するが、本文中では生テキストのまま表示され、読み手が 「用語をクリック→glossary に飛ぶ→戻る」 の 3 step を毎回必要とする。

1.2 現状 (Current State / As-Is)

  • docs/architecture/glossary.md: 6 section、~30 term の表形式定義 (INV/STL/ORD/SSoT 等 bizlp ドメイン中心)
  • 技術用語 (phantom dependency / Cloudflare Queues / Durable Objects 等) は glossary 未登録、各 doc で個別説明 (or 未説明)
  • docs site build: scripts/docs-build.mjs (marked + custom renderer)、現状 glossary lookup 機構なし
  • 読み手の体験: 技術用語に遭遇 → 別 tab で検索 / glossary を別途開く → 元 doc に戻る → 認知負荷高い

1.3 課題 (Problem)

痛みの定量化 (proxy 実測 + 再評価):

  • proxy 実測 (n=1 session, 本日 2026-05-25): ADR-0066 audit 中、Pipeline reviewer (代表取締役) が "phantom dependency" / "DLQ" / "consumer lag" 等の技術用語遭遇で文脈停止が発生。1 doc あたり 2-5 用語の文脈停止 (各 ~10-30s) → 約 1 min/doc の認知 overhead
  • n=1 の限界自認: 客観性に欠ける、Jr 入社前は読み手 = 代表取締役 + 私の 2 名のみで実測機会が限定的。Jr 入社後 2 ヶ月 (2026-12) で n≥5 session 実測に置換し信頼区間を ±30% 以内に狭める (本セッションで確認した v3 圧縮戦略と同様の段階補正アプローチ)
  • 集計手順 (再現可能化):
    1. session chat log の 「これって何?」「説明して」 の頻度を carrier 集計
    2. 1 doc あたりの平均文脈停止数を proxy 計測
  • 信頼区間: 実測 1 session (n=本日) で推定区間 ±50% (0.5-1.5 min/doc)
  • 再評価: Jr 入社 (2026-10) 後 2 ヶ月 (2026-12) に実測 n≥5 doc 読み (Jr 自身の access log) に置換
  • 将来予測: docs site 規模 500+ docs → 月次 ~20-30 doc 読み (Jr 含む) → 月次 ~20-30 min の認知 overhead 累積

1.4 制約・要件 (Constraints & Requirements)

  • Cloudflare Pages static rendering との互換性 (build-time に HTML 生成、Runtime JS は最小限)
  • 既存 docs-build.mjs (marked + custom renderer) に非破壊で乗ること
  • glossary.md SSoT 原則: 用語定義は 1 箇所、自動連動
  • false-positive 抑制: code block 内の同名単語、URL 内、見出し内などは tooltip 付与しない
  • ADR-0045 / ADR-0058 整合 (frontmatter / nav lint / 配置ルール)
  • JavaScript dependency 最小化 (Cloudflare Pages の bundle size 抑制)

1.5 目標 (Goals / To-Be)

docs/architecture/glossary.md を SSoT として、build-time に全 docs の本文中 term を <span class="glossary-term" data-def="..."> に自動置換、CSS hover popup で定義表示。JS 不要・Cloudflare Pages native 対応・glossary 一元更新で全 doc 即反映。

2. 決定

docs/architecture/glossary.md を SSoT として、scripts/docs-build.mjs を拡張し、marked AST を traverse して本文中の term 出現を <span class="glossary-term" data-def="..."> に build-time 自動置換する。templates/page.html + CSS の :hover/:focus pseudo-class で popup 表示 (JS 不要)。code block / URL / 見出し / frontmatter / 同一段落 2 回目以降は除外する false-positive 抑制を実装。段階実装 B1 (glossary 充実) → B2 (parser + replacer) → B3 (CSS hover) で着手し、将来 B4 (Tippy.js 等 JS library) は別 ADR とする。

2.1 アーキテクチャ

docs/architecture/glossary.md  (SSoT、term + 定義 markdown table)
    ↓ build-time parse (scripts/docs-build.mjs に拡張)
glossary terms map (in-memory JSON)
    ↓ marked custom renderer / token visitor
HTML 生成時、本文中の term 出現を <span class="glossary-term" data-def="..." tabindex="0">term</span> に自動置換
    ↓
templates/page.html + CSS で hover popup (JS 不要、:hover/:focus pseudo-class)
    ↓
Cloudflare Pages static serve

2.2 主要変更

  • scripts/docs-build.mjs 拡張 (~50-80 行追加): glossary.md parser + term replacement logic
  • scripts/lib/glossary.mjs 新規 (~50 行): glossary parse + term matching API
  • templates/page.html + 関連 CSS: .glossary-term hover popup スタイル
  • docs/architecture/glossary.md 拡充: 技術用語追加 (phantom dependency / Cloudflare Queues / DO 等 ~10-15 term)

2.3 false-positive 抑制策

対象処理
`code` inline / code blocksskip (marked AST の type='code' / 'inlineCode' で除外)
URL / link textskip (type='link' の children で除外)
見出し (#/##/...)skip (type='heading' の children で除外)
frontmatterskip (--- blocks は marked parse 対象外)
同一段落で複数回初出のみ (重複防止、<span> 化は同段落 1 回)

2.4 段階実装

  • Phase B1: glossary.md 技術用語追加 (~1-2h、人力 + RQ-053 結果連携)
  • Phase B2: docs-build.mjs + lib/glossary.mjs 実装 (~2-3h、Cursor / Claude 支援)
  • Phase B3: templates + CSS hover popup スタイリング (~1h)
  • Phase B4 (将来): JS-based rich tooltip (Tippy.js 等) への段階拡張 (本 ADR スコープ外)

3. 判断基準 (Decision Drivers)

ADR-0050 / ADR-0054 / ADR-0058 と同 Q42 5 軸 + WSM + K.O. (Suhr 1999 CBA 準拠)。

3.1 評価軸

#重要度 (係数)案件特有の解釈
1#usable[Must] (×2.0)読み手が用語遭遇時に context switch なく即定義を得られるか
2#maintainable[Must] (×2.0)用語追加・更新が SSoT 一元で全 doc に伝播するか
3#suitable[High] (×1.0)Cloudflare Pages static rendering との適合性
4#operable[High] (×1.0)false-positive 抑制と運用追従コスト
5#efficient[Medium] (×0.5)build 時間・bundle size への影響

K.O. criterion: Must 軸の score < 3 は不採用。

3.2 評価軸 × 案スコア表

係数採択 (glossary 自動 link, CSS only)X1 <abbr> 手動X2 何もしないX3 Tippy.js JS libraryX4 search 機能のみ
#usable [Must]×2.05 (hover で即表示)3 (用語ごと手動付与)1 (現状)5 (rich popup)3 (検索 step 残る)
#maintainable [Must]×2.05 (SSoT glossary 一元更新)2 (各 doc 個別更新)1 (放置)4 (library 依存)3
#suitable High×1.05 (Cloudflare static native)4 (HTML 標準)53 (JS bundle 増)4
#operable High×1.05 (false-positive 抑制 + CSS only)45 (運用なし)3 (library update 追従)4
#efficient Medium×0.54 (build 時間微増 ~1s)5 (build 無変化)53 (JS 実行 cost)5
加重和 (正規化)0.9620.5310.3460.7080.519
K.O. 通過 (Must ≥3)❌ (#usable=1, #maintainable=1)

採択首位 = glossary 自動 link + CSS only。

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

  • 採用案 (glossary 自動 link, CSS only): SSoT 駆動、JS 不要、Cloudflare native、false-positive 抑制
  • X1: <abbr title="..."> 手動付与: HTML 標準だが doc 内重複・SSoT 連動なし、#maintainable=2 で劣後
  • X2: 何もしない (現状維持)K.O. (#usable=1, #maintainable=1、認知 overhead 累積継続)
  • X3: Tippy.js 等 JS library: rich popup 可だが bundle size 増 + library 追従コスト、本 ADR スコープ後 Phase B4 で再評価
  • X4: search 機能 (algolia / pagefind 等) で代替: 検索 step 残るため hover の即時性に劣る、#usable=3

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • 認知 overhead 削減: 月次 ~20-30 min/Jr (proxy 実測 ±50%) → ~0 min、Jr onboarding 加速
  • glossary SSoT 強化: 用語追加で全 doc 即反映、二重管理回避
  • 新規参加者の自走力向上: 技術用語遭遇 → hover で即理解 → context switch 不要
  • 既存 docs 改修不要: build-time 自動付与、author 側追加作業ゼロ

5.2 負の影響 (Bad)

  • build 時間微増 (~1-3s、term 数 + doc 数比例)
  • glossary.md 充実コスト: 初期 ~10-15 技術用語追加 ~1-2h、継続 ~10-20 min/月 (用語遭遇時の追加)
  • false-positive リスク: code block 内の同名単語の hover 化 (§2.3 抑制策で軽減)
  • <span> 増加で HTML size 増: term 数 × doc 数で線形、影響微小 (Cloudflare Pages free 上限内余裕)

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

影響範囲:

  • 改修対象:
    • scripts/docs-build.mjs 拡張 (+50-80 行、parser + replace logic)
    • 新規 scripts/lib/glossary.mjs (~50 行、SSoT)
    • templates/page.html + CSS (+30-50 行、hover popup style)
    • docs/architecture/glossary.md (+10-15 term entry)
  • 検証対象: 既存 全 docs (~530 .md、build 通過 + 視覚確認)
  • 波及:
    • AI Agent への影響なし (build-time HTML 変更のみ、markdown source は不変)
    • 読み手 (人間) UX 向上
    • search index への影響: pagefind 等を将来導入時に <span class="glossary-term"> を indexer が認識する設定が必要 (本 ADR スコープ外)
  • Decider: 代表取締役 (単独) / レビュアー: docs site Cloudflare Pages preview / 将来 stakeholder: Jr (2026-10)

運用上の罠:

対処
code block 内の同名単語が tooltip 化marked AST の type フィルタで除外 (code, inlineCode)
用語の大文字小文字揺れ (e.g., OAuth vs oauth)glossary 側で正規形を SSoT、build-time に case-insensitive match で吸収 (define alias 機構)
同一段落で同用語複数回出現 → 視覚 noisy初出のみ <span> 化、二回目以降 plain text (build-time state track)
URL や ID 文字列に term と同じ部分文字列 (e.g., "INV" が "INVITATION" に含まれる)word boundary regex (\b...\b / 日本語は [^a-zA-Z0-9_] boundary) で誤マッチ防止
glossary.md 構造変更 (table 列追加 etc.)parser を defensive にする + structure 規約を ADR で明文化
Cloudflare Pages の build cacheterm 追加時に invalidate (現状 deploy 毎に build なので問題なし)

監視 dashboard / 自動 alert / FP 検出 flow:

Metric監視対象Alert 閾値確認手順
glossary.tooltip.fp_count_per_buildbuild log 出力時の suspect log (code block 内マッチ等)> 5/build で alarmingdocs:build:full 出力を grep、grep "GLOSSARY_FP_SUSPECT"
glossary.tooltip.term_count_per_doc1 doc あたりの tooltip 化数> 30/doc で visual noise 兆候build 後の HTML を grep -c "glossary-term"
glossary.build_time_deltatooltip 拡張前後の build 時間差> +5s sustained で performance reviewtime npm run docs:build を before/after で比較
Cloudflare Pages preview の視覚確認hover popup 動作 + FP 視認月次 5 doc サンプリングpreview URL 手動巡回
FP 報告 issue trackerGitHub Issues label glossary-tooltip-fp5 件超で 6.2 (A) feature flag offissue 集計

自動 alert 設計:

  • build log に [GLOSSARY] FP_SUSPECT prefix で suspect line を吐く → CI で grep + report
  • 月次 review チェックリスト (monthly_review_checklist.md に追加要): FP 件数集計、新規 term 追加、code block 誤マッチサンプリング

コスト試算:

  • 時間コスト (初期): B1 glossary 充実 1-2h + B2 docs-build 拡張 ~2-3h + B3 templates+CSS ~1h = **4-6h**、レビューバッファ +30% で 5-8h
  • 時間コスト (継続 12 ヶ月): glossary term 追加 10-20 min/月 × 12 = ~2-4h/年 + 月次 false-positive review ~10 min/月 = ~2h/年 = **4-6h/年**
  • 削減効果: 認知 overhead 削減 20-30 min/月 × Jr 入社後想定読み手 1-2 人 = ~20-60 min/月 = **4-12h/年** + onboarding 工数削減 ~2h (1 回切り)
  • ROI フェーズ分け (誠実評価):
    • Phase 0 (Jr 入社前 = 2026-09 まで): 読み手 = 代表取締役 + 私の 2 名のみ、削減効果 ~5-10min/月 × 2 = ~2-4h/年。継続コスト 4-6h/年 を控除 = net -2 to +0h/年、ROI ほぼゼロ
    • Phase 1 (Jr 入社後 = 2026-10〜): 読み手 +Jr で削減効果 ~4-12h/年、net +0 to +6h/年、回収 1-2 年 (Jr 入社後加速)
    • Phase 2 (業務委託参画増): 読み手 ×3、削減効果 ~12-24h/年、本来の ROI 顕在化
  • 戦略投資正当化: Jr 入社前は ROI ゼロを許容、Jr 入社時の onboarding 即時自走化 + Phase 2 への基盤として正当化。短期回収を期待せず長期 (3-5 年) で評価

6. 撤退条件 (Rollback Plan)

6.1 撤退判断指標

  • 3 ヶ月後 (2026-08-25): false-positive 報告 > 5 件/月 → §6.2 (B) revert
  • 6 ヶ月後 (2026-11-25): build 時間増 > 10s 常態化 → optimize or revert
  • 撤退判断: glossary.md 更新追従工数 > 1h/月 → 「メンテ負債化」と判断、revert 検討
  • 1 年後 (2027-05-25): X3 (JS library, Tippy.js 等) への移行 ADR 起案検討、本 ADR Superseded 候補

6.2 ロールバック手順 (3 段階)

  • (A) feature flag off: scripts/docs-build.mjs の glossary lookup を if (false) で skip (~5min)
  • (B) renderer 拡張 revert: docs-build.mjs + lib/glossary.mjs + templates/page.html を revert (~30min)
  • (C) glossary.md 縮小 + 全廃: 技術用語 entry を削除、bizlp ドメイン用語のみ残置 (~30min)
  • 撤退コスト合計: A: ~5min / B: ~30min / C: ~1h

6.3 Review After / 負債化リスク

  • Review After:
    • 3 ヶ月後 (2026-08-25): false-positive 報告 / build 時間増 / glossary 追加件数
    • 6 ヶ月後 (2026-11-25): Jr 入社直前、技術用語充実度評価
    • 1 年後 (2027-05-25): X3 (JS library) 移行 ADR 起案検討
  • リスク 1: false-positive 多発 (例: term 数 50+ で誤マッチ累積) → word boundary regex を強化、allowlist 機構導入
  • リスク 2: glossary.md 構造変更 (table → JSON Schema 等) で parser 破壊 → defensive parser + ADR-0058 同パターンの 3 way CI 検討
  • リスク 3: Cloudflare Pages build limit (15 min) 超過 → term 数 cap 設定 + build cache 活用
  • 将来検討事項: Tippy.js 等 JS library 統合で rich popup (code snippet / link / 画像) 表示 → 別 ADR (Phase B4)

6.5 Confirmation (準拠確認 / Fitness Function)

  • 検証 1 (機械 / 自動): npm run docs:build で全 ~530 .md が success、warning 0、build 時間増 < 3s。実行頻度: 全 PR の CI / deploy 毎。違反時: build fail → blocker、§6.2 (A) feature flag off で revert
  • 検証 2 (機械 / 自動): 故意 false-positive fixture (code block 内 / URL 内 / 見出し内 / frontmatter) で <span class="glossary-term"> 化されないことを E2E test。実行頻度: CI 毎。違反時: test fail → blocker、抑制策 §2.3 を強化
  • 検証 3 (手動 / レビュー): Cloudflare Pages preview で 5 doc を視覚確認、hover popup 動作確認。実行頻度: 初回リリース時 + 月次 spot check。違反時: issue 起票 → glossary alias / regex 修正
  • 検証 4 (運用指標): 月次 false-positive 報告件数 < 5 件、glossary 技術用語 ≥ 15 entry。実行頻度: 月次。違反時: §6.1 撤退判断指標へ

7. 検証可能な完了条件

#観測指標目標値測定
1npm run docs:build 成功 + warning 00 warningdocs build CI
2build 時間増< 3sbefore/after 比較
3故意 false-positive fixture (code/URL/heading 内) で <span> 化されない100% passE2E test
4Cloudflare Pages preview で hover popup 動作視覚確認 5 doc手動
5月次 false-positive 報告件数< 5 件/月issue tracker
6glossary.md 技術用語数≥ 15 entry (phantom dependency 等)wc -l 集計
7Jr onboarding 時の用語質問数 (将来 2026-10)前年同月比 -50%Jr 入社後実測

8. 過去決定との関係

ADR関係整合性
ADR-0046 (旧) (Superseded by ADR-0048) + ADR-0048 (re-establish doc inventory)Confirms (docs 構造管理の前例)docs/architecture/glossary.md は arc42 ch.12 SSoT として既存運用、本 ADR が glossary 自動 link 用法を新規確立
ADR-0045 (organize-docs-internal)Confirms (frontmatter / 配置ルール)本 ADR 採択 doc は docs/architecture/glossary.md (arc42) で配置不変
ADR-0058 (frontmatter-lint Rule Reference SSoT)Confirms (SSoT pattern)glossary SSoT は frontmatter SSoT と同じ「単一源駆動」思想
ADR-0050 (Q42 MCDA)Confirms本 ADR §3 で Q42 5 軸適用
将来統合候補: ADR-XXXX (search 機能導入、pagefind / algolia)補完並立<span class="glossary-term"> を search indexer が認識する設定が必要

参照 (References)

  • 関連 ADR: ADR-0045 (frontmatter / 配置) / ADR-0048 (doc inventory) / ADR-0058 (SSoT pattern) / ADR-0050 (Q42 MCDA)
  • 関連 PR/Issue: -
  • 既存 doc: docs/architecture/glossary.md (本 ADR の SSoT) / scripts/docs-build.mjs (拡張対象、marked custom renderer)
  • 本セッション (2026-05-25): 代表取締役「phantom dependency 等の用語を hover で表示できるか」要望が起点
  • 将来統合候補: ADR-XXXX search 機能導入 (pagefind / algolia)、Tippy.js JS library 統合 ADR (Phase B4)

11. 参照: Pipeline 審査履歴 (2026-05-25 実行時, 通常 flow)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v2 (204 行) で 46/50 (Standard 閾値 40 + 6 pt 余裕、Critical 閾値 45 も超過) 通過。§audit history パターンの 第十一適用例。デフォルトでは折りたたまれており、 をクリックで展開する。

📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 46 / 50) — クリックで展開

Gate 0-4 結果

  • Gate 0 Triage: needsAdr=true / triageMode=Standard
  • Gate 1 Socratic: pass=true (追加質問 0 件)
  • Gate 2 Consistency: PASS (ADR-0045/0050/0058 整合、ADR-0073 想定参照は問題提起)
  • Gate 3 Parallel Review: 3 vendor 出力は §改善余地 に要約
  • Gate 4 Scoring: 46 / 50
#採点項目点数コメント
1問題定義4proxy 実測 n=1 で信頼区間 ±50% は誠実だが客観性に欠ける (本 PR で §1.3 に n=1 限界の自認 + Jr 入社後 ±30% 補正計画を明示)
2代替案5abbr 手動 / 現状維持 / Tippy.js / search 機能の 4 案 + K.O. 判定
3判断基準5Q42 5 軸 + 係数 + K.O. + 正規化加重和
4過去 ADR 整合性4ADR-0073 が「想定、不在の場合は本 ADR が新規確立」と曖昧で参照健全性が崩れる (本 PR で §9 ADR-0073 削除、ADR-0046/0048 (Superseded/現役 doc inventory) に置換)
5影響範囲5改修ファイル + 行数 + 検証対象 + AI Agent/読み手/search 波及 + Decider/Jr stakeholder
6運用上の罠46 罠と対処は詳細だが、監視 dashboard / 自動 alert / FP 検出 flow の運用設計への言及が薄い (本 PR で §5.4 罠 table 下に「監視 metric + alert 閾値 + 確認手順」table 5 件 + 自動 alert 設計を追記)
7ロールバック性53 段階 + 各撤退コスト分単位
8コスト試算4削減効果分母『Jr 1-2 人』の根拠が薄く、Jr 入社前は ROI ほぼゼロという事実をやや楽観的に表現 (本 PR で §コスト試算 ROI を 3 phase 分け、Phase 0 (Jr 前) net -2~+0h/年 = ROI ほぼゼロを明示、Phase 1/2 で顕在化と誠実評価)
9完了条件57 観測指標 + 目標値 + 測定方法 + 4 検証
10長期影響5Review After 3/6/12 ヶ月 + 3 リスク + Phase B4 将来 ADR

合計: 46 / 50 (Standard 閾値 40 → PASS, Critical 閾値 45 → PASS)

改善余地 (本 PR で反映済)

#指摘反映先効果
1ADR-0073 が想定で実在未確認、参照健全性が崩れる§9 過去 ADR table から ADR-0073 削除、ADR-0046 (Superseded) + ADR-0048 (現役 doc inventory) に置換。§References の関連 ADR list も更新過去 ADR 整合 4/5 → 5/5
2proxy 実測 n=1 で信頼区間 ±50% は弱い§1.3 に「n=1 の限界自認 + Jr 入社前は読み手 2 名で実測機会限定 + Jr 入社後 (2026-12) に n≥5 実測で ±30% 補正」を明示問題定義 4/5 → 5/5 見込
3削減効果『Jr 1-2 人』が楽観的、Jr 入社前 ROI ゼロを楽観表現§コスト試算の ROI を Phase 0 (Jr 前) / Phase 1 (Jr 後) / Phase 2 (業務委託増) の 3 phase 分けに再構成、Phase 0 は net -2~+0h/年 = ROI ほぼゼロを明示、戦略投資正当化を誠実表現コスト試算 4/5 → 5/5 見込
4運用罠節に監視 dashboard / 自動 alert / FP 検出 flow の設計言及不足§5.4 罠 table 下に「監視 metric + alert 閾値 + 確認手順」table 5 件 (fp_count_per_build / term_count_per_doc / build_time_delta / preview 視覚確認 / FP 報告 issue tracker) + 自動 alert 設計 (build log [GLOSSARY] FP_SUSPECT prefix + 月次 review チェックリスト) を追加運用罠 4/5 → 5/5 見込

改善効果見込: 46/50 → 50/50 達成可能性。

Status 遷移

  • v2 投入 (204 行) → Pipeline 通常 flow 46/50 通過 → auto-PR #952 生成 (Proposed)
  • 本 PR で Status: Proposed → Accepted に更新、改善余地 4 件 (§9 ADR-0073 削除 / §1.3 信頼区間補強 / §コスト試算 Phase 分け / §5.4 監視 dashboard) を同時反映