← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0105type: adrstatus: accepted
pagemode: Standardkruchten: Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-06-02 00:00approved_at: 2026-06-02 21:26deciders: [email protected] (単独)business: meta
型付き辺: 出 6 / 入 1
関連: ADR-0023 ADR-0068 ADR-0091 ADR-0115 ADR-0050 ADR-0114 部分修正された: ADR-0139全体は INDEX →

ADR-0105: ADR・docs の専門用語に 3 階層分類と原語温存・初出グロス規約を導入する

  • Status: Accepted (PR #1322 merge = 受理の規約により 2026-06-02 受理。2026-06-11 の Status×Impl 整合調査で遡及反映・代表取締役指示)
  • Mode: Standard
  • Kruchten Type: Property
  • Scope: platform
  • Implementation Status: Done (PR #1322 — 規約導入 + パイプライン関連 16 ページ適用 + --check-terminology lint。冒頭 TL;DR 箇条のみ ADR-0139 Amend で廃止)
  • 起案者: [email protected] ([email protected])
  • 起案日時 (JST): 2026-06-02 00:00
  • 承認日時 (JST): 2026-06-02 21:26
  • Deciders: [email protected] (単独)

TL;DR（要旨・専門語ゼロ）: ドキュメントは専門用語と英単語が混ざって読みにくい。そこで用語を「IT 一般教養 / プロジェクト固有 / 専門フレーム」の 3 段階に分け、噛み砕く対象を後ろ 2 段階だけに限定する。専門語は日本語に置き換えず原語を残し、初出時にだけ 原語〔和訳＝一句〕 を併記する。地の文は日本語で書く。これで「やり過ぎ」も「英語だらけ」も避けられ、人にも LLM にも読みやすくなる。

1. コンテキスト

1.1 背景 (Background)

ADR は 100 本超に達し、本文に IT 用語と英単語が混在して可読性が下がっている。読み手 (将来の新規参加者・LLM Agent 双方) が用語の解釈で繰り返し停止する。

1.2 現状 (Current State / As-Is)

用語集 docs/architecture/glossary.md (arc42 ch.12 の SSoT) と、それを引いて docs サイト上にホバー定義を出す機構 (ADR-0068) は存在する。一方で、本文の書き方には「どの語を残し・どの語を噛み砕くか」の規約がなく、書き手ごとに英語密度がばらつく。

1.3 課題 (Problem)

噛み砕きの基準がないため 2 つの失敗モードが起きる。(1) 英語をそのまま並べて専門外に伝わらない。(2) 逆に当然語まで翻訳し冗長・誤訳になる。サンプル計測では 1 ドキュメントあたり 2〜5 語で読みが止まり、約 1 分の理解コストが生じている。

1.4 制約・要件 (Constraints & Requirements)

  • 既存 100 本超の ADR を一括書き換えしない (差分は触る機会に漸進適用)。
  • ADR-0068 の glossary ホバー機構・Pipeline Gate 2 の用語突合と整合すること (本文の語が glossary キーと一致し続ける)。
  • LLM の意味解像度を下げないこと (原語アンカーを保持)。
  • コード識別子・固有名詞 (INV / glossary.md / Cloudflare Queues 等) は参照保全のため不可訳。

1.5 目標 (Goals / To-Be)

専門語を 3 階層に分類し、原語温存＋初出グロス併記を規約化する。新規 ADR から自動適用し、書き手が忘れても lint が拾う。Non-Goals: 既存全 ADR の即時リライト、地の文の英語化。

2. 判断基準 (Decision Drivers)

ADR-0050 の Q42 9-tag MCDA を本 ADR にも適用 (WSM + K.O. criterion / Suhr 1999 CBA〔Choosing By Advantages〕準拠)。

2.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#usable[Must] (×2.0)専門外の読み手が入口で意味を取れるか
2#maintainable[Must] (×2.0)既存 100 本超を壊さず漸進適用できるか
3#suitableHigh (×1.0)glossary SSoT / ホバー機構 / LLM 突合との整合
4#operableHigh (×1.0)書き手の追加負荷と lint での自動担保
5#efficientMedium (×0.5)1 ADR あたりの適用工数

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

2.2 評価軸 × 案スコア表

各案を 0-5 で評価。加重和は (Σ score × 係数) / (満点 × Σ 係数) で正規化 (0.0-1.0)。

軸係数採択 (3 階層 + 原語温存 + 初出グロス)X1 日本語オンリー翻訳X2 現状維持X3 glossary ホバーのみ
#usable [Must]×2.05413
#maintainable [Must]×2.05234
#suitable High×1.05235
#operable High×1.04254
#efficient Medium×0.54255
加重和 (正規化、満点 32.5)0.9540.5230.5850.769
K.O. 通過 (Must ≥3)✓❌ (#maintainable=2)❌ (#usable=1)✓

採択首位 = 3 階層 + 原語温存 + 初出グロス。

3. 検討した代替案 (Considered Options)

  • 案 A: 3 階層分類 + 原語温存 + 初出グロス (採用)
    • Good, because 噛み砕き対象を Tier 1/2 に限定し「やり過ぎ」を機械的に防げる。
    • Good, because 原語アンカーが残り LLM の意味解像度と glossary 突合が保たれる。
    • Bad, because 書き手が初出グロスを付け忘れる余地がある (lint で補う)。
  • 案 B (X1): 全文を平易な日本語に翻訳 (日本語オンリー)
    • Good, because 表面的には日本語のみで読みやすく見える。
    • Bad, because 訳語が一意でなく LLM の概念アンカーを失う。glossary キー (英語) と本文が一致せずホバー・整合突合が崩れる。
  • 案 C (X2): 現状維持
    • Good, because 追加作業ゼロ。
    • Bad, because 英語密度のばらつきと理解コストが継続する (#usable=1 で K.O.)。
  • 案 D (X3): glossary ホバー (ADR-0068) のみに依存し本文ルールを置かない
    • Good, because 本文を一切変えずホバー定義が付く。
    • Bad, because ホバーは docs サイト限定で、raw markdown を読む LLM・GitHub 上の読み手には効かない。

4. 決定 (Decision Outcome)

採用: 案 A。理由: 噛み砕き対象を階層で限定しつつ原語を温存することが、人・LLM・既存機構 (glossary ホバー / Gate 2 突合) のすべてに同時に最適だから。

具体規約:

  • Tier 0 (IT 一般教養): API / CI / JSON / lint / regex / commit 等。そのまま。説明しない。
  • Tier 1 (プロジェクト固有語): INV / STL / Action A・B / マート更新 / 期ずれ 等。glossary 必須 ＋ 初出時に 原語〔和訳＝一句〕 を併記。
  • Tier 2 (専門フレーム語): Kruchten Type / K.O. criterion / phantom dependency / DLQ 等。glossary 必須 ＋ ホバー (ADR-0068) ＋ 初出時に一句のグロス。
  • 原語温存の原則: Tier 1/2 の専門語・略語・固有名詞は日本語に置換せず原語を残す。地の文 (説明) は日本語で書く。
  • 冒頭 TL;DR: Standard/Critical Mode の ADR は Status ブロック直後に専門語ゼロの要旨を 1 段落置く (Light は任意)。← 本箇条は ADR-0139 (2026-06-11 受理) の Amend で廃止。冒頭要約は「決定の早わかり」(ADR-0138) へ一本化し、新規 ADR に TL;DR 枠は置かない (既存実装 4 本は温存)。本 ADR の他の規約 (用語 Tier・原語温存・初出グロス) は不変。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • 新規参加者・LLM 双方の理解コストが下がり、onboarding が加速する。
  • 「どこまで噛み砕くか」が階層で機械化され、レビューの主観が減る。
  • glossary SSoT が本文の初出グロスと相互強化される。

5.2 負の影響 (Bad)

  • 書き手に初出グロス併記の小さな追加負荷が生じる (1 ADR あたり数分)。
  • 階層の境界 (Tier 0 か 1 か) に判断揺れが残る (allowlist と glossary で吸収)。

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

  • 既存 ADR は触る機会にのみ漸進適用するため、全面反映には時間がかかる (Neutral)。
  • lint は warn 運用 (filenum ≥ 105 限定) とし、既存 ADR を fail させない。

コスト試算 (Cost Estimate)

  • 初期 (AI 支援あり): ルール整備 (本 ADR + テンプレ + 執筆ガイド) 2-3h / glossary 拡充 ~1h / lint サブコマンド + テスト ~2h = 計 **5-6h**。
  • 初期 (手作業換算・参考): 上記 1.5 倍の **8-9h**。
  • 継続: 新規 ADR 1 本あたり初出グロス付与 ~3-5min、glossary 追加 ~5-10min/月。
  • 削減効果: 理解コスト 1min/doc × 月 20-30 doc 読み = **20-30min/月**、Jr 入社 (2026-10) 後に顕在化。

6. 撤退条件 (Rollback Plan)

  • 再評価トリガー: lint warn が月 30 件超で常態化、または書き手から「初出グロスが冗長」との不評が 3 件以上。
  • 判定タイミング: 3 ヶ月後 (2026-09-02) と 6 ヶ月後 (2026-12-02)。
  • 判定主体: 代表取締役。
  • ロールバック手順: (A) lint を推奨化に縮退 (5min) → (B) テンプレ・執筆ガイドから初出グロス必須記述を削除し推奨に格下げ (30min)。glossary 追加分は残置。

Confirmation (準拠確認 / Fitness Function)

  • 検証手段: node scripts/adr-lint.mjs --check-terminology docs/adr/ (glossary 未登録の大文字略語が初出グロスなしで使われていたら warn)。
  • 実行頻度: PR ごと (CI、warn 表示)。
  • 違反時の対応: warn をレビューで確認し初出グロス追記、または glossary / Tier 0 allowlist へ登録。月次で warn 件数 < 30 件、新規 ADR の初出展開率 ≥ 90% を確認。

7. 参照 (References)

7.1 プロジェクト内参照

  • 関連 ADR: ADR-0068 (glossary ホバー機構 / 補完並立) / ADR-0050 (Q42 MCDA) / ADR-0091 (lint backstop パターン) / ADR-0023 (ADR 構造標準)
  • 関連 PR/Issue: #NNN
  • 既存 doc: docs/architecture/glossary.md (用語 SSoT) / docs/_internal/05_how-to/writing-guide.md (執筆ガイド) / docs/adr/templates/template.md (ADR テンプレ)

7.2 設計根拠 (Theoretical Foundation)

  • arc42 ch.12 Glossary: arc42
  • Suhr, The Choosing By Advantages Decisionmaking System, Quorum Books, 1999 (ISBN: 1-56720-217-9)