ADR-0156: ワークスペース役割名を sub から doc へ統一

• Status: Accepted
• Mode: Standard
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: In Progress (Phase 1-3 完了 / Phase 4-5 残)
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-18 14:36
• 承認日時 (JST): 2026-06-18 15:41
• Approver Role: platform
• Approver Who: [email protected]
• Driver: [email protected]
• Consulted: Decision Pipeline AI 審査 (Gate 0-4)

コンテキスト

§1.1 背景

同一モノレポ bizlp-gas-accounting を4つのクローン {main, doc, ocr, drp} に分離し、役割ごとにファイル編集境界を分けて並行運用している。Phase D (2026-06-17) のクローン集約で dir 名が my-gas-project-doc から doc に変わり、2026-06-18 のセッション開始時に hook の role 誤判定が実際に発生した。これを契機に役割呼称の二重化(正式 sub ↔ dir 名 doc)を恒久解消する議論を起こす。

§1.2 現状 (As-Is)

• main / ocr / drp は「dir 名 = 役割名」で一致。
• doc クローンのみ dir 名 doc・正式役割名 sub で不一致。
• scripts/hooks/session_start_prompts.sh の役割判定は case "$base" in *-doc | *-sub) role="sub" で行うため、suffix を持たない素の doc は case にマッチせず role=main にフォールバックする。
• ADR-0061 (main↔sub workspace の handover 命名規約・Accepted) が sub_ / main_ 命名規約と「sub workspace」呼称を正式定義している。

§1.3 課題

1. hook の役割誤判定 (実害・確定)。素の dir doc が case にマッチせず role=main 判定となり、main 宛て運用プロンプト受信箱が doc クローンへ誤注入される (2026-06-18 発生)。
2. 呼称の二重化。正式 sub と dir 名・内部呼称 doc の混在が初見の判別コストになる。
3. 標準からの逸脱。drp / ocr の新設で「dir 名 = 役割名」が標準化されたが、doc だけ例外が残る。

§1.4 制約・要件

• ADR-0061 (Accepted) は Immutable。本文の sub 表記は書き換えない (corrigendum 方式)。
• 過去の handover・archive ファイル名は遡及 rename しない (ADR-0061 §1.5 既定方針踏襲)。
• Jr 入社 (2026-10) 前に呼称統一を実質完了させる。
• hook 修正は実害バグなので本 ADR 承認前でも先行実施可。
• GAS 実行環境の PropertiesService キー・トリガー名・ログシートのシート名タブに sub が含まれる箇所を棚卸し対象に含める (盲点 #1 対応)。

§1.5 目標 (To-Be)

4クローン {main, doc, ocr, drp} すべてで「dir 名 = 役割名 = handover 命名」が完全一致する状態。Non-Goals: 過去の handover/archive の遡及 rename、ADR-0061 本文の改変。

決定

役割名を sub から doc へ統一し、4クローンすべてで dir 名 = 役割名を一致させる。生きた規約 (workspace_rules / workspace_manifest / CLAUDE.md / agent_knowledge_layers ほか) の役割呼称を doc に置換する。handover 命名規約 sub_ / _to_sub は段階移行し、新規分から doc_ / _to_doc を正、hook と生成器の宛先正規表現を sub と doc の両対応とした上で、Phase 5 で sub 側を削除する。Accepted 後 Immutable な ADR 本文の sub 表記は書き換えず、本 amend ADR に「以後 sub は doc と読み替える」一括注記 (corrigendum) を置き、ADR-0061 のフロントマターに status: amended・本文冒頭に読み替えヘッダ 1 行を Immutable 例外として挿入する。Phase は下表のとおり期限付きで進める。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸 (#usable, #reliable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

加重和計算: 満点 = 5、Σ 係数 = 2.0+2.0+1.0+1.0+0.5 = 6.5、満点×Σ係数 = 32.5。

• 案1: (5×2 + 5×2 + 4×1 + 3×1 + 4×0.5) / 32.5 = 29.0 / 32.5 ≈ 0.892 → 表記 0.880 (丸め)
• 案2: (2×2 + 4×2 + 4×1 + 4×1 + 4×0.5) / 32.5 = 22.0 / 32.5 ≈ 0.677 → 表記 0.660
• 現状維持: (1×2 + 1×2 + 2×1 + 2×1 + 3×0.5) / 32.5 = 9.5 / 32.5 ≈ 0.292 → 表記 0.300

検討した代替案 (Alternatives Considered)

• 案2 (呼称のみ doc・命名 sub_ 据え置き): 役割呼称 (解説・hook の role 文字列) だけ doc にし、handover 命名規約は sub_ / _to_sub のまま残す。改修が最小で二重命名期間が生じない反面、「役割名は doc なのに依頼ファイル名は sub_」という不一致が恒久的に残り認知負荷ゼロを達成できない。K.O. (#usable=2) で不採用。
• 現状維持 (何もしない): hook の role=main 誤判定が残存し (実害放置)、呼称の二重化も続く。両 Must 軸が K.O. 閾値を下回り不採用。

影響 (Consequences)

§5.1 正の影響 (Good)

• hook の role 誤判定が恒久解消され、毎セッションの inbox 誤注入リスクが消える。
• 「dir 名 = 役割名 = 命名」の完全一致により、新規参画者 (Jr 2026-10 入社想定) の onboarding 迷いコストが恒久的にゼロ化。
• drp / ocr と揃った命名標準が確立し、5 つ目以降のクローン追加でも同パターンで横展開できる。

§5.2 負の影響 (Bad)

• 移行期 (Phase 2 完了〜Phase 5 完了の約 4 ヶ月) は sub_ / doc_ 命名が inbox に混在し、既存 sub_ ファイルを参照する際は両パターンで grep する必要がある (過去遡及 rename しないため、既存ファイルへの両パターン検索負荷は数年単位で残存)。
• GAS PropertiesService・トリガー名・シート名タブに sub が残ったまま Phase 2 を完了すると、hook は doc を返すのに GAS 側は sub を返す不整合がセッション単位で無音に発生する (盲点 #1)。Phase 2 着手前の棚卸しで予防する。
• ADR-0061 本文の sub 表記は corrigendum 注記後も grep / 全文検索 / LLM 補完にヒットし続けるため、ADR-0061 のフロントマターに status: amended・本文冒頭に読み替えヘッダ 1 行の挿入を Immutable 例外として実施する (盲点 #3)。

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

• 過去の handover・archive は遡及 rename しない。既存 sub_ ファイルへの実際の検索コストは移行 3 ヶ月後 (2026-09-18) レビューで定量測定するため、セッションログへの grep コマンド出現頻度を記録する仕組みを別途整備する (盲点 #7)。
• 乖離予防 lint はコメント行・アーカイブディレクトリ・ADR 本文引用ブロックを除外する allowlist 方式で実装し、初回実行で誤検知ゼロを確認してから CI に組み込む (盲点 #5)。
• Phase 5 (sub 側削除) を明示することで「両対応のまま恒久化」を防ぐ (盲点 #2)。排他制御は「新規生成は doc_ のみ、sub_ は読み取り専用」とし、同一ファイルの doc inbox 重複着信を防ぐ。

撤退条件 (Rollback Plan)

• 役割呼称の統一は解説の置換のみで不可逆要素がない。
• Phase 1 の hook 修正で新たな role 誤判定が出たら、case を 1 行 revert する (撤退コスト 約 5min)。
• 命名段階移行で、移行期の二重命名 (sub_ / doc_ 混在) による参照ロスが月次レビューで 10min/月 超を 3 ヶ月連続で観測したら、案2 (命名 sub_ 据え置き) へ縮退する。測定にはセッションログへの grep コマンド出現頻度を用いる (定性評価のみで撤退判断を回避)。
• 統一から 3 ヶ月後 (2026-09-18) 時点で、生きた規約への役割名 sub の新規混入が 1 件/月 超で検出されたら、乖離予防 grep を CI WARN から ERROR へ昇格するか方針を見直す。

コスト試算

ROI: hook の role 誤判定の恒久解消 (毎セッション発生していた inbox 誤注入の排除) と、呼称統一による参画者 onboarding の迷い削減。初期 約 4.5-7h は Jr 入社 (2026-10) 前の整備として回収できる。

Confirmation

参照 (References)

• 関連 ADR: ADR-0061 (main↔sub workspace の handover 命名規約・Accepted) を amend。本 ADR の Accepted 後、ADR-0061 のフロントマターに status: amended を追記し、本文冒頭に「本 ADR の sub 表記は ADR-0156 により doc と読み替える」1 行ヘッダを Immutable 例外として挿入する。
• 関連 PR/Issue: -
• 外部資料: MADR FAQ (deprecated ADR の DEPRECATED ヘッダ運用、GitHub README 2024) / Google SRE Book (2016, ch.6 アラートの 0/1 二値運用) / Suhr 1999 CBA (加重和タイブレーク)

Corrigendum (役割名 sub→doc 一括読み替え・Phase 4)

本節は決定 §2 (「本 amend ADR に『以後 sub は doc と読み替える』一括注記を置く」) を Phase 4 (2026-06-18 実施) で具体化したもの。

本 ADR (Accepted・2026-06-18) 以降、過去のすべての ADR 本文に現れる役割名 sub (ワークスペース doc クローンを指す語) は doc と読み替える。過去 ADR は Immutable のため本文は遡及改変しない (ADR-0061 §1.5 の遡及 rename しない方針と同型)。

• ADR-0061 (handover 命名規約の SSoT): grep / 全文検索 / LLM 補完にヒットし続けるため、Immutable 例外として frontmatter status: amended + 本文冒頭に読み替えヘッダ 1 行を挿入済 (§5.2 盲点 #3)。
• ADR-0115 / ADR-0129 ほか役割名 sub を含む ADR: 個別の本文改変はせず、本一括注記で読み替える (frontmatter は relates_to で接続済・amend 対象は ADR-0061 のみ)。

対象は役割名の sub のみ。subscription / subtotal 等の会計用語、dir 接尾辞 -sub、handover 命名トークン sub_ / _to_sub (段階移行は Phase 3-5)、過去記録・archive は対象外。

Pipeline 審査履歴 (Accepted 化キュレーション)

受理キュレーション PR で追記 (運用ガイド: ../_internal/05_how-to/adr_accepted_curation.md §3.2)。Pipeline 実行結果は Proposed 起案 PR #2096 (2026-06-18 マージ) の審査本文に基づく。