ハンドオフ

新しい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. Current State Summary - 現在何が起きているか
2. Important Context - 次のエージェントが必ず知っておくべき重要情報
3. Immediate Next Steps - 明確で実行可能な最初のステップ
4. Decisions Made - 根拠を含む選択（結果だけではなく）

ガイダンスについては 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: 作業を開始

ハンドオフドキュメントから「Immediate Next Steps」項目 #1 で開始します。

作業中にこれらのセクションを参照：

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

ステップ 6: ハンドオフを更新またはチェーンする

作業中：

• 「Pending Work」の完了項目をマーク
• 関連するセクションに新しい発見を追加
• 長時間のセッション：--continues-from で新しいハンドオフを作成してチェーンする

ハンドオフチェーニング

長時間実行されるプロジェクトの場合、ハンドオフをチェーンして、コンテキスト系統を維持します：

handoff-1.md (初期作業)
    ↓
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 - エージェント再開用の検証チェックリスト