Smart Handoff/Pickup ガイド - Claude Code セッション管理

Claude Code のセッションが切れても作業コンテキストを失わないための手法。
/smart-handoff でセッション終了時に作業状態を保存し、
/smart-pickup で新しいセッションから復元・照合する方法を解説。

- セットアップ手順
- 使い方フロー
- 実際のユースケース（バグ修正、長期プロジェクト、タスク切り替え）
- ベストプラクティス
- トラブルシューティング

Transcript

1.  Smart Handoff / Pickup ガイド Claude Code の作業状態を 保存・復元するカスタムコマンド  セッションをまたいだスムーズな再開とチーム引き継ぎを実現  SAVE CONTEXT /smart-handoff  RESTORE CONTEXT /smart-pickup  2025-12-26
2.  OVERVIEW 概要: コマンドと目的   導入のメリット  コンテキストの完全復元 中断後でも「どこまで進んだか」 「何を決定したか」を即座に思い出し、 シームレスに作業を再開できます。  複数タスクの並行管理 機能実装と緊急バグ修正など、異なるコンテキストを持つタスクを ファイ ル単位で切り替えられます。  チーム引き継ぎの効率化 生成された構造化ドキュメントを共有するだけで、 他メンバーへの作業移 管が完了します。    Session A  .md File  Session B CONTEXT FLOW   SAVE /smart-handoff セッション終了時に 作業状態を保存 RESTORE /smart-pickup 新しいセッションで 作業状態を復元 Page 2
3. PROBLEM & SOLUTION なぜ必要か: 課題と解決策   従来の課題 (Pain Points)  Smart Handoff による解決  作業状態をファイルに永続化 Markdownファイルに状態を保存し、いつでも完全に復元可能にする。  タスクごとに状態を分離 working-*.md でタスク別に管理し、スイッチングコストをゼロに。  引き継ぎドキュメント自動生成 構造化されたドキュメントを自動生成し、共有するだけで引き継ぎ完了。  アーキテクチャ決定を自動保存 会話から技術的な意思決定を抽出し、ADRとして記録に残す。  セッション切断による喪失 ネットワーク切断やタイムアウトで、コンテキストや作業途中の記憶が失われる。  複数タスクの並行管理 機能開発とバグ修正を行き来する際、コンテキストが混ざり混乱する。  チーム間の作業引き継ぎ 「どこまでやったか」の説明に時間がかかり、情報の伝達漏れが発生する。  技術的決定の記録漏れ なぜそのアーキテクチャを選んだか等の重要な決定背景が残らない。      Page 3
4. bash $ mkdir -p ~/.claude/commands ~/.claude/context # ディレクトリが作成されます  smart-handoff.md +  smart-pickup.md   ~/.claude/commands/ bash & claude $ ls -la ~/.claude/commands/smart-*.md -rw-r--r-- 1 user staff xxxx ... smart-handoff.md -rw-r--r-- 1 user staff xxxx ... smart-pickup.md claude> /smart- // Tabキーで補完されればOK SETUP セットアップ: ディレクトリとコマンド配置  1 ディレクトリ作成 コマンドファイルと作業状態ファイル（コンテキス ト）を保存するためのディレクトリを準備します。 2 コマンドファイルの配置 ~/.claude/commands/ に、ガイドに記載されて いる2つのMarkdownファイルを配置します。 3 セットアップの確認 ファイルが存在することを確認し、Claude Code で コマンドが補完されるかテストします。 Page 4
5. USAGE セッション終了時 /smart-handoff 作業状態の保存   実行フロー  コマンド実行 Claude Code上でコマンドを入力 /smart-handoff  保存先を選択 対話モードで保存先を指定  既存ファイル  新規作成  タスク名入力 新規作成の場合のみ入力 bugfix-login_  自動保存 会話履歴・Git状態・コードを解析し Markdown生成     1 2 3 4  実行結果イメージ ➜ /smart-handoff Analyzing session context... ? どのファイルに作業状態を保存しますか？ (Use arrow keys) ◦ working-contact-page.md • 新規作成 ? タスク名を入力してください: bugfix-login ✔ 作業状態を保存しました Page 5
6. USAGE セッション再開時 /smart-pickup 作業状態の復元・再開   実行フロー  コマンド実行 新しいセッションで開始 /smart-pickup  ファイル選択 再開したいタスクを指定  working-api.md  working-ui.md  自動照合 保存状態 vs Git現状 ブランチ コミット 変更ファイル  再開アクション 差分を確認し、 次のステップを提示     1 2 3 4  実行結果イメージ ➜ /smart-pickup ? どの作業状態を読み込みますか？ (Use arrow keys) • working-bugfix-login.md (2025-12-25 18:00) ◦ working-auth-feature.md Reading state & comparing with git... ## 作業確認 : ログインバグ修正 ブランチ: fix/login-bug ✓ (一致) フェーズ: 実装中 未コミット変更: ⚠ あり (UserService.ts) Page 6
7. CONTEXT DATA 保存される情報   セッション概要  タスク名 / 目的  現在のブランチ  フェーズとステータス   直近の活動  完了した作業項目  中断時の取り組み中タスク  思考プロセス・コンテキスト   技術的決定  アーキテクチャ構成  実装方針と選定理由  却下された代替案   コードコンテキスト  関連リポジトリ  重要ファイル / 変更箇所  Gitの状態 (差分・ステージ)   実装状態  フェーズごとの進捗率  未着手の機能一覧  既知の問題やバグ   次のアクション  再開時の具体的なステップ  実行すべきコマンド  検証・テストの手順  Page 7
8. USE CASE 01 バグ修正中のセッション切断   シナリオ: ログイン機能の不具合修正 Event 切断・中断 Status 原因特定完了 Decision 方針決定済み Action 実装開始...     WITHOUT SMART HANDOFF  WITH SMART HANDOFF - New Session -  再説明のコスト・手戻り発生  さっきのバグ修正の続きを... すみません、コンテキストが失われました。 どのバグで、何をしていましたか？ えっと、ログインの件で、UserService.tsを... ファイルの内容を見せていただけますか？ - New Session -  即座にコーディング再開可能  /smart-pickup  restored: working-bugfix-login.md おかえりなさい。ログインバグ修正の続きですね。 原因: トークン期限切れロジック 状態: UserService.ts 修正中 Page 8
9. USE CASE 02 長期プロジェクトの継続開発   シナリオ: 認証機能を3日間かけて実装 毎日の作業終了時に状態を保存し、翌日にコンテキストを維持したまま再開  feature/auth-implementation SMART HANDOFF のメリット  技術決定の継承 「なぜJWTを選んだか」 「Redisの設定はどうしたか」といった文脈が日をまたいでも 失われません。   フェーズ進捗の可視化 全体計画の中で「どこまで完了し」 「何が残っているか」を正確に把握してスタート できます。   次アクションの明確化 「昨日は何をしようとして終わったっけ？」と考える時間をゼロにし、即座にコード を書き始められます。  Day 1 設計フェーズ /smart-handoff  アーキテクチャ決定: JWT + Redis  新規作成: working-auth-feature.md Day 2 実装フェーズ /smart-pickup /smart-handoff  前日の設計コンテキストを復元して実装開始  進捗更新: JWT生成完了 / Redis連携完了 Day 3 完成フェーズ /smart-pickup  残タスク「ログアウトAPI」から即座に再開  全体テスト実行とPR作成へ Page 9
10. USE CASE 03 複数タスクの並行管理   シナリオ: お問い合わせ実装中に緊急バグ修正が発生 Resume Task A 再開 Task A お問い合わせ実装 Interrupt 💥 緊急バグ報告 Task B バグ修正対応     SMART CONTEXT SWITCHING FLOW  FILE MANAGEMENT STRUCTURE  ~/.claude/context/ working-contact-page.md Paused Branch: feature/contact Last: 14:05 working-bugfix-payment.md Done Branch: fix/payment-err Last: 15:25 Task A: Contact Page 14:00 実装作業中... 緊急割り込み発生  /smart-handoff Task B: Payment Bug 14:15 原因調査と修正完了  /smart-handoff Resume Task A 15:30 元の作業状態を復元 Page 10
11. BEST PRACTICES 推奨・非推奨 (Do / Don't)   Do (推奨) 効果的なコンテキスト保存のために   フェーズ完了時の保存 設計完了、主要機能の実装完了、テスト完了など、論理的な区切りで保存する。  離席前の保存 ランチ、会議、終業などの前に保存し、タイムアウトや不意のセッション切断に備える。  タスク切替時の保存 現在のタスクを保存してから新しいタスクを読み込み、コンテキストの混在を防ぐ。  重要決定後の保存 アーキテクチャやライブラリ選定など、重要な技術的決定をした直後に記録する。  PR提出時の保存 レビュー指摘対応に備え、PR提出時点の状態とコンテキストを保存しておく。  Don't (非推奨) 避けるべきアンチパターン   複数タスクの混在 1つのファイル（例: working-all.md ）に複数のタスク情報を混ぜない。復元時に混乱の元となる。  完了ファイルの放置 完了したタスクのファイルは削除またはアーカイブし、選択リストをクリーンに保つ。  細かすぎる保存 5分ごとやコード1行ごとの保存は不要。管理が煩雑になるだけでメリットが薄い。  進捗なしの保存 前回保存時から進捗がない状態での上書き保存は避ける（ファイルの更新日時が無意味になる） 。 Page 11
12. TROUBLESHOOTING トラブルシューティング   ファイルが見つからない File Not Found  症状 /smart-pickup 実行時にエラーが表示される  確認 $ ls -la ~/.claude/context/ # ファイルが存在するか確認  解決策 ディレクトリを作成: mkdir -p ~/.claude/context 正しいパスにファイルを移動 ファイル名が working-*.md 形式か確認  コマンドが認識されない Command Not Recognized  症状 /smart-handoff と入力しても補完されない  確認 $ ls ~/.claude/commands/ # ファイルの存在を確認  解決策 ファイルの拡張子が .md か確認 ファイルの先頭に frontmatter があるか Claude Code を再起動して再読み込み  Git状態との不整合 State Mismatch  症状 「ブランチが一致しません」等の警告が出る  仕様 これは正常な動作です。 保存時と現在の差分を報告しています。  対処法 記載されたブランチに切り替える: git checkout {branch} または、現在の状態でそのまま続行する Page 12
13. SUMMARY まとめと次のアクション   Key Takeaways  シームレスな再開 作業状態をファイルに永続化することで、セッション中断や日を またぐ作業でも、記憶に頼らず即座にコンテキストを復元。  タスク分離と管理 タスクごとにファイルを分けることで、複数プロジェクトの並行 作業や緊急の割り込みタスクへの切り替えがスムーズに。  自動ドキュメント化 技術的な意思決定、アーキテクチャ、残タスクが自動的に記録さ れ、チームへの引き継ぎ資料としても機能する。  Next Actions コマンド配置 commandsディレクトリ作成 mkdir -p ~/.claude... 終了時に保存 離席前に必ず実行 /smart-handoff 開始時に復元 新しいセッションで実行 /smart-pickup ファイル整理 完了ファイルは削除 rm working-*.md 1 2 3 4 Page 13