session-handoff

ハンドオフ

新しい AI エージェントが曖昧さなくシームレスに作業を引き継げる、包括的なハンドオフドキュメントを作成します。長時間作業するエージェントのコンテキスト枯渇問題を解決します。

モードの選択

該当するモードを判断してください。

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

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

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

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

先回りして提案しますか？ 大きな進展があった後（5 件以上のファイル編集、複雑なデバッグ、重要な決定など）に、次のように提案してください。

「大きな進展がありました。このコンテキストを次回のセッションに引き継げるよう、ハンドオフドキュメントの作成をご検討ください。準備ができたら『create handoff』と言ってください。」

CREATE ワークフロー

ステップ 1：ひな形を生成する

スマートひな形スクリプトを実行して、事前入力済みのハンドオフドキュメントを作成します。

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py [task-slug] --model <your model ID>

例：python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py implementing-user-auth --model claude-opus-5-5

実行中のモデル ID を --model に渡してください。CLI から環境変数に設定されることはありません。指定しない場合、Model 行は [TODO] のままとなり、バリデーターでブロックされます。

対象プロジェクトのディレクトリで実行してください。ひな形は現在の作業ディレクトリから、プロジェクトのパス、Git ブランチ、最近のコミットを取得します。

継続中の作業に関するハンドオフ（以前の作業へのリンクを含む）の場合：

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

スクリプトは以下を実行します。

• 必要に応じて .claude/handoffs/ ディレクトリを作成する
• タイムスタンプ付きのファイル名を生成する
• タイムスタンプ、作成者（CLI とセッション ID）、モデル、ホスト名、プロジェクトパス、Git ブランチ、最近のコミット、変更したファイルを事前入力する
• 以前の作業から続ける場合、ハンドオフの連鎖リンクを追加する
• 編集するファイルのパスを出力する

ステップ 2：ハンドオフドキュメントを完成させる

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

1. 現在の状態の概要 - 現在何が起きているか
2. 重要なコンテキスト - 次のエージェントが必ず把握しておくべき重要な情報
3. 直近の次のステップ - 明確で実行可能な最初のステップ。各項目には情報源を記載します。情報源は、ユーザーの引用、またはユーザーがレビューした作業記録です。 ユーザーの引用とは、日付を含むユーザーの逐語的な発言です。記入済みの Q-n ans: も該当します。 ユーザーがレビューした作業記録とは、ユーザーがレビューした成果物のページまたは仕様書です。ハンドオフやエージェントのメモは該当しません。 自分のアイデアは「エージェントの提案（依頼されていないもの）」に記載します。
4. 決定事項 - 理由を含む選択（結果だけではありません）
5. 間違いと修正 - 証拠を含め、誤った方向への進行とユーザーによる修正を記録します。ルールの提案は ~/.agents/retro-inbox/pending/ に置き、そのファイル名だけをここに記載します。

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

ステップ 3：ハンドオフを検証する

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

python3 ~/.agents/skills/session-handoff/scripts/validate_handoff.py <handoff-file>

バリデーターは以下を確認します。

• [TODO: ...] のプレースホルダーが残っていない
• 必須セクションが存在し、内容が記入されている
• 検出可能なシークレット（API キー、パスワード、トークン）がない
• 参照先のファイルが存在する

バリデーターが BLOCKED と報告している間は、ハンドオフを確定しないでください。シークレット、残存する [TODO: ...] のプレースホルダー、必須セクションの欠落があるとブロックされ、ゼロ以外の終了コードが返されます。それ以外はすべて警告です。

ステップ 4：ハンドオフを確認する

ユーザーに次の内容を報告します。

• ハンドオフファイルの場所
• 検証結果（READY / BLOCKED）と警告
• 引き継いだコンテキストの概要
• 次回セッションで最初に行う項目

RESUME ワークフロー

ステップ 1：最近のハンドオフを確認する

複数のセッションが同じリポジトリで同時に作業することがあるため、最新のファイルが別の セッションのものかもしれません。最新のものだけでなく、最近のハンドオフを一覧表示します。

ls -lt .claude/handoffs/*.md | head -10              # newest first
grep -H -E '^- (Written by|Session|CLI|Model|Host):' .claude/handoffs/*.md   # writer: manual and compact handoffs

過去 2 日間に作成されたハンドオフのうち、タスクまたはファイルが自分の作業と重なるものをすべて読みます。 また、ユーザーが指定したハンドオフ、またはタスクのハンドオフチェーンでリンクされているハンドオフも、古くても読みます。 タスク、ファイル、チェーンリンクをもとに、自分のタスクに該当するハンドオフを選びます。 Written by: と compact-<session id>.md は、前のセッションである可能性もある作成者を示します。 作成者が異なることを、同時進行の作業の証拠として扱わないでください。 作成者が記載されていない場合、または UNCONFIRMED の場合、作成者は不明です。

ステップ 2：古さを確認する

ハンドオフのヘッダー情報（タイムスタンプ、ブランチ、コミット）を現在のリポジトリと比較します。

git log --oneline -- .            # commits since the handoff was written
git status --short                # uncommitted drift
git branch --show-current         # still the branch the handoff names?

別のブランチで作成されたハンドオフ、または多くのコミット分だけ遅れているハンドオフは、事実ではなく手掛かりとして扱います。記載された内容に基づいて行動する前に、すべてを再確認してください。

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

何らかの作業に取り掛かる前に、関連するハンドオフ文書を最後まで読みます。

ハンドオフがチェーンの一部（「Continues from」リンクがある場合）なら、全体像を把握するため、リンクされている前のハンドオフも読みます。

ハンドオフ内のどのセクションにある場合でも、記載されているユーザーがレビューした作業記録はすべて、全文を読みます。キーワード検索だけで確認してはいけません。

ステップ 4：コンテキストを確認する

対象範囲を示したり、ハンドオフに基づいて行動したりする前に、次を確認します。

1. プロジェクトディレクトリと Git ブランチが、ハンドオフに記載されたものと一致している。
2. 記載されたブロッカーが、現在もブロッカーである（その後、解決されている可能性があります）。 すべての Q-n とその ans: を先に読みます。記入済みの ans: がまだ実行されていない場合は、今回のセッションでそのまま引き継ぐべき指示です。空の ans: や Suggested の値は承認ではありません。
3. 記載された前提が現在も成り立っている。次のステップに関係する前提を確認します。
4. 変更されたファイルに、競合する作業が後から加えられていない。
5. Immediate Next Step の各項目を、その Source と照合する。Source を読み、記載された作業を裏付けていることを確認します。 Source がない項目は提案です。Source を確認できない項目は UNCONFIRMED です。 提案、UNCONFIRMED の項目、自分が新たに思いついたことを、ユーザーが指定した対象範囲として提示してはいけません。 ユーザーの引用は、ユーザーがレビューした作業記録より優先されます。ユーザーの引用どうしでは、後のものが優先されます。 エージェントが記載した項目が Source に優先することはありません。競合があれば報告し、対象範囲を示したり行動したりする前にハンドオフを修正します。

ステップ 5：作業を開始する

「Immediate Next Steps」の項目 #1 に取り掛かる前に、今回の実行に関する最新の人間による修正と承認を確認します。

作業中は、次のセクションを参照します。

• 「Critical Files」で重要な場所を確認する
• 「Key Patterns Discovered」で従うべき規約を確認する
• 「Potential Gotchas」で既知の問題を避ける

ステップ 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>]	スマートなひな形で新しいハンドオフを生成する
validate_handoff.py <file>	完全性、品質、セキュリティを確認する

一覧表示と古さの確認にスクリプトは不要です。上記の RESUME ワークフローを参照してください。

references/

• handoff-template.md - ガイダンス付きの完全なテンプレート構成