session-handoff

Handoff

完全なハンドオフドキュメントを作成し、新しい AI エージェントが曖昧さなしに作業をシームレスに引き継げるようにします。長時間実行されるエージェントがコンテキストを使い果たす問題を解決します。

モードの選択

どのモードが該当するかを判断します。

ハンドオフを作成しますか？ ユーザーが現在の状態を保存したい、作業を一時停止したい、またはコンテキストが一杯になりつつある場合です。

• 以下の CREATE ワークフローに従います。

ハンドオフから再開しますか？ ユーザーが前回の作業を続けたい、コンテキストを読み込みたい、または既存のハンドオフに言及している場合です。

• 以下の RESUME ワークフローに従います。

プロアクティブな提案： 大きな作業（5 件以上のファイル編集、複雑なデバッグ、重要な判断）の後には、次のように提案します。

「大きな進展がありました。今後のセッションのためにこのコンテキストを保持するハンドオフドキュメントの作成を検討してください。準備ができたら「create handoff」と言ってください。」

CREATE ワークフロー

ステップ 1：スキャフォールドの生成

スマートスキャフォールドスクリプトを実行し、事前入力されたハンドオフドキュメントを作成します。

python scripts/create_handoff.py [task-slug]

例：python scripts/create_handoff.py implementing-user-auth

継続ハンドオフの場合（前回の作業にリンクする場合）：

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

スクリプトは次の処理を行います。

• 必要に応じて .claude/handoffs/ ディレクトリを作成
• タイムスタンプ付きのファイル名を生成
• タイムスタンプ、プロジェクトパス、Git ブランチ、最近のコミット、変更されたファイルを事前入力
• 前回の作業から継続する場合は、ハンドオフチェーンのリンクを追加
• 編集用のファイルパスを出力

ステップ 2：ハンドオフドキュメントの完成

生成されたファイルを開き、[TODO: ...] のセクションをすべて埋めます。以下のセクションを優先してください。

1. 現在の状態の概要 - 今まさに何が起きているか
2. 重要なコンテキスト - 次のエージェントが必ず知っておくべき重要な情報
3. 直近の次のステップ - 明確で実行可能な最初のステップ
4. 下した判断 - 結果だけでなく、理由を含む選択

ガイダンスとして、references/handoff-template.md のテンプレート構造を使用してください。

ステップ 3：ハンドオフの検証

検証スクリプトを実行し、完全性とセキュリティを確認します。

python scripts/validate_handoff.py <handoff-file>

バリデーターは次の項目をチェックします。

• 残っている [TODO: ...] プレースホルダーがないこと
• 必須セクションが存在し、内容が記入されていること
• 機密情報の可能性（API キー、パスワード、トークン）が検出されないこと
• 参照されているファイルが存在すること
• 品質スコア（0〜100）

機密情報が検出された場合、またはスコアが 70 未満の場合は、ハンドオフを確定しないでください。

ステップ 4：ハンドオフの確認

ユーザーに以下を報告します。

• ハンドオフファイルの場所
• 検証スコアと警告事項
• 取得したコンテキストの概要
• 次のセッションの最初のアクション項目

RESUME ワークフロー

ステップ 1：利用可能なハンドオフの検索

現在のプロジェクト内のハンドオフを一覧表示します。

python scripts/list_handoffs.py

これにより、すべてのハンドオフの日付、タイトル、完了状態が表示されます。

ステップ 2：鮮度の確認

読み込む前に、ハンドオフがどの程度最新かを確認します。

python scripts/check_staleness.py <handoff-file>

鮮度のレベル：

• FRESH：再開しても安全 - ハンドオフ以降の変更は最小限
• SLIGHTLY_STALE：変更を確認してから再開
• STALE：再開前にコンテキストを慎重に検証
• VERY_STALE：新しいハンドオフの作成を検討

スクリプトは次の項目をチェックします。

• ハンドオフ作成からの経過時間
• ハンドオフ以降の Git コミット
• ハンドオフ以降に変更されたファイル
• ブランチの乖離
• 参照されているファイルの欠落

ステップ 3：ハンドオフの読み込み

何らかの作業を始める前に、該当するハンドオフドキュメントを最後まで読みます。

ハンドオフがチェーンの一部である場合（「Continues from」リンクがある場合）は、完全なコンテキストを把握するために、リンク先の前回のハンドオフも読みます。

ステップ 4：コンテキストの検証

references/resume-checklist.md のチェックリストに従います。

1. プロジェクトディレクトリと Git ブランチが一致することを確認する
2. ブロッカーが解消されたかを確認する
3. 前提条件が依然として有効かを検証する
4. 競合がないか、変更されたファイルを確認する
5. 環境の状態を確認する

ステップ 5：作業の開始

ハンドオフドキュメントの「直近の次のステップ」の項目 #1 から始めます。

作業中は、次のセクションを参照してください。

• 重要な場所については「重要なファイル」
• 従うべき規約については「発見されたキーパターン」
• 既知の問題を避けるためには「潜在的な落とし穴」

Step 6: 作業中の更新とハンドオフの連鎖

作業を進める中で、次の点を行ってください。

• 「Pending Work」で完了した項目にマークを付ける
• 新たな発見を関連するセクションに追加する
• 長時間のセッションでは、--continues-from を使って新しいハンドオフを作成し、連鎖させる

ハンドオフの連鎖

長期間にわたるプロジェクトでは、ハンドオフを連鎖させてコンテキストの系譜を維持してください。

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

連鎖内の各ハンドオフは、次のとおりです。

• 直前のハンドオフへのリンクを持つ
• 古いハンドオフを置き換え済みとしてマークできる
• 新しいエージェントに向けてコンテキストの痕跡を提供する

連鎖から再開する場合は、まず最新のハンドオフを読み、その後必要に応じて前のハンドオフを参照してください。

保存場所

ハンドオフは .claude/handoffs/ に保存されます。

命名規則: YYYY-MM-DD-HHMMSS-[slug].md

例: 2024-01-15-143022-implementing-auth.md

リソース

scripts/

スクリプト	用途
create_handoff.py [slug] [--continues-from <file>]	自動スキャフォールディングを使って新しいハンドオフを生成
list_handoffs.py [path]	プロジェクト内で利用可能なハンドオフを一覧表示
validate_handoff.py <file>	完全性、品質、セキュリティを検証
check_staleness.py <file>	ハンドオフのコンテキストがまだ最新かどうかを評価

references/

• handoff-template.md - ガイダンス付きの完全なテンプレート構造
• resume-checklist.md - 再開するエージェント向けの検証チェックリスト