smart-precompact

smart-precompact

タスクは、会話の中から引き継ぐ価値のある情報を取り出し、コンパクト化の後も初対面の相手と話しているように感じないよう、セッションを続けるためのプロンプトを引き渡すことです。

成功の基準：コンパクト化の後、すでに起きた間違いを繰り返さず、ユーザーがすでに答えた質問をせず、すでに却下された方法を提案しないことです。

速度の約束：実行は数秒で完了します。ファイル検索もフォルダーのスキャンも、find も行いません。このスキルはコンテキストがすでにいっぱいのときに実行されるため、不要な呼び出しはすべて自動コンパクト化を早めてしまいます。

言語：この手順は英語ですが、ユーザーに見えるすべての内容はユーザーのメッセージの言語に従います。受付行、ブロック 1、ブロック 2（「構築中：」や「失敗、再試行しない：」などのラベルは自然に訳してください）、ブロック 3 が対象です。変わらないものは 3 つあります。/compact コマンドそのもの、セッションからそのままコピーした文字列（エラー、パス、コマンド）、そしてフックが自身のファイルを認識するために使う引き継ぎファイルの 1 行目 # Handoff . <root> . <date and time> です。

---

実行モード

引数	動作
(空)	デフォルト。 ブロックを読み込み、フィルタリングして表示します。ディスクへの書き込みはゼロです
handoff	再開プロンプトをプロジェクト外の 1 つのファイルにも保存し、新しいセッションでそこから続けられるようにします
save	プロジェクト内にすでに存在するドキュメントファイルに項目を追加します
save notes	save と同様に、個人用メモフォルダーにも書き込みます。明示的に依頼された場合のみ、かつ config.md にパスが設定されている場合に限ります

モードは組み合わせられます。たとえば handoff save のように指定します。デフォルトでは何も変更しません。

言葉での依頼：「コンパクト化の準備をして保存して」または「明日続けられるようにして」＝ handoff。「それとドキュメントも更新して」＝ save。「メモにも追加して」または「Obsidianにも追加して」＝ save notes。どの言語で依頼されても、同じモードとして扱います。迷った場合はデフォルトにします。

自動トリガー（フック、省略可能）

scripts/compact_hook.py は scripts/install_hook.py でインストールします（README.md を参照）。 次の 2 つを行います。

1. コンパクト化の前： コンテキストが最初のしきい値（60%）を超えたときと、2 回目のしきい値（80%）を超えたときに、会話にメモを追加します。メモが表示されたら：
   • まずユーザーの質問に答えてください。 このスキルのためにユーザーの作業を止めないでください。
   • 同じ返信の最後に、メモにあるパスを使って、このスキルを handoff モードで実行します。
   • ユーザーのメッセージの言語で、コンテキストが X% を超え、/compact の行を用意したと 1 行で伝えます。2 回目のしきい値では、コンパクト化を促す表現を強めます。自動コンパクト化が実行される前に、今がコンパクト化のタイミングであることを伝えます（表示されたらプロンプト上部の帯にある Smart compact を使うか、行を貼り付けます）。
   • ユーザーが同じメッセージ内ですでにこのスキルを依頼していた場合は、1 回だけ実行し、handoff を追加します。
2. コンパクト化の後： セッションの引き継ぎファイルを自動的に会話に戻します。そのため、フックがインストールされていれば、ユーザーは帯にある Smart compact を押すか、/compact の行を貼り付けるだけで済みます。

---

ステップ 1：コンテキスト（コマンド 1 つ）

date "+%Y-%m-%d %H:%M"; echo "root: $(git rev-parse --show-toplevel 2>/dev/null || pwd)"; echo "session: ${CLAUDE_CODE_SESSION_ID:-none}"; git status --short 2>/dev/null | head -10; grep -qs compact_hook.py ~/.claude/settings.json && echo "restore-hook: on"

これだけです。ls もスキャンも行いません。root はプロジェクトのルートです。会話がサブフォルダーに移動していても、すべてのプロジェクトパス（docs/、CLAUDE.md）はここを起点に読み込みます。ブランチとコミットはプロンプトに含めません。Claude Code はコンパクト化の後と、新しい各セッションで、最新の Git の状態を自動的に読み込みます。

会話はすでに一度コンパクト化されていますか？（会話の一部が要約として表示されています。）セッションの引き継ぎファイルがあれば読み込みます（パスはステップ 4b に記載されているため、これは読み込みであり、検索ではありません）。そのファイルは、コンパクト化前の内容を記録したものです。ファイルがない場合は、会話の一部が要約としてのみ参照できることを受付行で伝え、その内容について憶測しないでください。

---

ステップ 2：トリアージ

会話を振り返ります。各項目について、**「これがなくなると、次のセッションで何がうまくいかなくなりますか？」**と考えてください。

重要度順の 5 つのカテゴリ：

1. 行き詰まり。 試したことと、失敗した理由です。最も損失の大きいカテゴリです。 これがないと、次のセッションで同じ方法を再び試してしまいます。
2. 決定事項。 Y ではなく X を選び、その理由があります。理由がなければ、それは決定事項ではありません。
3. ユーザーによる修正。 「違います、こうです」「必ずこうしてください」。ユーザー自身の言葉による作業ルールです。
4. 作業状況。 どのファイルに手を加えたか、どこまで作業が進んでいるか、何が未テストか。
5. 未完了項目。 残っている作業と、その優先順位。

正確な文言。 項目が文字列（パス、エラーメッセージ、フィールド名、コマンド）に依存する場合は、一字一句そのままコピーしてください。エラーメッセージを要約すると、すでに別のエラーメッセージになっています。

秘密情報は決して含めないでください。 API キー、トークン、パスワード、接続文字列、カード番号は、正確な文字列の中にある場合も含め、[REDACTED: what it is] に置き換えてください。ブロックはファイルに保存され、会話に貼り付けられます。そこに秘密情報が入った時点で、すでに外部に漏れています。

省略テスト

次の各項目を除外してください：

• git、コード、または CLAUDE.md にすでに記載されている（コンパクト化のたびに CLAUDE.md は再読み込みされます）
• 会話のその時点でのみ有効な内容（「ファイルを見せて」、途中段階の文言など）
• 後の結論で置き換えられた内容

平均的な項目は段落ではなく、1 行でまとめられます。項目が 8 件を超えた場合は、絞り込みが不十分です。

---

ステップ 3：ブロックの作成

reference/prompt-templates.md を読み、ディスクに書き込む前に両方のブロックを作成してください。引き継ぎファイルはブロック 2 のコピーなので、保存前にブロック 2 を完成させてください。

分け方：

• ブロック 2（再開プロンプト）は単独で完結します。 新しいセッションが読むファイルでもあり、新しいセッションには要約がありません。そのため、すべてを含めます。理由付きの行き詰まり、理由付きの決定事項、ルール、状況、ファイルへのポインター、次のステップです。
• ブロック 1（/compact の行）は、要約内の推論を守ります。 要約する側に、何を残し、何を圧縮するかを伝えます。作業状況は決して記載しないでください。
• 重複が許されるのは、行き詰まりとユーザーによる修正だけです。 失われた場合の損失が最も大きく、同じ間違いを繰り返すセッションより、1 行の重複のほうが負担は小さいためです。逆に言えば、行き詰まりを含む領域は「圧縮可能」にしてはいけません。

長さ：コンパクト行は最大 60 語、再開プロンプトは最大 200 語、「次にやること」は最大 3 ステップです。

---

ステップ 4：書き込み（依頼があった場合のみ）

save、save notes、または handoff の指示がなければ、このステップ全体を省略してください。

4a. 保存

root を基準に、すでに存在するファイルだけに書き込んでください。プロジェクト内にファイルやフォルダーを新規作成してはいけません。保存先がない場合は、記録行にその旨を記し、項目はブロック 2 に残してください。

内容	保存先	1 回あたりの上限
決定事項と行き詰まり	docs/DECISIONS.md	2
未完了項目、および完了した項目に付ける [x]	docs/TASKS.md	5
明示的な作業ルール	プロジェクトルートの CLAUDE.md	1 件。ほとんどの場合は 0 件

形式、例外的なケース、矛盾については reference/routing-table.md を参照してください。

CLAUDE.md に記載する基準。 このファイルは今後すべてのセッションで読み込まれ、重複した行を追加すると、以後の会話すべてでトークンを消費します。次の3 つすべてを満たす場合に限り、行を追加してください：（1）ユーザーが明示的に述べている（「必ず」「決して」「違います、こうです」）。ルールを推測してはいけません。（2）同じ内容が別の表現ですでに記載されていない（書き込む前に読み込んで確認する）。（3）削除すると今後の動作が変わる。迷った場合は書き込まず、候補があったことと、採用しなかった理由を記録行に記載してください。

追記のみ。 書き換え、削除、「整理」は禁止です。例外は 2 つだけです。完了したタスクに [x] を付ける場合と、ユーザーが直後に振り分けを修正した際に、この実行で自分が追加した行を訂正する場合です。書き込む前に読み込み、すでに記載されている項目は追加しないでください。

4b. ハンドオフ

パス： フックのメモにパスが記載されている場合は、それを使います。それ以外の場合は ~/.claude/handoffs/<first 8 characters of session>.md を使います。セッションが none の場合は、 ~/.claude/handoffs/<name of the root folder>.md を使います。

内容： 1 行目に # Handoff . <root> . <date and time from step 1>、空行を 1 行、その後にステップ 3 のブロック 2 をそのまま記載し、最後の行にブロック 1 を非表示コメントとして記載します：``。 Smart PreCompact mod はこの行を読み取り、ワンクリックでまったく同じコンパクト化を実行します。フックはファイルを会話に戻す前にこの行を取り除きます。セッションごとにファイルは 1 つだけで、実行のたびに上書きされます。アーカイブはありません。作業状態は古くなり、古いバージョンは誤解を招くためです。フックは 14 日間誰も触れていないファイルを削除し、1 行目で識別します。ヘッダーは変更しないでください。変更すると、そのファイルは削除されなくなります。このスキルがプロジェクトの外に作成するファイルはこれだけです。フォルダーがない場合は、 mkdir -p ~/.claude/handoffs を実行します。

4c. メモを保存する

パスとフォルダー名は、スキルフォルダー内の config.md に記載されています。検索しないでください。 パスがない場合、またはディスク上に存在しない場合は、レシートに 1 行記載してスキップします。形式： reference/routing-table.md。メモフォルダーには、まだ存在しない場合に限り今日のログを作成できます。また、判断ごとに新しいファイルを作成できます （<decisions>/YYYY-MM-DD <short title>.md）。

---

ステップ 5：出力

レシートは 1 行で、会話で使われている言語で記載します（最後のメッセージがコマンドだけの場合も同様です）。項目数、何をどこに書いたか、何をなぜ省いたか、見つかった矛盾、そして会話が以前にコンパクト化されていたかどうかを記載します。フックから実行した場合、この行には割合も含め、追加の行はありません。

続けて、bash ではなく text 型のブロックを、ブロック間にテキストを挟まずに出力します。（インターフェースによっては、bash ブロックに「実行」ボタンが表示され、クリックするとテキストがターミナルで実行されることがあります。）

モード	出力内容
handoff なし	ブロック 1、ブロック 2
handoff あり、restore-hook: on なし	ブロック 1（ファイルパスで終わる）、ブロック 2、ブロック 3
handoff と restore-hook: on あり	ブロック 1（ファイルパスで終わる）、ブロック 3。レシートには、再開プロンプトを保存し、コンパクト化の後に自動的に会話に戻ることを記載します

ブロック 3 は、新しいセッション向けの 1 文です：Read <path> and continue from there.

次のタスクは、今回の作業と関係ありませんか？ 1 行追加して、/clear を実行し、ブロック 2 または 3 で新しいセッションを始めるほうがよいと伝えます。新しいセッションはコンパクト化よりも低コストで、不要な要約も引き継ぎません。

出力前のセルフチェック

• すべての行き詰まりとすべての判断に理由がある
• ブロック 2 は、会話を見ていないセッションでも理解できる
• コンパクト化の行に状態を記載していない
• 60 語以内、200 語以内、次のステップは最大 3 つ
• 正確な文字列は一字一句そのままコピーされ、秘密情報は [REDACTED] に置き換えられている
• コンパクト化された箇所について、詳細を捏造していない

---

例

別の言語では、ラベルと本文をその言語にして、ブロックの形式は同じにします。

/compact Keep: why the checkouts/update webhook was rejected (it fired dozens of times
per cart and created duplicate emails), the exact wording of the 429 error from
Klaviyo, and the user's correction: "never send to real customers in tests". You can
compress the JSON debugging round and the log reading.

Continue where we left off.

Building: an automatic abandoned cart email for a Shopify store.
State: the function in jobs/cart.ts is written and tested on a demo cart. Not tested against real Klaviyo, not deployed.
Decisions: Klaviyo and not Mailchimp, because Klaviyo has a built-in cart event.
Failed, don't retry: the checkouts/update webhook (it fired dozens of times per cart,
  created duplicate emails). Error: `429 Too Many Requests: rate limit 75/s exceeded`.
Rules set: never send to real customers in tests, only to the test address.
Read before touching: docs/DECISIONS.md
Next up: 1) deploy to staging  2) test on the test address  3) show me before turning it on.

---

正確性に関する取り決め

把握していること：現在の会話の内容、このセッションで実行されたツールの出力、この実行で読み取ったファイル。

把握していないこと（ツールが必要）：

• 日付：ステップ 1 の date。記憶やコンテキストから取得してはいけません。
• 対象ファイルにすでに書かれている内容：書き込む前に Read します。推測してはいけません。

確認が必要な場合：項目が判断のように見えるものの、理由が明示されていない場合。理由を捏造してはいけません。1 行で質問するか、その項目を省きます。

対応を拒否する場合：ドキュメントファイル内の既存の内容の削除、圧縮、「クリーンアップ」を依頼された場合、または会話がすでにコンパクト化されていてハンドオフファイルがなく、コンパクト化された内容の詳細を求められた場合。捏造せず、その旨を明確に伝えます。

境界

許可されていること：会話を読むこと。ステップ 1 のコマンドを実行すること。既知のパスにあるファイル（対象ファイル、引き継ぎファイル、config.md）を読むこと。ブロックを表示すること。要求されたモードでのみ書き込みを行い、ステップ 4 の対象にのみ書き込むこと。

禁止されていること：自分で /compact を実行すること（ユーザーが貼り付けるか、Smart compact を押します。実行するとユーザーのコンテキストが消去されます）。ファイルやフォルダーを検索すること。プロジェクト内にファイルやフォルダーを作成すること。書き込みモードが要求されていないときに書き込むこと。4a の 2 つの例外を除き、既存の行を書き換えたり削除したりすること。シークレットをブロックやファイルにコピーすること。説明されていない決定理由をでっち上げること。このスキル自体はコミットもプッシュもしません。コミットを求める別個のユーザーリクエストは、ブロックの後に通常どおり処理します。