context-compressor

Context Compressor

問題が「能力不足」ではなく、主に「コンテキストが多すぎる」場合にこのスキルを使用します。

このスキルは、自己完結型のローカルパッケージです。MCP サーバーは必要ありません。トークンのプロファイリング、ローカルでの圧縮、証拠の確認、またはリポジトリ内で再現可能な圧縮ワークフローが必要な場合に使用してください。

このスキルでできること

付属の Python スクリプトを使用して、次のことができます。

1. 未圧縮と圧縮後のトークン使用量を測定する
2. 大きなテキストや変換した JSON ペイロードを圧縮する
3. 単純な要約ではなく、クエリに関連する証拠を保持する
4. 圧縮後の出力に、安全に回答するための十分な証拠が残っているか確認する
5. 安定したコンテキストを前方に、変動するクエリテキストを後方に配置し、キャッシュに適したプロンプトの組み立てを支援する

使用するタイミング

次のような依頼があった場合に、このスキルを使用してください。

• このファイル、トランスクリプト、ドキュメント、またはコードダンプを圧縮する
• モデルにコンテキストを送信する前にトークンコストを削減する
• プロンプトや RAG ペイロードをキャッシュに適した形にする
• 直近のターンを保持したまま、複数ターンの履歴を圧縮する
• セマンティック圧縮と、より軽量な抽出的ベースラインを比較する
• 圧縮後のコンテキストに十分な証拠が残っているか検証する

次の場合にも自動的に使用されます。

• コンテキストが 80K トークンに近づいた場合（spawn-token-guard.cjs が compression-reminder.txt を書き込みます）
• コンテキストが 120K トークンに達した場合（新たなスポーンの前に圧縮が必須です）
• コンテキストが 150K トークンに達した場合（レッドライン — 圧縮が完了するまで新たなエージェントをスポーンできません）

クイックワークフロー

次の順序をデフォルトとして使用してください。

1. まずプロファイリングを行う
2. 具体的な質問がある場合は query_guided を実行する
3. 正確性が重要で、十分性の確認が必要な場合は evidence_aware を実行する
4. 証拠が不十分な場合は、圧縮の強度を下げるか、検索範囲を広げる
5. 削減量、リスク、次に取るべき最も安全なアクションを報告する

ユーザーがコマンドを 1 つだけ求めている場合は、run_skill_workflow.py を使用してください。

コマンド

agent-studio リポジトリのルートから実行してください。必ず以下の正確なコマンドを使用してください。一般的な手順に置き換えてはいけません。

1. トークン使用量のプロファイリング

python .claude/skills/context-compressor/scripts/profile_tokens.py --file <path> --output-format auto

2. コンテキストの圧縮

python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode baseline --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode query_guided --query "<question>" --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode evidence_aware --query "<question>" --min-similarity 0.4 --output-format auto

3. フレームワーク JSON の変換と圧縮

python .claude/skills/context-compressor/scripts/compress_context.py --json-file <payload.json> --input-adapter auto --mode query_guided --query "<question>" --output-format auto

4. ワークフロー全体の実行

python .claude/skills/context-compressor/scripts/run_skill_workflow.py --file <path> --mode evidence_aware --query "<question>" --output-format auto --fail-on-insufficient-evidence

5. 証拠のみを検証

python .claude/skills/context-compressor/scripts/validate_evidence.py --file <path> --query "<question>" --min-similarity 0.4 --output-format json

6. TOON と JSON のガードを実行

python .claude/skills/context-compressor/scripts/benchmark_toon_vs_json.py

7. Node.js ラッパー（エージェント統合用）

node .claude/skills/context-compressor/scripts/main.cjs --query "<question>" --mode evidence_aware --limit 20 --fail-on-insufficient-evidence

モードの選び方

• baseline：具体的な質問がまだない場合の、迅速で汎用的な圧縮
• query_guided：QA、レビュー、対象を絞った抽出タスクに最適なデフォルト
• evidence_aware：重大な影響を伴う回答、監査、または明示的な十分性の指標が必要な場合に使用

出力に関する期待事項

このスキルを使用した場合は、結果を平易な言葉で要約してください。

1. 元のサイズと圧縮後のサイズ
2. 推定トークン削減量または圧縮率
3. 出力がクエリに特化しているか、汎用的か
4. 証拠が十分と思われるか
5. 重要な詳細が回答から抜け落ちるリスクがあるか

スクリプトが証拠不十分と判定した場合は、事実を誇張しないでください。圧縮後のコンテキストはまだ安全に使える状態ではないと伝え、より広範な処理を推奨してください。

同梱リファレンス

関連する場合にのみ、次のファイルを参照してください。

• references/workflow-guide.md：コマンドの選択、モードの選択、実行例
• references/prompt-caching.md：安定したプレフィックスの順序、キャッシュのテレメトリ、キャッシュに安全なプロンプト構造
• references/evaluation.md：スキルのベンチマーク方法と結果の解釈

評価用の構成

スタータープロンプトは evals/evals.json にあります。スキルを調整するときや、小規模で再現可能なベンチマークセットが必要なときに使用してください。

agent-studio との統合

圧縮トリガーパイプライン

1. compression-trigger.cjs がコンテキストの逼迫を検出し、compression-reminder.txt に書き込みます
2. Router がリマインダーを読み取り、このスキルを使用する context-compressor エージェントをスポーンします
3. エージェントがクエリコンテキストとともに run_skill_workflow.py を実行します
4. 実際の圧縮統計が compression-stats.jsonl に記録されます

メモリの永続化

圧縮後、MemoryRecord を使用して、抽出した学びを永続化します。

• gotchas.json：テキストに gotcha|pitfall|anti-pattern|risk|warning|failure が含まれる場合
• issues.md：テキストに issue|bug|error|incident|defect|gap が含まれる場合
• decisions.md：テキストに decision|tradeoff|choose|selected|rationale が含まれる場合
• patterns.json：上記以外の抽出した証拠のデフォルトの保存先

ccusage によるコスト追跡

圧縮の強さを決める前に、.claude/context/runtime/ccusage-status.txt を読み込み、現在のトークン使用量を確認します。このファイルは、ツールを使用するたびに ccusage-statusline.cjs によって自動更新されます。形式：

[tokens] 135,345 today (in: 14,850 / out: 120,495) | Cost: $127.4826
[cache] $627.2992 saved | 139,399,832 reads, 8,751,364 writes

ルーターはパイプラインの各マイルストーンで、必ずこれを表示しなければなりません（P0 ユーザーフィードバック）。代替手段：ccusage --no-color 2>&1 | tail -5。

絶対遵守事項

1. 必ず上記のスクリプトコマンドをそのまま使用します。一般的な CLAUDE.md のガイダンスに切り替えてはいけません。
2. 必ず圧縮前にプロファイルを実行し、入力サイズを把握します。
3. 正確性が重要な場合、クエリなしで圧縮してはいけません。evidence_aware モードを使用します。
4. 圧縮後、必ずMemoryRecord を使用して抽出した学びを永続化します。
5. 証拠が不十分な場合、決してはったりを言ってはいけません。より広範な処理を推奨します。
6. 必ず削減量、リスク、次に取るべき最も安全な対応を、平易な言葉で報告します。