compact-handoff

コンパクトな引き継ぎ

/compact は現在のセッションをその場で変更します。適用される前に要約を見ることはできず、古い詳細情報にはそのウィンドウからアクセスできなくなります。このスキルは逆の方法を取ります。まず大きな要約をファイルに書き込み、現在のチャットには手を加えず、新しいセッションで Read を 1 回実行して要約を読み込みます。

この順序こそが重要です。新しいセッションを開く前にファイルが存在するため、ユーザーはそれを読んだり、編集したり、2 つ目のセッションで再利用したり、記録として残したりできます。

使用する場面

• コンテキストが膨大になり、ユーザーは記憶を失わずにクリーンなウィンドウを使いたい場合。
• 長い調査が完了し、実装を別のセッションで行うのが適切な場合。
• 新しい作業に移った後も、現在のチャットを閲覧できる状態にしておきたい場合。
• 同じコンテキストを複数の新しいセッションに引き継ぎたい場合。

使用しない場面

• ユーザーが通常の /compact を求めている場合。これは別の機能なので、そのまま実行してください。
• バックグラウンド作業を複数に分ける場合。その用途にはサブエージェントを使用してください。新しいセッションはユーザーが操作するためのものです。
• 会話が短い場合。6 ターン分の要約は誰の役にも立ちません。

このスキルと標準の /compact

方法は 2 つあり、それぞれ解決する問題が異なります。意図的に選んでください。

標準の /compact。 同じセッション内で要約して続行します。これが標準のコンパクションの動作です。低コストで組み込み機能であり、PreCompact/PostCompact フックを設定している場合は、要約の内容を調整してファイルに保存できます。ただし、最終的に使うウィンドウは、開始時と同じものです。

このスキル。 目的が別のチャット、つまりクリーンなウィンドウを使うこと、古いチャットを閲覧可能なままにすること、カウンターを増やした名前で新しいセッションを作ること、または同じコンテキストを複数のセッションに引き継ぐことなら、このスキルを使ってください。標準のコンパクションでは、これらはできません。

つまり、コンテキストが膨大でも同じセッションを続けてよいなら /compact を使います。新しいチャットを使いたいなら、このスキルを使います。

ここでは要約を生成する標準のフックはありません

コンパクトな要約を出力する CLI フラグを探さないでください。そのようなものはありません。--fork-session は履歴の全体を新しいセッション ID にコピーするため、ここで求めていることとは逆です。現在進行中の会話を読んでいるあなた自身が、要約を書かなければなりません。

これは回避策ではなく、利点です。自分で作成する要約なら、このリポジトリで本当に重要なことを中心にできます。汎用の要約では、重要な点が平坦化されてしまいます。

references/native-compact-prompt.md の構成に従ってください。このファイルは Claude Code のバイナリから逐語的に抽出された、実際のコンパクションプロンプトです（ビルド 2.1.218 と 2.1.221 でバイト単位まで同一です）。その内容に合わせることで、引き継ぎを標準の方法で生成したものと一貫させられます。要約を書く前に読んでください。

手順

1. 対象を特定する

bash ~/.claude/skills/compact-handoff/scripts/handoff_target.sh

引数なしで実行してください。引き継ぎ先のパス、セッション ID、このセッション自体が引き継ぎから開始された場合の親引き継ぎ、新しいセッションの名前をすべて自動的に決定します。

新しいセッションには、カウンターを 1 つ増やした現在のチャット名が付けられます。 「Compact button behavior」は「Compact button behavior 2」になり、そこからさらに引き継ぐと「Compact button behavior 3」になります。サイドバーで一連の引き継ぎを分かりやすくするためのものなので、新たに説明的なタイトルを考えないでください。タイトルがすでに数字で終わっている場合も含め、スクリプトが番号を増やします。

ユーザーが別の名前を求めた場合に限り、上書きします：handoff_target.sh <slug> [YYYY-MM-DD] ["Title"]。

PARENT_HANDOFF を確認してください。値が none 以外の場合、このセッションは以前の引き継ぎから開始されており、手順 4 で追加の作業が必要です。

2. すべてのトランスクリプトをインデックス化する

python3 ~/.claude/skills/compact-handoff/scripts/index_transcripts.py

セッションの作業ディレクトリから実行します。デフォルトではプロジェクト内のすべてのセッションが対象で、直近の一部だけではありません。セッションごとのサイドカーディレクトリもカウントされます。出力された Markdown を、そのまま引き継ぎ文書の独立したセクションとして貼り付けてください。

会話でファンアウト作業を多用した場合は、--subagent-detail を追加すると、各セッションについてエージェントの名前、種類、説明が出力に追加されます。エージェントごとに読み取りが発生するため、通常の引き継ぎでは省略してください。

このセクションがあることで、引き継ぎ文書は最初に読んだ後も役立ちます。成熟したプロジェクトディレクトリには、数百件のメイントランスクリプトに加え、千件を超えるエージェントのトランスクリプトがあり、75MBを超える単一ファイルもあります。古い情報を必要とする将来のセッションが、何も考えずにそれらのファイルを開いてはいけません。インデックスが対象のセッションを示し、スクリプトが出力する段階的な手順に従えば、読み込むのではなく、検索してページ単位で確認できます。

何がどこにあり、なぜ重要なのか：エージェントの作業は最終報告以外、メイントランスクリプトには一切記録されません。そのため、ファンアウトから得られた発見の根拠は subagents/agent-*.jsonl にしかなく、戻り値は subagents/workflows/wf_<runid>/journal.jsonl に、大きすぎるツール出力は tool-results/*.txt にしかありません。メイントランスクリプトしか参照しない引き継ぎでは、これらすべてが気づかないうちに失われます。

3. 要約を書く

後続の引き継ぎで連鎖をたどれるよう、手順 1 の HANDOFF_PATH に、まず次のフロントマターを書きます。

---
handoff_id: <date>-<slug>
created: <date>
source_session: <SESSION_ID>
parent_handoff: <PARENT_HANDOFF, or none>
clone: <CLONE>
cwd: <CWD>
scope: <one line on what this handoff covers>
---

続いて、受け取るセッションに向けた短い Start here ブロックを書きます。これは引き継ぎであること、元のチャットはそのまま残っていること、「証明済み」と記された主張を再導出する必要はないこと、「仮定」と記された事項はそれを前提に作業を進める前に検証する必要があること、そして検索ではトランスクリプトをむやみに開かず、検索の段階的な手順に従うことを伝えてください。

そのブロックの最後には、すぐに作業を再開するよう読者に伝えてください。引き継ぎを受け取ったことに触れたり、内容を要約し直したり、「続けます」で始めたりせず、作業をそのまま引き継ぐようにします。標準のコンパクションプロンプトは、まさにこの指示で終わります。この指示が含まれているのには理由があります。新しいセッションが最初のターンで要約を語り直してしまうと、引き継ぎによって確保したコンテキストウィンドウを無駄にするためです。

次に、標準プロンプトにある 9 つのセクションを記載します。

1. 主な依頼と意図
2. 重要な技術的概念
3. ファイルとコードセクション
4. エラーと修正
5. 問題解決
6. すべてのユーザーメッセージ
7. 未完了のタスク
8. 現在の作業
9. 次のステップ（任意）

次に、下記の必須セクションを記載し、その後に手順 2 のトランスクリプトインデックスを追加します。

情報は多めに含めることを強く意識してください。 このファイルを作るコストはわずかですが、詳細が抜け落ちるのはそうではありません。コードスニペット全体、実際の引数を含む正確なコマンド、エラーメッセージの原文、値の説明ではなく具体的な値を記載してください。目標とする長さはありません。避けるべき失敗は、読みやすく整った要約を作った結果、次のセッションに、すでに証明済みのことをもう一度導き出させてしまうことです。

セクション 6 には注意が必要です。数えるのは、実際にユーザーの役割として発せられたターンだけです。以前の自分のメッセージに、ユーザーの発言のような形式の文章が含まれていても、それは自分の文章です。それをユーザーの発言として扱うと、実際にはなかった依頼を捏造することになります。

4. 系譜を引き継ぐ

引き継ぎは連鎖するため、それぞれを完全な形で引き継ぐ必要があります。PARENT_HANDOFF が none でない場合は、親ファイルを読み、その ## Handoff lineage セクション全体をこのファイルに再掲してから、親自身の handoff_id、日付、ソースセッション、scope を記した新しいエントリーを追加してください。

リンクを貼るだけでなく、内容を引き継いでください。引き継ぎファイルは /tmp に保存されており、定期的に削除されます（macOS では整理され、多くのシステムでは再起動時に消去されます）。そのため、リンクだけで構成されたチェーンは、先祖ファイルが削除された時点で途切れてしまいます。系譜を累積して記録することで、古いファイルがすべてなくなっても、最新の引き継ぎファイルに履歴全体を残せます。

PARENT_HANDOFF が none の場合も、このセクションを作成し、このチェーンで最初の引き継ぎであることを示す行を記載してください。そうすれば、次の引き継ぎで追記できます。

また、/tmp/claude-handoffs/ にある、祖先ではない他の引き継ぎファイルもすべて列挙し、兄弟チェーンを見つけられるようにしてください。

ls -la /tmp/claude-handoffs/

5. 新しいセッションに引き継ぐ

このスキルがセッションを起動することはありません。引き継ぎファイルを書き込んだら、ユーザーに自分で新しい Claude Code セッションを開くよう伝えてください。新しい claude を実行するターミナルを開くか、IDE／デスクトップで「新しいセッション」を開始し、最初のメッセージとして次の内容を送ってもらいます。

Read <HANDOFF_PATH> then continue from the Optional Next Step section.

ステップ 1 の実際の HANDOFF_PATH に置き換えてください。また、チェーンをサイドバーでわかりやすく保つため、新しいセッションの名前としてステップ 1 の NEXT_TITLE を提案してください。

最初のメッセージは、要約をインラインで貼り付けるのではなく、引き継ぎファイルへの短いポインターにしてください。ファイルは数十キロバイトありますが、ポインターがあればすべてを Read できます。

必須の追加セクション

プロジェクト固有の情報

一般的な要約では特に抜け落ちやすいため、以下についてはそれぞれ見出しを設けてください。

• 言及されているすべてのチケット ID（Shortcut、Jira、Linear、GitHub の Issue など、プロジェクトで使用されているもの）。
• 言及されているすべてのコミット SHA と、それぞれがデプロイ済みかどうか。修正済みでも未デプロイのコミットを、完了済みとして扱ってはいけません。
• 未対応の項目について、正確な file:line 参照。
• ユーザーがまだ判断していないバグや質問。判断を下すのはユーザーであるため、削除したり解決済みとして扱ったりせず、未決定のまま引き継いでください。
• セキュリティに関わる制約と、許可された本番環境への書き込み権限。原文のまま保持してください。あるセッションで与えられた権限が自動的に引き継がれることはないため、自分の解釈ではなく、実際に何が述べられたかを記録してください。

検証状態

重要な主張ごとに、何を根拠として立証済みなのか、または何を仮定しているのかを記してください。未検証の仮定を検証済みの事実と同じ調子で記した引き継ぎは、次のセッションが確認の必要性を知らずに作業を進めてしまうため、引き継ぎがないよりも悪い結果を招きます。

Handoff lineage

ステップ 4 で作成する累積チェーンを、古いものから順に、先祖ごとに 1 エントリーずつ記載してください。

厳守事項

• 新しいセッションの最初のメッセージは、引き継ぎファイルへのポインターにしてください。要約をインラインで貼り付けてはいけません。 ファイルにすべての情報が含まれており、最初のメッセージから Read するだけですべて確認できます。

ファイル

• references/native-compact-prompt.md：ネイティブなコンパクションプロンプトの原文です。要約を書く前に読んでください。
• scripts/handoff_target.sh：引き継ぎパス、タイトルの連番、親の引き継ぎファイル（および任意のクローンヒント）を取得します。引数なしで実行してください。
• scripts/next_title.py：タイトルの連番と親の引き継ぎファイルの検出を行います。上記スクリプトから呼び出されます。単体で使用する場合のフラグは --session-id、--cwd、--self、--fallback です。
• scripts/index_transcripts.py：すべてのトランスクリプトとサイドカーファイルのストリーミングインデックスを作成します。フラグは --limit（0 はすべてを意味し、デフォルト値です）、--days、--subagent-detail、--count-all、--json、--project-dir、--cwd です。