headroom

Headroom — トークン削減のためのポータブルスキル

このスキルでは、あらゆるコーディングエージェントがコンテキスト内で Headroom の圧縮テクニックを適用する方法を説明します。Headroom のバイナリは必要ありません。

どの変換を適用するか

コンテンツの種類に応じて変換を選びます。ツールの結果が約200トークン未満の場合は、圧縮を省略してください。オーバーヘッドに見合いません。

エージェントが使用／貼り付けようとしているコンテンツ	適用する変換	ヘルパースクリプト
辞書／オブジェクトのJSON配列（ツールの結果、APIレスポンス）	SmartCrusher	scripts/smart_crusher.py
ビルド／テストログ（pytest、npm、cargo、make）	LogCompressor	scripts/log_compressor.py
grep／ripgrep／ag の出力（file:line:content）	SearchCompressor	scripts/search_compressor.py
ソースコード（Python、JS、TS、Go、Rust、Java、C/C++）	CodeCompressor	scripts/code_compressor.py
コンテキストの予算を超える会話履歴	RollingWindow	scripts/context_manager.py
モデルが書き戻そうとしているものすべて	Output Shaper（L2）	prompts/verbosity_steering.md

7つのルール

エージェントが内面化すべき基本ルールです。詳細は AGENTS.md を参照してください。ここでは簡潔に説明します。

1. 貼り付ける前に圧縮します。 約200トークンを超えるツールの結果を次のメッセージに貼り付ける前に、該当するヘルパースクリプトを実行します（スクリプトがない場合は、該当するヒューリスティックを手作業で適用します）。説明文ではスクリプトを明記します。「SmartCrusher で1,432 → 187トークンに圧縮（先頭3件、末尾2件、すべてのエラー、クエリに対するBM25上位5件を保持）。」
2. エラーは決して削除しません。 エラー、スタックトレース、is_error: true の結果、FAILED の行は最重要です。強く圧縮する場合でも、常に100％保持します。
3. 先頭からN件、末尾からN件を保持します。 配列、ログ、検索結果では、常に先頭の3件と末尾の2件を保持します。これらはページネーションのコンテキストと新しさを伝えます。
4. プレフィックスを安定させます。 プロンプトを組み立てる際は、リクエスト間でシステムプロンプトと最初のユーザーターンをバイト単位で同一に保ちます。プロバイダーのKVキャッシュを維持できるよう、動的なコンテンツ（タイムスタンプ、「今日は」などの記述、セッションID）はプロンプトの末尾に移動します。
5. 古いツール出力から削除します。 会話がトークンの予算を超えた場合は、古い側から完全な tool_call と tool_result のペアを削除します。ペアを分割してはいけません。システムプロンプトは決して削除しません。直近のユーザーターン2件も削除しません。
6. 自分の出力を整えます。 既定の冗長度はL2です。前置きを省き、画面に表示済みのコードを繰り返さず、path:line で参照します。ユーザーが簡潔さを求めた場合はL3（結論のみ）に下げます。ユーザーがすでに確認できるツールの結果を説明してはいけません。
7. 元に戻せるようにします。 ツールの結果を圧縮する際は、元の内容を .headroom-cache/<sha256>.txt に書き込み、説明文にSHAを含めます。「CCR key: a3f9…」。後のターンで元の内容が必要になった場合は、そこから取得します。

ここでいう「圧縮」とは

圧縮とは、選択であり、zip 圧縮ではありません。gzip は実行しません。保持する項目／行／ノードを選び、LLM がユーザーの質問に答えるために必要な情報を保った、より短い表現を出力します。元の内容は常に CCR キャッシュから取得できます。

選択ヒューリスティックは、優先順位の高い順に次のとおりです。

1. エラー — 常に保持します。
2. 先頭 N 件 — ページネーション／セットアップのコンテキストを保持します。
3. 末尾 N 件 — 直近の情報を保持します。
4. 異常値 — 平均値から 2σ を超える値（数値配列の場合）、または隣接する項目とフィールドが大きく異なる項目。
5. 関連項目 — ユーザーの現在の質問との BM25 類似度で上位 K 件。
6. 変化点 — フィールド値が遷移する項目（ステータスの切り替わり、カウンターのリセットなど）。
7. サンプル — 残りの項目から統計的に代表性のあるサンプルを選び、LLM が分布を把握できるようにします。

出力トークンの調整（「L2 のデフォルト」）

独自の返信を生成する際は、ユーザーが増減を求めない限り、prompts/verbosity_steering.md のレベル 2 に従ってください。5 つのレベルは次のとおりです。

• L0 — オフ
• L1 — 儀礼的な表現を省略（「すばらしいですね。では…」など）
• L2 — L1 に加え、すでに画面に表示されているコード／出力を繰り返さず、path:line で参照します (デフォルト)
• L3 — L2 に加え、結論のみを示し、求められない限り推論を省略します
• L4 — 断片的な表現にし、トークンを最小限にします

併せて適用する「エフォートルーティング」のルール：直前のターンが is_error: false のツール結果で、新たなユーザーの依頼がない場合、これは機械的な続行です。L3 で返信し、深い推論は省略します。直前のターンがエラーだった場合、またはユーザーから新しい質問があった場合は、通常どおり十分なエフォートをかけてください。prompts/effort_routing.md を参照してください。

このスキルのファイル

• AGENTS.md — 共通のエージェントルール（あらゆるエージェントフレームワークで機能します）。最初に読んでください。
• CLAUDE.md — 同じルールを Claude Code ／ Cursor 向けに記したもの。
• docs/techniques.md — 各変換処理の詳しい解説と、具体的な例。
• docs/integrations.md — エージェントごとのセットアップ（Hermes、Claw、Codex、Cursor、Aider、Goose、Continue、OpenHands、vibe、Copilot CLI）。
• docs/reversible-ccr.md — ディスク上の CCR キャッシュの規約。
• scripts/ — Python 標準ライブラリのみを使ったヘルパー。pip install は不要です。
• prompts/ — 出力調整用のシステムプロンプトの断片。
• examples/ — 各変換処理の変換前／変換後の比較。

重要な安全ルール（違反しないでください）

これらは、上流の Headroom にある安全ルールを反映したものです。それぞれが具体的な障害を防ぎます。

1. ユーザーまたはアシスタントのテキストは絶対に削除しないでください。 ツールの結果は圧縮できますが、人間が作成したメッセージは圧縮できません。
2. tool_call と tool_result のペアは絶対に分割しないでください。 片方を削除すると、もう片方の対応がなくなり、モデルが結果を捏造するおそれがあります。
3. 解析に失敗した場合は何も変更しません。 入力が想定された型として解析できない場合は、変更せずにそのまま渡してください。圧縮に失敗するより、圧縮しないほうが安全です。
4. 直近の情報は常に保持してください。 重要度スコアが低くても、直近 N 件のターン（デフォルトではユーザーターン 2 件）は絶対に削除しません。
5. システムプロンプトは常に保持してください。 絶対に削除しないでください。
6. エラーは 100% 保持してください。 例外はありません。
7. 冪等にしてください。 すでに圧縮済みの出力に圧縮処理を実行しても、何も変更されない（またはほとんど変更されない）ようにしてください。

クレジット

このスキルは、Tejas Chopra とコントリビューターによる chopratejas/headroom の技術を移植して再実装したものです。ライセンスは Apache 2.0 です。帰属表示の詳細については、NOTICE と README.md の「クレジット」セクションを参照してください。上流プロジェクトのほうが高速で、精度が高く、ML を活用しています。可能であれば、そちらをインストールしてください。