ADR-0061: main↔sub workspace 間の handover prompt 構造と命名規約を確立

読み替え注記 (ADR-0156 corrigendum / 2026-06-18): 本 ADR の sub 表記は ADR-0156 により doc と読み替える。本 ADR は Accepted 後 Immutable のため本文は改変せず、この 1 行ヘッダのみを例外として挿入している (ADR-0156 §5.2 盲点 #3 / §References)。

• Status: Amended (ADR-0156 により役割名 sub→doc を統一・決定自体は有効)
• Mode: Standard
• Scope: platform
• Kruchten Type: Existence/Property
• Implementation Status: Done (PR #921 — template + how-to guide)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-22 19:32
• 承認日時 (JST): 2026-05-22 20:00 (Pipeline 通常 flow v2 48/50 通過)
• Review After: 2026-08-22 (3 ヶ月), 2026-11-22 (6 ヶ月), 2027-05-22 (1 年)
• Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

main workspace (~/projects/my-gas-project) と sub workspace (~/projects/my-gas-project-doc) を並行運用する開発体制で、セッション間引き継ぎを handover prompt 経由で行う運用が暗黙的に成立している。しかし明示的な運用 ADR が無く、Jr 入社 (2026-10) で属人運用崩壊のリスクが顕在化しつつある。

1.2 現状 (Current State / As-Is)

命名揺れ実件数 (n=3) — 過去 handover prompt の命名パターン:

• handover_2026-05-14_<topic>.md (single underscore)
• handover_2026-05-19_<topic>.md
• handover_2026-05-20_adr_0054_0055_sidebar_session.md (topic 内 underscore 多用、可読性低下)

Step 構造バラつき事例 (n=3):

• 2026-05-14 版: Step 1〜3 (pull / 確認 / 反映) 構造
• 2026-05-19 版: Step 1〜4 (pull / handover / 主要 doc / 派生案) 構造
• 2026-05-20 版: Step 1〜5 (pull / 保留 PR / 主要 doc / sub doc 更新 / 改善案) 構造 — 最も精緻

集計手順: ls tasks/prompts/handover_*.md で件数取得、各 file の冒頭 Step を grep し構造差異を集計。

1.3 課題 (Problem)

命名揺れと Step 構造バラつきが累積しており、Jr 入社後 (2026-10) は handover 頻度が現 ~1 回/月 → ~2-4 回/月想定。命名揺れ累積で参照困難化リスクが高まり、属人運用のまま Jr 引き継ぎが発生すると onboarding 工数増加が予想される。

参照困難化の具体ケース (n=1, 実測):

• 2026-05-20 handover セッション中、handover_2026-05-20_adr_0054_0055_sidebar_session.md を tasks/prompts/ から探す際、ファイル名の adr_0054_0055_sidebar_session 部分が _ を multiple 使用しており、grep handover_*.md の結果 list で 「どの adr / どの session か」を即座に判別できず ~3-5min ロス。当時は handover 件数が 3 件のみで顕在化しなかったが、Jr 入社後の累積で月次 ~10-20min/月の参照工数増を想定 (件数 × 判別コスト)。
• 集計手順 (再現): ls tasks/prompts/handover_*.md | awk -F_ '{print NF}' で _ 区切り field 数を分布、4 fields (date + topic_simple) vs 6+ fields (topic_with_underscores) を識別。本 ADR の <topic> 単一フィールド規約で本問題を構造的に防止。

1.4 制約・要件 (Constraints & Requirements)

• 配置場所は tasks/prompts/ に固定 (既存運用踏襲)
• handover prompt は target session 完了後に削除される短命運用、git log で履歴追跡可能であること
• ADR-0045 (docs/_internal/ 組織化) の 04_specs/templates/ 配置パターンに準拠
• AI Agent (Claude / Gemini / GPT) の世代交代に耐える形式
• 過去 handover 3 件は遡及 rename しない (歴史的記録、git log 参照可能)

1.5 目標 (Goals / To-Be)

handover prompt の 配置場所 / 命名規約 / Step 構造 / frontmatter / 削除運用 / template を ADR で確立し、Jr 入社時の引き継ぎ容易性と規約遵守率 ≥95% を達成する。Non-Goals: 過去 handover 全件の遡及 rename、CI 統合 (初期は self-check のみ)、Pipeline draft prompt との統合 (ADR-0042 別カテゴリ)。

2. 決定

handover prompt の配置場所 (tasks/prompts/)、命名規約 (handover_YYYY-MM-DD_<topic>[_<n>].md 他 4 種)、標準 5 Step 構造 (2026-05-20 版踏襲)、frontmatter 5 項目必須、短命運用 (削除 + git log 追跡) を本 ADR で明文化する。あわせて docs/_internal/04_specs/templates/handover_prompt_template.md と docs/_internal/05_how-to/handover_prompt_guide.md を新設する。命名 lint script は optional (規約遵守率 < 90% 観測時に実装)。

2.1 命名規約

• handover_YYYY-MM-DD_<topic>.md — セッション間引継ぎ (main → sub / sub → main 双方向)
• 同日複数 handover 時: handover_YYYY-MM-DD_<topic>_<n>.md (例: _1.md, _2.md) で topic 衝突回避
• sub_YYYY-MM-DD_<topic>.md — sub session 宛て個別依頼
• main_YYYY-MM-DD_<topic>.md — main session 宛て個別依頼
• impl_adr-NNNN_<topic>.md — ADR 実装プロンプト。NNNN は 4 桁固定 (impl_adr-0058_ ✅、impl_adr-58_ ❌)

2.2 標準 Step 構造 (5 step、2026-05-20 版踏襲)

• Step 1: pull (前提同期)
• Step 2: 前 session の保留 PR / 残課題の解消
• Step 3: 主要 doc 一読 (整合性確認)
• Step 4: sub 担当 doc 整合性更新
• Step 5: 改善案整理

2.3 frontmatter 必須項目

• type: handover-prompt
• target_session (例: claude-code (sub workspace))
• source_session
• session_date (YYYY-MM-DD)
• estimated_handover_effort (単位: 分、例: 30min or 2h 形式統一)

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 4 個選定)

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

3.2 評価軸 × 案スコア表

加重和は K.O. 通過候補のタイブレーク用 (Suhr 1999 CBA criterion 準拠)。

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

• 採用案 (ADR + template 化): handover prompt の命名 / Step / frontmatter / template を ADR で明文化。— Good: 暗黙運用の明文化、Jr 入社時の引き継ぎ容易、ADR-0045 templates 配置パターン踏襲 / Bad: ADR 化のオーバーヘッド、単独運用では費用対効果やや低
• 案 X1: docs/_internal/05_how-to/ に運用ガイドを追加 (ADR 不要): — Bad: 6-12 ヶ月後の再議論可能性が低いなら ADR 不要だが、本件は Jr 入社後の運用変化が予想され ADR 化が適切。K.O. 不通過候補
• 案 X2: 何もしない (暗黙運用継続): — Bad: 命名揺れ累積で参照困難化、Jr 引き継ぎコスト増。K.O. 不通過: #reliable=1
• 案 X3: ADR-0042 (LLM prompt lifecycle) を拡張して handover も統合: — Bad: ADR-0042 は Pipeline draft prompt (起案→PR 化) が主スコープ、handover prompt は 運用引継ぎ で性質が異なる (短命 vs 長期保持、自動化 vs 手動)。K.O. 不通過: #suitable=2 (ADR-0042 スコープを越境)
• 案 X4: ADR-0019 (Decision Pipeline LangGraph) と統合し prompt 全般を一元管理: — Bad: ADR-0019 は Pipeline インフラ自体の決定、handover prompt はその外側の運用、層が異なる。本 ADR §関連で「ADR-0019 との重複部分は Pipeline draft prompt のみ、handover prompt は別カテゴリ」と明示し責務分離を担保。K.O. 不通過: #maintainable=2 (層越境で管理複雑化)

5. 影響 (Consequences)

5.1 正の影響 (Good)

• Existence 影響: docs/_internal/04_specs/templates/handover_prompt_template.md (50 行) と docs/_internal/05_how-to/handover_prompt_guide.md (80 行) が新規導入され、handover prompt の標準形が単一参照点として確立
• Property 影響 (横断ルール): 命名規約 (handover_ / sub_ / main_ / impl_adr-NNNN_ 4 種) と標準 5 Step 構造、frontmatter 5 項目が tasks/prompts/ 配下で全 handover prompt に強制適用される
• Jr 入社 (2026-10) 時の onboarding 説明が ~30min × 1 回で完結する見込み
• ADR-0045 templates 配置パターンに準拠することで docs/_internal/ 組織化方針との整合性確保
• 月次 review (15min/月) で規約遵守率を観測可能、年間総運用工数 **3.5h/年**
• 命名揺れ修正 ~5min/件 × 2-4 件/月 (Jr 後想定) = ~0.2-0.4h/月削減、Jr onboarding 短縮 ~1h/件
• ROI: 初期 2-4h ÷ 削減 ~3-5h/年 = **6-12 ヶ月で回収** (Jr 入社後加速)

5.2 負の影響 (Bad)

• ADR 化のオーバーヘッド: template 作成 ~1-2h + how-to doc 作成 ~1-2h の初期投資
• 単独運用 (Jr 入社前) では費用対効果やや低、ROI が顕在化するのは Jr 入社後 (2026-10) 以降
• 過去 3 件 (handover_2026-05-14/19/20_*.md) は遡及 rename しないため、新旧命名規約が混在 (git log 経由参照は可能)
• Step 構造が将来変更 (例: Step 6 追加) された場合、template + how-to doc + 過去 handover 全件更新コストが発生
• AI Agent 世代交代 (Claude 4 → 5) で handover 形式の最適解が変化する可能性、1 年後再評価必要

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

• 命名 lint script (scripts/handover-prompt-lint.mjs ~50 行, ~1-2h) は optional: 規約遵守率 < 90% 観測時のみ実装、初期は self-check のみ
• CI 統合なし: handover は短命のため lint 自動化の ROI 低い
• AI Agent (Claude / Gemini / GPT) 周知: CLAUDE.md §Workspace 運用に 1 行リンク追加で完了
• 同日複数 handover 時の topic 衝突は _<n>.md suffix で吸収
• estimated_handover_effort は分単位表記 (30min / 2h どちらも可)
• 削除済 file の追跡は git log --all --diff-filter=D -- tasks/prompts/、復元は git show <SHA>:<path>
• 長命化したい handover は docs/_internal/05_how-to/<name>.md に移行 (frontmatter type: how-to に変更)

5.4 運用上の罠

5.5 コスト試算

6. 撤退条件 (Rollback Plan)

6.1 撤退判断指標

• 3 ヶ月後 (2026-08-22): handover prompt 起案件数 < 5 件 + 規約遵守率 < 90% → ADR Superseded、暗黙運用に戻る
• Jr 入社後 6 ヶ月 (2027-04) 時点で運用が機能しないなら how-to doc 化検討
• ADR Light → Standard 昇格判定: 起案件数 ≥ 30 件で常時参照される状態なら Standard 昇格

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

• (A) ADR Superseded のみ: template + how-to doc は touched せず保持、本 ADR Status を Superseded に変更
• (B) template 削除 + 参照切れ修復:
  1. docs/_internal/04_specs/templates/handover_prompt_template.md 削除
  2. docs/_internal/05_how-to/handover_prompt_guide.md 削除
  3. 既存 handover prompt の冒頭から template: handover_prompt_template.md リンクを削除 (sed 一括)
  4. CLAUDE.md §Workspace 運用 のリンクを削除
• (C) frontmatter 巻き戻し: 新命名規約準拠 handover prompt の frontmatter を削除 (旧無 frontmatter 形式に戻す)、削除工数 ~5min/件

6.3 検証可能な完了条件

6.4 Review After

• 3 ヶ月後 (2026-08-22): 規約遵守率 / 起案件数評価
• 6 ヶ月後 (2026-11-22): Jr 入社後 1 ヶ月の運用機能性評価
• 1 年後 (2027-05-22): how-to doc 移行 trigger 判定 (起案件数 ≥ 50)

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証手段 1 (手動): 月次 review チェックリスト (docs/_internal/06_ops/monthly_review_checklist.md に追加) — 命名 regex マッチ率 + Step 構造 grep + frontmatter 5 項目存在確認
• 検証手段 2 (機械, optional): scripts/handover-prompt-lint.mjs (初期 skip、規約遵守率 < 90% 観測時に実装、~50 行 / ~1-2h)
• 実行頻度: handover 起案時 (起案者 self-check) + 月次 review 1 回
• 違反時の対応: PR レビューで指摘 → rename / template リンク追加 / frontmatter 補完

6.6 負債化リスク

• リスク 1: 起案件数が 1 年で 10 件未満なら ADR の費用対効果疑問 → Superseded + how-to doc 化
• リスク 2: Step 構造が将来変更 (例: Step 6 追加) → template + how-to doc + 過去 handover prompt 全件更新コスト
• リスク 3: AI Agent の世代交代 (Claude 4 → 5) で handover 形式の最適解変化 → 1 年後再評価

7. 参照 (References)

• 関連 ADR:
  • ADR-0042 (LLM prompt lifecycle): handover prompt は Pipeline draft prompt とは別カテゴリ (短命 vs 長期保持、運用引継ぎ vs ADR 起案)。本 ADR §代替案 X3 K.O. で明示的に分離
  • ADR-0019 (Decision Pipeline LangGraph): ADR-0019 のスコープは Pipeline インフラ自体、本 ADR の handover は Pipeline 外側の運用層。重複部分の具体特定: ADR-0019 §関連 ADR で言及される「draft prompt」(Pipeline 入力) のみ重複、handover prompt (session 引継ぎ) は重複なし
  • ADR-0045 (docs/_internal/ 組織化): docs/_internal/04_specs/templates/ への template 配置の前例として準拠
• 関連 PR/Issue: -
• 外部資料:
  • 本セッション (2026-05-19〜20) 実例: tasks/prompts/handover_2026-05-20_adr_0054_0055_sidebar_session.md
  • memory: [[reference-handover-prompt-location]] (本 ADR の暫定 memory、採択時に Superseded)
  • 将来統合候補: Anthropic 公式 multi-agent handover ガイド (公開時に本 ADR を Superseded 検討)

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

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v1 (66 行) で 29/50 差し戻し → 10 採点項目に対応する改善反映 v2 → 48/50 で Standard 閾値 40 + Critical 閾値 45 双方クリア。ADR-0056 §8 / ADR-0058 §11 / ADR-0057 §8 / ADR-0059 §11 / ADR-0060 §8 で確立した §audit history パターンの 第六適用例。デフォルトでは折りたたまれており、▶ をクリックで展開する。

Status 遷移

• v1 起案 (2026-05-22 KV 投入) → Pipeline 通常 flow 29/50 差し戻し
• v2 改善 (10 採点項目に対応, +19 pt) → Pipeline 再投入 → 48/50 通過 → auto-PR #913 生成 (Proposed)
• 本 PR で Status: Proposed → Accepted に更新、改善余地 1 件 (§1.3 参照困難化 n=1 実測ケース) を同時反映