context-compression

コンテキスト圧縮の戦略

エージェントのセッションで会話履歴が数百万トークンに達すると、圧縮は必須になります。単純な方法は、リクエストあたりのトークン数を最小限に抑えるために積極的に圧縮することです。最適化の適切な目標はタスクあたりのトークン数です。これは、圧縮で重要な情報が失われた場合の再取得コストも含め、タスクの完了までに消費したトークンの合計です。

有効にするタイミング

次の場合に、このスキルを有効にしてください。

• エージェントのセッションがコンテキストウィンドウの制限を超える場合
• コードベースがコンテキストウィンドウを超える場合（500万トークン以上のシステム）
• 会話の要約戦略を設計する場合
• エージェントが変更したファイルを「忘れる」ケースをデバッグする場合
• 圧縮品質を評価するフレームワークを構築する場合
• 決定事項、ファイル、リスク、次のアクションを保持した、永続的な引き継ぎ用の要約を作成する場合

ほかのスキルが担当する、隣接領域の作業ではこのスキルを有効にしないでください。

• マスキング、プレフィックスキャッシュ、分割などの一般的なトークン効率化手法：context-optimization。
• 緩和策を選ぶ前に、長いコンテキストが機能しない理由を診断する場合：context-degradation。
• 要約せずに、生の出力、ログ、計画をファイルに書き込む場合：filesystem-context。
• セッションをまたいだ長期的な意味記憶を設計する場合：memory-systems。
• モデルが自らのコンテキストを書き換えるタイミングと場所を判断する場合：self-managed-context。ただし、置き換えるテキストで何を保持する必要があるかは、このスキルが引き続き担当します。

基本概念

コンテキスト圧縮では、トークンの削減と情報の損失を比較衡量します。セッションの特性に応じて、実運用に適した次の3つの手法から選択してください。

1. アンカー付き反復要約：ファイルの追跡が重要な長時間のセッションに実装します。セッションの目的、ファイルの変更内容、決定事項、次のステップを明示的なセクションに分けた、構造化された永続的な要約を維持します。圧縮が発生したら、新たに切り捨てられた範囲だけを要約し、最初から作り直すのではなく、既存の要約と統合します。これにより、要約を全面的に再生成するたびに蓄積するずれを防げます。再生成のたびに、モデルが優先度が低いと判断してもタスクには必要な詳細が失われるリスクがあります。構造化によって、各セクションが要約者の記入すべきチェックリストとして機能するため、情報がひそかに失われるのを防ぎ、情報の保持を強制できます。

2. 不透明圧縮：再取得コストが低く、トークンを最大限に削減する必要がある短いセッションに限って使用します。再構成の忠実度を最適化した圧縮表現を生成し、可読性を完全に犠牲にする一方で、99％以上の圧縮率を実現します。注意すべきトレードオフがあります。プローブベースの評価を実行しない限り、何が保持されたかを検証する方法はありません。そのため、デバッグや成果物の追跡が重要な場合には決して使用しないでください。

3. 全面的な再生成による要約：要約の読みやすさが重要で、セッションのフェーズが明確に分かれている場合に使用します。圧縮が発生するたびに、詳細で構造化された要約を生成します。弱点は、サイクルを繰り返すたびに詳細が累積的に失われることです。要約を全面的に再生成すると、そのたびに新たに要約し直すため、それ以前の要約で保持されていた詳細の優先度が下がる可能性があります。

詳細なトピック

リクエストあたりのトークン数ではなく、タスクあたりのトークン数を最適化する

リクエストごとのトークン数ではなく、タスクの開始から完了までに消費したトークンの合計を測定してください。圧縮によってファイルパス、エラーメッセージ、決定の根拠が失われると、エージェントは再調査やファイルの再読込、結論の再導出を行う必要があり、圧縮で節約した量よりはるかに多くのトークンを浪費します。リクエストあたりのトークンをさらに0.5％節約しても、再取得が20％増える戦略は、全体としてはコストが高くなります。主な品質指標として、再取得の頻度を追跡してください。エージェントがすでに処理したファイルの再読込を繰り返し求める場合、圧縮が過剰です。

まずアーティファクトの追跡に関する課題を解決する

アーティファクトの追跡情報の完全性は、圧縮評価（claim-context-compression-factory-benchmark）で見落とされがちな要素です。一般的な要約ではこの情報を確実に維持できないため、あらかじめ対策してください。

圧縮サイクルごとに、次のカテゴリを明示的に保持してください。

• 作成したファイル（フルパス）
• 変更したファイルと変更内容（ファイル名だけでなく、関数名も含める）
• 読み取ったものの変更していないファイル
• 具体的な識別子：関数名、変数名、エラーメッセージ、エラーコード

これらの詳細を要約者が記録することに頼るのではなく、エージェントの基盤に独立したアーティファクトインデックス、または明示的なファイル状態の追跡を実装してください。専用のファイルセクションを設けた構造化要約でも、長時間のセッションでは情報を漏れなく保持するのが困難です。

必須セクションで要約を構成する

情報が知らないうちに失われるのを防ぐため、明示的なセクションを設けて構造化要約を作成してください。各セクションは、要約者が記入するチェックリストとして機能するため、漏れを見逃さずに済みます。

## Session Intent
[What the user is trying to accomplish]

## Files Modified
- auth.controller.ts: Fixed JWT token generation
- config/redis.ts: Updated connection pooling
- tests/auth.test.ts: Added mock setup for new config

## Decisions Made
- Using Redis connection pool instead of per-request connections
- Retry logic with exponential backoff for transient failures

## Current State
- 14 tests passing, 2 failing
- Remaining: mock setup for session service tests

## Next Steps
1. Fix remaining test failures
2. Run full test suite
3. Update documentation

エージェントの分野に合わせてセクションを調整してください。デバッグエージェントには「根本原因」と「エラーメッセージ」が必要であり、移行エージェントには「ソーススキーマ」と「ターゲットスキーマ」が必要です。重要なのは特定のセクションではなく構造です。明示的なスキーマであれば、どのようなものでも自由形式の要約より優れています。

圧縮を実行するタイミングを戦略的に選ぶ

圧縮の方法と同じくらい、圧縮を実行するタイミングも重要です。セッションの予測可能性に基づいて、トリガー戦略を選択してください。

戦略	トリガーのタイミング	トレードオフ
固定しきい値	コンテキスト使用率が70～80％	シンプルですが、圧縮が早すぎる場合があります
スライディングウィンドウ	直近のNターン＋要約を保持	コンテキストサイズを予測しやすくなります
重要度ベース	関連性の低いセクションから圧縮	複雑ですが、重要な情報を維持できます
タスク境界	論理的なタスクの完了時に圧縮	要約は明確になりますが、タイミングを予測しにくくなります

コーディングエージェントには、構造化要約を組み合わせたスライディングウィンドウを標準として使用してください。予測可能性と品質のバランスに優れています。セッションに明確なフェーズの移行（例：調査、実装、テスト）がある場合は、タスク境界をトリガーにしてください。

指標ではなくプローブで圧縮を評価する

ROUGEや埋め込み類似度などの従来の指標では、圧縮の機能的な品質を評価できません。語彙の重なりが大きくても、エージェントが作業を続けるために必要なファイルパスが抜けている要約もあります。

プローブベースの評価を使用してください。圧縮後に、重要な情報が保持されているかを確認する質問をします。エージェントが正しく答えられれば、必要な情報が圧縮後も保持されています。そうでなければ、推測や幻覚が生じます。

プローブの種類	検証する内容	質問の例
想起	事実の保持	「元のエラーメッセージは何でしたか？」
アーティファクト	ファイルの追跡	「どのファイルを変更しましたか？」
継続性	タスクの計画	「次に何をすべきですか？」
判断	推論の過程	「Redisの問題について、何を決定しましたか？」

6つの観点で圧縮を評価する

コーディングエージェントの圧縮品質を、次の観点から評価してください。正確性とアーティファクト追跡情報の保持は、語彙の類似度よりも手法の違いを明確に示す傾向があります（claim-context-compression-factory-benchmark）。そのため、圧縮には一般的な要約とは別の、専門的な対応が必要です。

1. 正確性：ファイルパス、関数名、エラーコードなどの技術的な詳細は正確ですか？
2. コンテキストの把握：応答は現在の会話状態を反映していますか？
3. アーティファクトの追跡：どのファイルを読み取ったか、変更したかをエージェントは把握していますか？
4. 網羅性：応答は質問のすべての部分に対応していますか？
5. 継続性：情報を再取得せずに作業を続けられますか？
6. 指示への準拠：応答は明示された制約を守っていますか？

実践的なガイダンス

大規模なコードベースに三段階の圧縮ワークフローを適用する

コンテキストウィンドウを超えるコードベースやエージェントシステムでは、三段階のフェーズを順に経て圧縮します。各フェーズでコンテキストを絞り込み、次のフェーズが予算内で動作できるようにします。

1. 調査フェーズ：アーキテクチャ図、ドキュメント、主要なインターフェースを調べます。調査内容を、コンポーネント、依存関係、境界をまとめた構造化分析に圧縮します。出力：生の調査内容に代わる単一の調査ドキュメントです。

2. 計画フェーズ：調査ドキュメントを、関数シグネチャ、型定義、データフローを含む実装仕様に変換します。この段階で、500万トークンのコードベースは約2,000語の仕様に圧縮されます。

3. 実装フェーズ：仕様に沿って作業を進めます。コンテキストは、生のコードベースの調査内容ではなく、仕様と現在作業中のファイルに集中します。仕様はすでに簡潔なため、このフェーズでさらに圧縮が必要になることはほとんどありません。

圧縮の種としてサンプル成果物を活用する

手動での移行例や参考 PR が提供された場合は、コードベースを最初から調べるのではなく、目指すパターンを把握するためのテンプレートとして利用します。サンプルからは、静的解析では明らかにならない制約がわかります。変更後も維持すべき不変条件、変更によって問題が起きるサービス、適切な実装の形などです。

これは、エージェントが本質的な複雑さ（ビジネス要件）と偶発的な複雑さ（レガシーな回避策）を区別できない場合に、特に重要です。サンプル成果物には、その違いが暗黙的に記録されており、試行錯誤による調査に費やすトークンを節約できます。

アンカー付き反復要約を段階的に実装する

1. エージェントの領域（デバッグ、移行、機能開発）に合った明確な要約セクションを定義します
2. 最初の圧縮が必要になったら、切り詰められた履歴をそれらのセクションに沿って要約します
3. その後の圧縮では、新たに切り詰められた内容だけを要約し、既存の要約は再要約しません
4. 新しい情報を既存のセクションに統合し、情報を再生成するのではなく、ファイルパスと判断の識別情報を基準に重複を除去します
5. 各情報がどの圧縮サイクルに由来するかをタグ付けします。これにより、要約にずれが生じた場合のデバッグが可能になります

セッションの特性に合ったアプローチを選ぶ

次の場合は、アンカー付き反復要約を使用します：

• セッションが長時間続く（100件以上のメッセージ）
• ファイルの追跡が重要（コーディング、デバッグ）
• 情報が保持されていることの検証が必要

次の場合は、不透明な圧縮を使用します：

• トークンの節約を最大化する必要がある
• セッションが比較的短い
• 再取得のコストが低い（例：ファイルシステムへのアクセスが不要）

次の場合は、再生成型要約を使用します：

• 人間によるレビューで要約の解釈しやすさが重要
• セッションに明確なフェーズの区切りがある
• 圧縮が必要になるたびに、コンテキスト全体を確認しても問題ない

手法ごとに圧縮率を調整する

手法	圧縮率	品質スコア	トレードオフ
アンカー付き反復	98.6%	3.70	品質は最高で、圧縮率はわずかに低い
再生成型	98.7%	3.44	品質は良好で、圧縮率は中程度
不透明	99.3%	3.35	圧縮率は最高で、品質は低下

これらは、普遍的な定数ではなく、特定のソースに基づくベンチマーク値として使用してください（claim-context-compression-factory-benchmark）。再取得のコストが発生するタスクでは、一般にこのトレードオフは構造化されたアプローチに有利です。

例

例 1：デバッグセッションの圧縮

圧縮前のコンテキスト（89,000 トークン、178 メッセージ）：

• /api/auth/login エンドポイントで 401 エラー
• 認証コントローラー、ミドルウェア、セッションストアを追跡
• 古い Redis 接続を発見
• 接続プーリングを修正し、再試行ロジックを追加
• 14 件のテストが成功、2 件が失敗

圧縮後の構造化された要約：

## Session Intent
Debug 401 Unauthorized error on /api/auth/login despite valid credentials.

## Root Cause
Stale Redis connection in session store. JWT generated correctly but session could not be persisted.

## Files Modified
- auth.controller.ts: No changes (read only)
- middleware/cors.ts: No changes (examined)
- config/redis.ts: Fixed connection pooling configuration
- services/session.service.ts: Added retry logic for transient failures
- tests/auth.test.ts: Updated mock setup

## Test Status
14 passing, 2 failing (mock setup issues)

## Next Steps
1. Fix remaining test failures (mock session service)
2. Run full test suite
3. Deploy to staging

例 2：プローブによる応答品質の確認

圧縮後に「元のエラーは何でしたか？」と質問した場合：

良好な応答（構造化された要約）：

「元のエラーは、/api/auth/login エンドポイントからの 401 Unauthorized 応答でした。有効な認証情報を入力したユーザーにもこのエラーが返されていました。根本原因は、セッションストア内の古い Redis 接続でした。」

不良な応答（過度な圧縮）：

「認証の問題をデバッグしていました。ログインに失敗していました。設定の問題をいくつか修正しました。」

構造化された応答では、エンドポイント、エラーコード、根本原因が維持されています。過度に圧縮した応答では、技術的な詳細がすべて失われています。

ガイドライン

1. リクエストあたりのトークン数ではなく、タスクあたりのトークン数を最適化する
2. ファイル追跡用に明示的なセクションを設けた構造化要約を使用する
3. コンテキスト使用率が 70～80% に達したら圧縮を開始する
4. 全面再生成ではなく、段階的なマージを実装する
5. プローブベースの評価で圧縮品質をテストする
6. ファイル追跡が重要な場合は、アーティファクトの履歴を別途記録する
7. 品質をよりよく維持できるなら、圧縮率が多少低くなることを許容する
8. 圧縮品質の指標として、再取得の頻度を監視する

注意点

1. ツール定義やスキーマは絶対に圧縮しないでください：関数呼び出しのスキーマ、API 仕様、ツール定義を圧縮すると、エージェントの機能が完全に損なわれます。パラメーター名や型が要約によって削除されたツールは、エージェントから呼び出せません。ツール定義は圧縮を適用しない不変の基点として扱ってください。

2. 圧縮された要約は事実を幻覚することがあります：LLM が会話履歴を要約すると、元の内容にはなかった、もっともらしい詳細を持ち込むことがあります。元の内容を破棄する前に、圧縮後の出力を必ずソース資料と照合してください。特に、要約時に「丸められたり」捏造されたりする可能性があるファイルパス、エラーコード、数値には注意してください。

3. 圧縮によりアーティファクトへの参照が壊れます：ファイルパス、コミット SHA、変数名、コードスニペットは、圧縮時に言い換えられたり削除されたりします。エージェントが config/redis.ts を必要としているのに、要約に「設定ファイルを更新した」と書かれていると、再調査が必要になります。識別子は文章に埋め込まず、専用セクションでそのまま保持してください。

4. 初期のターンには、再現できない制約が含まれています：セッションの最初の数ターンには、タスクの設定、ユーザーの制約、アーキテクチャ上の決定が含まれていることが多く、これらは再導出できません。初期のターンは圧縮の対象外にするか、その制約をすべての圧縮サイクルで維持される永続的な前置きに抽出してください。

5. 高い圧縮率はサイクルを重ねるごとに損失が累積します：圧縮率 95% は一度だけなら安全に見えますが、繰り返し適用すると損失が累積します。圧縮率 95% で 3 回圧縮すると、元のトークンのうち残るのはわずか 0.0125% です。1 回の処理だけでなく、複数回の圧縮サイクルを想定して圧縮率を調整してください。

6. コードと文章には異なる圧縮が必要です：自然言語には冗長性があるため、文章はうまく圧縮できます。コードはそうではありません。関数シグネチャやインポートパスからトークンを 1 つ削除するだけで、コードが役に立たなくなることがあります。分野に応じた圧縮戦略を適用してください。文章のセクションは積極的に要約し、コードブロックと構造化データはそのまま保持します。

7. プローブベースの評価では、誤った安心感を得ることがあります：プローブは、尋ねられた内容しか確認しないため、重要な情報が失われていても合格することがあります。ファイル名だけを確認し、関数シグネチャを確認しないプローブセットでは、シグネチャの喪失を見逃します。評価の 6 つの側面すべてを網羅するプローブを設計し、評価の実行ごとにプローブセットを入れ替えて死角を避けてください。

統合

このスキルは、コレクション内の複数のスキルと連携します。

• context-degradation - 圧縮は劣化を軽減するための戦略です
• context-optimization - 圧縮は、多くの最適化手法のうちの1つです
• evaluation - プローブベースの評価は、圧縮のテストに適用できます
• memory-systems - 圧縮は、スクラッチパッドや要約メモリーのパターンに関連します
• self-managed-context - モデルが自身の圧縮編集をトリガーして適用する場合、このスキルは置き換え用のメモに何を保持するかを提供します

参考資料

内部資料：

• Evaluation Framework Reference - 読むタイミング：プローブベースの評価パイプラインを構築または調整する場合、あるいは圧縮品質評価のための採点基準やLLMジャッジの設定が必要な場合

このコレクション内の関連スキル：

• context-degradation - 読むタイミング：圧縮を軽減策として適用する前に、長時間のセッションでエージェントのパフォーマンスが低下する原因を診断する場合
• context-optimization - 読むタイミング：圧縮だけでは不十分で、より広範な最適化戦略（プルーニング、キャッシュ、ルーティング）が必要な場合
• evaluation - 読むタイミング：一般的なLLM-as-judgeの手法を含め、圧縮に特化したプローブ以外の評価フレームワークを設計する場合

外部リソース：

• Factory Research：AI エージェントのコンテキスト圧縮を評価する（2025年12月） - 読むタイミング：圧縮手法の比較に関するベンチマークデータや、36,000件のメッセージ評価データセットが必要な場合
• LLM-as-judge評価手法に関する研究（Zheng et al., 2023） - 読むタイミング：バイアスのパターンやキャリブレーションを理解するために、LLMジャッジによる採点を実装または検証する場合
• Netflix Engineering：「The Infinite Software Crisis」—大規模なコードベースにおける3フェーズのワークフローとコンテキスト圧縮（AI Summit 2025） - 読むタイミング：大規模なコードベース向けに3フェーズの圧縮ワークフローを実装する場合や、本番環境規模のコンテキスト管理を理解する場合

---

スキルのメタデータ

作成日: 2025-12-22 最終更新日: 2026-05-15 作成者: Agent Skills for Context Engineering Contributors バージョン: 1.3.0