handoff

Handoff

次のコーディングエージェントまたは人間の開発者向けに、プロジェクト内で使うコールドスタート用の手引きとして .docs/handoff.md を管理します。このファイルには一時的なセッション状態のみを記録します。何が変わったか、何が決定されたか、何がブロックされているか、そして作業を再開するための正確な手順です。

Reference Files

ファイル	内容	読み込むタイミング
references/schema.md	Handoff のスキーマと行数制限ルール（原文のまま）	書き込み前に必ず
references/authority-boundaries.md	Handoff、メモリ、CLAUDE.md、計画、git の境界	書き込み前に必ず

When To Use

Handoff を使う場合	別の場所を使う場合
進行中の作業、未コミットの編集、現在のブランチ、ブロッカー、再開手順	コミット済みの履歴には git log
セッション単位の決定や失敗したアプローチ	長期的に有効なプロジェクト情報にはメモリまたは ADR
直近の検証状態と正確な次のコマンド	安定したセットアップ手順には CLAUDE.md
現在のロードマップの位置	戦略的なロードマップの内容には計画ファイル

Triggers

• 直接コマンド：/handoff、/handoff init
• 更新フレーズ：「update handoff」、「session handoff」、「refresh handoff」、「save handoff」
• 再開フレーズ：「cold-start primer」、「resume checklist」、「handoff to next session」
• Stop hook：.docs/handoff.md がすでに存在する場合、サイレントに更新

Prerequisites

• プロジェクトルートで git を利用できること。
• .docs/handoff.md へのプロジェクト書き込み権限。
• 任意のプロジェクト内マーカーファイル：
  • .docs/handoff.last-validation：最後に実行した検証コマンドと結果を記録します。
  • .docs/handoff.session：変更、決定、ブロッカー、参照情報に関する追加の箇条書きを記録します。

Workflow

1. モードを解決します。
   • /handoff init、または初期化ワークフローからの呼び出しで、.docs/handoff.md が存在しない場合は新規プロジェクト用のスタブを書き込みます。
   • /handoff、更新フレーズ、Stop hook からの呼び出しでは、ファイル全体を書き直します。
2. 信頼できる情報源を読み込みます。
   • references/schema.md を読み込み、スキーマの見出しを正確に維持します。
   • references/authority-boundaries.md を読み込み、生成するすべての handoff に権限境界の行を含めます。
3. リポジトリの状態を検出します。
   • git rev-parse --show-toplevel、git branch --show-current、git rev-parse --short HEAD、git status --porcelain を実行します。
   • porcelain status から変更済み、未追跡、ステージ済みのパス数を数えます。
   • Status セクションに、変更されたパスの上位 3～5 件を含めます。
4. 検証状態を検出します。
   • 直近のセッションコンテキストを優先します。現在のエージェントセッションで実際に実行したコマンドとその結果を確認します。
   • 利用可能な場合は .docs/handoff.last-validation を読み込みます。
   • どちらも存在しない場合は、合否を推測せず、「not recorded this session」と明示して不明であることを記録します。
5. セッションの実質的な内容を収集します。
   • 現在の会話、未コミットのパス、必要に応じてブランチのベース以降のコミットから、論理的な変更を要約します。
   • 決定事項とその理由を、2 文以内で記録します。
   • ブロッカーと未解決の質問は、実行可能な未チェック項目として記録します。
   • 次のセッションで無駄な作業を避けるうえで役立つ失敗したアプローチを含めます。
6. 全体を書き直して保存します。
   • .docs/handoff.md を追記せず、アトミックに置き換えます。
   • .docs/ が存在しない場合は作成します。
   • ファイル名は小文字の .docs/handoff.md にします。
7. 200 行以内にします。
   • レンダリング後の最終行数を数えます。
   • 200 行を超えた場合は、## What changed this session の内容を古いものから切り詰めます。
   • `` を挿入します。
   • それでも 200 行を超える場合は、必須の見出しをすべて維持したうえで、決定事項とブロッカーを新しく実行可能な項目に絞って簡潔にします。

Supported Operations

操作	コマンド	動作
更新	/handoff	現在のリポジトリとセッションの状態から .docs/handoff.md を書き直します
スキャフォールド	/handoff init	handoff が存在しない場合、空のスキーマスタブを作成します
Stop refresh	Stop hook	.docs/handoff.md がすでに存在する場合に限り更新します
ドライラン	uv run skills/handoff/scripts/handoff.py --dry-run	書き込まずに生成内容を表示します

実装上の注意事項

同梱のスクリプトは、コマンドとフックで使用される決定論的なベースラインです。

uv run skills/handoff/scripts/handoff.py --project-root "$PWD"
uv run skills/handoff/scripts/handoff.py --project-root "$PWD" --init

エージェントは書き込む前に、ライブセッションのコンテキストに基づいて入力済みの箇条書きを改善できますが、次の点は維持する必要があります。

• スキーマの見出しと順序。
• 権限の境界を示す行。
• ファイル全体を書き換えるセマンティクス。
• 200 行の厳格な上限。
• 暗黙のフォールバックではなく、不明な項目を明示すること。

グリーンフィールドのスキャフォールド

/handoff init として呼び出された場合、またはプロジェクトの初期化フロー中に .docs/handoff.md が存在しない場合は、空のプレースホルダーと実際の git メタデータを含むスキーマを書き込みます。これにより、init スクリプトを変更することなく、/init との統合ポイントを記録できます。

出力形式

.docs/handoff.md のファイルを 1 つだけ書き込みます。

必須の先頭行：

# Handoff — <project name>

**Last touched:** <ISO 8601 timestamp with timezone> · **branch:** `<branch>` · **HEAD:** `<short-sha>` · **session:** <model id>

トラブルシューティング

問題	解決方法
git リポジトリ内にいない	refresh の場合は明確に失敗させます。/handoff init の場合に限り、スキャフォールドではブランチ — と HEAD — を使用できます
.docs/ がない	書き込む前に作成します
検証状態を取得できない	「このセッションでは記録されていません」と書き、テストに合格したと主張しないでください
生成されたファイルが 200 行を超える	古い What changed の箇条書きを切り詰め、警告コメントを追加します
既存の handoff で大文字小文字の表記やルートパスが古い	自動的に移行しないでください。今後の refresh で収束するのは、そのプロジェクトで呼び出された場合に限られます

検証

• uv run python scripts/validate_evals.py
• uv run scripts/evaluate_package.py skills/handoff
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --dry-run
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --init --output <tmp-file>