最終更新: 2026/06/22 18:56
commonid: handover-prompt-guidetype: how-tostatus: active
pageaudience: both

handover prompt 運用ガイド (ADR-0061 / 命名 + Step + 削除運用 + Jr onboarding)

Status: ADR-0061 (Accepted 2026-05-22) で確立した handover prompt の命名規約 / Step 構造 / frontmatter / 短命運用の how-to 解説。残タスク節の固定マーカー (§8) は ADR-0145 (Accepted 2026-06-12) で追加。 対象: main↔doc workspace を行き来する起案者 (代表取締役 + Jr 2026-10〜) と AI Agent (Claude / Gemini / GPT) 読了時間目標: 30 分以内 (ADR-0061 §6.3 DoD #5) template: handover_prompt_template.md を copy → 編集して起案

1. 概要

handover prompt は session 間 (main workspace ↔ doc workspace) の作業引継ぎを伝える短命ファイル。tasks/prompts/ 配下に置き、target session 完了後は git rm で削除する。削除しても git log で履歴追跡可能 (詳細 §5)。

2. いつ書くか

シナリオ使う命名例
doc で着手した作業を main で継続 (またはその逆)handover_YYYY-MM-DD_<topic>.mdPhase 1 完了後、Phase 2 を別 ws に引き継ぐ
doc session に作業依頼 (TODO/doc 整備)doc_YYYY-MM-DD_<topic>.mdmain から「この doc を doc workspace で書いて」
main session に作業依頼 (GAS 実装)main_YYYY-MM-DD_<topic>.mddoc から「この script を main で実装して」
ADR 実装プロンプト (Pipeline 経由 or 手書き)impl_adr-NNNN_<topic>.mdimpl_adr-0058_phase2.md

役割名 sub→doc 命名移行 (ADR-0156): 新規 handover は doc_ / _to_doc を正とする。旧 sub_ / _to_sub は読み取り専用 (新規生成しない)。過去ファイルは遡及 rename しないため、既存分を探すときは sub_ と doc_ の両パターンで grep する。Phase 5 (2026-12 予定) で sub 側を削除。

書かない場合: 1 session で完結する単発作業 / user 指示で十分な軽微タスク。

3. 命名規約の詳細 (ADR-0061 §2.1)

handover_2026-05-22_pr906_phase2.md     ✅
handover_2026-05-22_pr906_phase2_2.md   ✅ (同日複数の 2 番目)
impl_adr-0058_phase2.md                 ✅ (4 桁固定)
impl_adr-58_phase2.md                   ❌ (3 桁不可)
main_phase2.md                          ❌ (日付欠落)
  • 日付は JST、YYYY-MM-DD 形式
  • <topic> は kebab-case、~30 文字以内推奨
  • 同日複数 topic 衝突は _<n> (1-indexed) で順序付け

4. Step 1-5 構造の意図 (ADR-0061 §2.2)

Step意図省略可?
Step 1: pull前提同期、保留 PR / 前 session 反映取込❌ 必須
Step 2: 保留 PR / 残課題の解消前 session で N/A としていた事項の再評価△ 該当なければ「N/A」明記
Step 3: 主要 doc 一読target session 編集範囲の整合性確認❌ 必須
Step 4: doc 担当 doc 整合性更新main 実装完了後の sub doc 反映△ main → sub のみ
Step 5: 改善案整理次 session への申し送り / ADR 候補 / memory 候補◯ 推奨

将来 Step 6 (例: link-check 確認) 追加可能性は ADR-0061 §5.3 で言及済、Supersede ではなく追記で対応。

5. 短命運用 (削除 + git log 追跡)

target session 完了後の削除は推奨だが必須ではない (個人判断)。削除後の追跡:

# 削除済 handover の履歴を見る
git log --all --diff-filter=D -- tasks/prompts/

# 特定 SHA 時点の handover を復元 (read-only)
git show <SHA>:tasks/prompts/handover_2026-05-22_pr906.md

# 削除済 file を作業ブランチに戻す
git checkout <SHA>~1 -- tasks/prompts/handover_2026-05-22_pr906.md

長命化したい handover は docs/_internal/05_how-to/<name>.md に移行し、frontmatter type: how-to に変更。

6. frontmatter 5 項目 (ADR-0061 §2.3)

---
type: handover-prompt                                      # 固定
target_session: claude-code (doc workspace)                # 受け取り側
source_session: claude-code (main workspace)               # 送り側
session_date: 2026-05-22                                   # YYYY-MM-DD
estimated_handover_effort: 30min                           # 30min / 1h / 2h 形式
template: handover_prompt_template                         # 任意、DoD #4 採用率カウント用
---

7. よくある罠と対処 (ADR-0061 §5.4)

罠対処
同日複数 handover topic 衝突_<n>.md suffix で順序付け (例: _1.md / _2.md)
estimated_handover_effort 単位揺れ (30 min vs 30min)スペースなしの 30min / 1h / 2h 形式に統一
削除後の追跡漏れ§5 の git log --all --diff-filter=D でリカバー可能、慌てて再起案しない
impl_adr-NNNN_ 桁数揺れ (impl_adr-58_)4 桁固定、起案前に ls tasks/prompts/impl_adr-* で既存形式確認
handover prompt 長命化 (テンプレ化したい)docs/_internal/05_how-to/<name>.md に移行、type: how-to 化
過去 handover への遡及 renamerename しない方針 (ADR-0061 §5.2)、過去 file は git log 経由参照

8. 残タスク節の固定マーカー (ADR-0145)

handover の残タスクは、見出しを一字一句固定した H2 節に書く:

## 残タスク(優先順)

この節は scripts/generate-coverage-gaps.mjs が抽出し、docs サイトの handover 残タスク一覧 (COVERAGE_GAPS.md) へビルド時に自動転載する。ページ側は自動生成のため直接編集しない。

ハイブリッド契約 (ADR-0145 ミニ改訂 2026-06-18): 抽出は「取りこぼしゼロ + 推奨マーカーへの寄せ」の二段構えになっている。

  • 硬い保証: 現役 handover (tasks/prompts/handover_*.md) は抽出可否によらず必ずページへ載る。残タスク節を機械抽出できない handover も「未構造・要マーカー」行で出る (静かに脱落しない)。
  • 寛容抽出: 正準マーカーに加え、同義の節見出し (「次にやること」「次の一手」「残り」「残っている設計判断」「継続タスク」「未着手」等) も吸収する。それでも ## 残タスク(優先順) が推奨形。
  • 督促: 推奨マーカーも同義見出しも無い handover は --check が「未構造」として列挙する。推奨マーカーへ寄せると正準扱いになる。

書き方:

  • 正準形は全角括弧・空白なしの ## 残タスク(優先順)。空白や半角括弧、同義見出しからも抽出されるが、正準形に揃えるのが推奨
  • 第 1 階層 1 項目 = タスク 1 件 (番号付きリスト推奨・優先順に並べる)
  • 手順書・討議論点・地雷メモはこの節に書かない (別の H2 へ)。この節は「次セッション以降に残る作業」だけを置く

消化の反映 (このページからの消し方):

  • 新しい handover を書くときは、直前 handover のマーカー節から消化済みタスクを削除してから書く (ADR-0145 §5.3)
  • 全タスクを消化した handover は tasks/prompts/archive/ へ退避する (ADR-0134)。退避した handover は走査対象外になる
  • どちらの操作も次回ビルドの再生成でページへ反映される

検査: node scripts/generate-coverage-gaps.mjs --check が ①ページと handover の乖離 ②最新 handover 4 週以上未更新 (幽霊エントリーの疑い) ③並走系列の重複エントリー ④未構造 (フォールバック行) handover の列挙 を warn する (PR はブロックしない)。抽出層が壊れて現役 handover の取りこぼしが起きた場合だけ exit 1 (硬い保証の backstop)。この backstop が実際にジョブを赤くするのは生成器を直接走らせる coverage-gaps-sync.yml (push:main / cron) で、PR 段階の不変条件は tests/coverage-gaps-generator.test.mjs (子プロセス統合テスト) が adr-lint workflow で守る。

適用範囲: 走査対象は tasks/prompts/handover_*.md のみ (doc_* / sub_* / main_* / impl_* と archive/ 配下は対象外)。

9. Jr 入社時 onboarding チェックリスト

新規 onboardee は以下を 30 分以内に通読:

  • 本 doc §1-5 (概念 + 命名 + Step + 削除運用) + §8 (残タスクマーカー)
  • ADR-0061 §2.1-2.3 + §5.4 (規約根拠)
  • handover_prompt_template.md (雛形)
  • 既存 handover 1〜2 件 (例: tasks/prompts/ の最新ファイル) を実例として読む

10. 関連

  • ADR-0061 (本規約の根拠): docs/adr/0061-handover-prompt-struct-naming-convention-main-sub-ws.md
  • ADR-0145 (残タスクマーカー + 残タスク一覧ページ自動生成): docs/adr/0145-repurpose-coverage-gaps-page-for-handover-tasks.md
  • 雛形 template: docs/_internal/04_specs/templates/handover_prompt_template.md
  • ADR-0042 (Pipeline draft prompt — 別カテゴリ、混同注意): docs/adr/0042-*.md
  • ADR-0019 (Decision Pipeline 刷新 — LangGraph 移行。ADR-0061 §7 が層分離対象として挙げる): docs/adr/0019-drp-migration.md
  • ADR-0045 (docs/_internal/ 組織化、templates 配置パターン): docs/adr/0045-organize-docs-internal-document-management-policy.md