コンテキスト圧縮

コンテキスト圧縮戦略

エージェントセッションが数百万トークンの会話履歴を生成する場合、圧縮は必須です。単純なアプローチは、リクエストあたりのトークンを最小限に抑えるために積極的な圧縮を行うことです。正しい最適化目標は、「タスクあたりのトークン」、すなわち、圧縮によって重要な情報が失われた場合の再フェッチコストも含めた、タスク完了までに消費される総トークン数です。

アクティブ化のタイミング

以下の場合にこのスキルをアクティブ化します。

• エージェントセッションがコンテキストウィンドウの制限を超えている
• コードベースがコンテキストウィンドウを超えている（500万トークン以上のシステム）
• 会話の要約戦略を設計している
• エージェントがどのファイルを変更したかを「忘れる」ケースをデバッグしている
• 圧縮品質の評価フレームワークを構築している
• 決定、ファイル、リスク、次のアクションを保持する耐久性のあるハンドオフサマリーを作成している

以下のような、他のスキルに属する隣接タスクではこのスキルをアクティブ化しないでください。

• マスキング、プレフィックスキャッシング、パーティショニングなどの一般的なトークン効率化戦略：context-optimizationを参照。
• 軽減策を選択する前に長いコンテキストがなぜ失敗するのかを診断する：context-degradationを参照。
• 生の出力、ログ、計画を要約せずにファイルに書き出す：filesystem-contextを参照。
• セッションを超えた長期的なセマンティックメモリの設計：memory-systemsを参照。
• モデルが自身のコンテキストをいつ、どこで書き換えるかを決定する：self-managed-contextを参照。このスキルは、置換テキストが保持しなければならないものを定義します。

中核的概念

コンテキスト圧縮は、トークン節約と情報損失のトレードオフです。セッションの特性に基づいて、3つの実用的なアプローチから選択します。

1. アンカー付き反復要約（Anchored Iterative Summarization）：ファイル追跡が重要な長時間実行セッションに実装します。セッションの意図、ファイル変更、決定、次のステップに関する明示的なセクションを持つ、構造化された永続的なサマリーを維持します。圧縮がトリガーされた場合、新しく切り詰められた範囲のみを要約し、既存のサマリーとマージします。これにより、サマリーをゼロから再生成する際に蓄積されるドリフトを防ぎます。再生成のたびに、モデルが低優先度とみなすがタスクには必要な詳細が失われるリスクがあります。構造化により、専用のセクションが要約者が埋めるべきチェックリストとして機能し、暗黙の情報損失を捉えるため、保持が強制されます。

2. 不透明圧縮（Opaque Compression）：再フェッチコストが低く、最大のトークン節約が必要な短期セッションに予約します。再構成の忠実度に最適化された圧縮表現を生成し、99%以上の圧縮率を達成しますが、解釈可能性を完全に犠牲にします。このトレードオフは重要です。プローブベースの評価なしに何が保持されたかを検証する方法はないため、デバッグや成果物追跡が重要な場合には決して使用しないでください。

3. 再生要約（Regenerative Full Summary）：サマリーの可読性が重要で、セッションに明確なフェーズ境界がある場合に使用します。圧縮がトリガーされるたびに、詳細な構造化サマリーを生成します。弱点は、繰り返しのサイクルにわたる累積的な詳細の損失です。各完全な再生成は新しいパスであり、以前のサマリーで保持されていた詳細を優先度を下げる可能性があります。

詳細トピック

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

タスク開始から完了までに消費される総トークン数を測定し、個々のリクエストあたりのトークン数ではありません。圧縮によってファイルパス、エラーメッセージ、決定の根拠が削除されると、エージェントは再探索、ファイルの再読み込み、結論の再導出を行う必要があり、圧縮によって節約されたよりもはるかに多くのトークンを浪費します。リクエストあたり0.5%多くのトークンを節約する戦略でも、再フェッチが20%増加する場合、全体としてコストが高くなります。再フェッチの頻度を主要な品質シグナルとして追跡します。エージェントが既に処理したファイルを繰り返し再読み込みするように要求する場合、圧縮が過剰です。

最初に成果物トレイル問題を解決する

成果物トレイルの整合性は、圧縮評価においてしばしば最も弱い次元です（claim-context-compression-factory-benchmark）。一般的な要約ではそれを確実に維持できないため、積極的にこれに対処します。

圧縮サイクルごとに、以下のカテゴリを明示的に保持します。

• 作成されたファイル（完全なパス）
• 変更されたファイルとその変更内容（ファイル名だけでなく関数名を含める）
• 読み込まれたが変更されていないファイル
• 特定の識別子：関数名、変数名、エラーメッセージ、エラーコード

サマライザーにこれらの詳細をキャプチャさせるのではなく、エージェントのスキャフォールディングに個別の成果物インデックスまたは明示的なファイル状態追跡を実装します。専用のファイルセクションを持つ構造化された要約でさえ、長いセッションでは完全性に苦労します。

必須セクションでサマリーを構造化する

暗黙の情報損失を防ぐ明示的なセクションを持つ構造化サマリーを構築します。各セクションは要約者が埋めるべきチェックリストとして機能し、省略を可視化します。

## セッションの意図
[ユーザーが達成しようとしていること]

## 変更されたファイル
- auth.controller.ts: JWTトークン生成を修正
- config/redis.ts: 接続プーリングを更新
- tests/auth.test.ts: 新しい設定用のモックセットアップを追加

## 行われた決定
- リクエストごとの接続ではなくRedis接続プールを使用する
- 一時的な障害に対する指数バックオフによる再試行ロジック

## 現在の状態
- 14テスト成功、2テスト失敗
- 残り：セッションサービステスト用のモックセットアップ

## 次のステップ
1. 残りのテスト失敗を修正
2. 完全なテストスイートを実行
3. ドキュメントを更新

エージェントのドメインに合わせてセクションを適応させます。デバッグエージェントには「根本原因」と「エラーメッセージ」、移行エージェントには「ソーススキーマ」と「ターゲットスキーマ」が必要です。特定のセクションよりも構造自体が重要であり、明示的なスキーマはフリーフォームの要約よりも優れたパフォーマンスを発揮します。

圧縮トリガーを戦略的に選択する

いつ圧縮をトリガーするかは、どのように圧縮するかと同じくらい重要です。セッションの予測可能性に基づいてトリガー戦略を選択します。

戦略	トリガーポイント	トレードオフ
固定しきい値	コンテキスト使用率70-80%	シンプルだが、圧縮が早すぎる可能性あり
スライディングウィンドウ	最後のNターン＋サマリーを保持	予測可能なコンテキストサイズ
重要度ベース	重要度の低いセクションを最初に圧縮	複雑だが信号を保持
タスク境界	論理的なタスク完了時に圧縮	クリーンなサマリーだがタイミングは予測不能

コーディングエージェントには、構造化サマリーとスライディングウィンドウをデフォルトとして使用します。これにより、予測可能性と品質の最良のバランスが得られます。セッションに明確なフェーズ遷移がある場合（例：調査→実装→テスト）は、タスク境界トリガーを使用します。

プローブを使用して圧縮を評価し、メトリクスに頼らない

ROUGEや埋め込み類似度などの従来のメトリクスは、機能的な圧縮品質を捉えることができません。語彙の重複スコアが高いサマリーでも、エージェントが継続するために必要なファイルパスが1つ欠けている可能性があります。

プローブベースの評価を使用します。圧縮後、重要な情報が生き残ったかどうかをテストする質問を行います。エージェントが正しく回答した場合、圧縮は適切な情報を保持しています。そうでない場合、推測または幻覚を起こします。

プローブの種類	テスト内容	質問例
想起（Recall）	事実の保持	「元のエラーメッセージは何でしたか？」
成果物（Artifact）	ファイル追跡	「どのファイルを変更しましたか？」
継続（Continuation）	タスク計画	「次に何をすべきですか？」
決定（Decision）	推論チェーン	「Redisの問題について何を決定しましたか？」

6つの次元で圧縮をスコアリングする

コーディングエージェントの圧縮品質を、これらの次元に沿って評価します。精度と成果物トレイルの保持は、語彙的類似度よりも方法を明確に区別する傾向があるため（claim-context-compression-factory-benchmark）、圧縮には一般的な要約以上の特別な処理が必要です。

1. 精度：技術的な詳細（ファイルパス、関数名、エラーコード）は正しいか？
2. コンテキスト認識：応答は現在の会話状態を反映しているか？
3. 成果物トレイル：エージェントはどのファイルが読み込まれたか、変更されたかを認識しているか？
4. 完全性：応答は質問のすべての部分に対処しているか？
5. 継続性：情報を再フェッチせずに作業を継続できるか？
6. 指示追従：応答は指定された制約を尊重しているか？

実践的なガイダンス

大規模コードベースに3フェーズ圧縮ワークフローを適用する

コンテキストウィンドウを超えるコードベースやエージェントシステムの場合、3つの連続したフェーズで圧縮します。各フェーズでコンテキストを絞り込み、次のフェーズが予算内で動作できるようにします。

1. 調査フェーズ：アーキテクチャ図、ドキュメント、主要インターフェースを調査します。調査結果を、コンポーネント、依存関係、境界の構造化された分析に圧縮します。出力：生の調査結果を置き換える単一の調査ドキュメント。

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

3. 実装フェーズ：仕様に従って実行します。コンテキストは、仕様とアクティブな作業ファイルに焦点が当てられ、生のコードベースの調査ではありません。仕様が既にコンパクトであるため、このフェーズでさらに圧縮が必要になることはほとんどありません。

サンプル成果物を圧縮シードとして使用する

手動移行の例や参照PRが提供された場合、コードベースをゼロから調査するのではなく、それをテンプレートとして使用してターゲットパターンを理解します。この例は、静的分析では表面化できない制約を明らかにします。どの不変条件が保持されなければならないか、どのサービスが変更によって壊れるか、クリーンな実装がどのようなものかなどです。

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

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

1. エージェントのドメイン（デバッグ、移行、機能開発）に一致する明示的なサマリーセクションを定義する
2. 最初の圧縮トリガーで、切り詰められた履歴をそれらのセクションに要約する
3. 後続の圧縮では、新しく切り詰められたコンテンツのみを要約する。既存のサマリーを再要約しない
4. セクションを再生成するのではなく、新しい情報を既存のセクションにマージし、ファイルパスと決定IDで重複を排除する
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エラー
• authコントローラー、ミドルウェア、セッションストアを追跡
• 古いRedis接続を発見
• 接続プーリングを修正し、再試行ロジックを追加
• 14テスト成功、2テスト失敗

圧縮後の構造化サマリー：

## セッションの意図
有効な資格情報にもかかわらず、/api/auth/loginで401 Unauthorizedエラーをデバッグする。

## 根本原因
セッションストア内の古いRedis接続。JWTは正しく生成されたが、セッションを永続化できなかった。

## 変更されたファイル
- auth.controller.ts: 変更なし（読み取りのみ）
- middleware/cors.ts: 変更なし（調査済み）
- config/redis.ts: 接続プーリング設定を修正
- services/session.service.ts: 一時的な障害に対する再試行ロジックを追加
- tests/auth.test.ts: モックセットアップを更新

## テストステータス
14成功、2失敗（モックセットアップの問題）

## 次のステップ
1. 残りのテスト失敗を修正（セッションサービスのモック）
2. 完全なテストスイートを実行
3. ステージングにデプロイ

例2: プローブ応答品質

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

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

「元のエラーは、/api/auth/loginエンドポイントからの401 Unauthorized応答でした。ユーザーは有効な資格情報でこのエラーを受け取りました。根本原因はセッションストア内の古いRedis接続でした。」

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

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

構造化された応答は、エンドポイント、エラーコード、根本原因を保持しています。過剰圧縮の応答は、すべての技術的詳細を失っています。

ガイドライン

1. リクエストあたりのトークンではなく、タスクあたりのトークンに最適化する
2. ファイル追跡のための明示的なセクションを持つ構造化サマリーを使用する
3. コンテキスト使用率70-80%で圧縮をトリガーする
4. 完全な再生成ではなく、インクリメンタルマージを実装する
5. プローブベースの評価で圧縮品質をテストする
6. ファイル追跡が重要な場合は、成果物トレイルを個別に追跡する
7. 品質保持のために、やや低い圧縮率を受け入れる
8. 再フェッチ頻度を圧縮品質シグナルとして監視する

ハマりどころ

1. ツール定義やスキーマを決して圧縮しない：関数呼び出しスキーマ、API仕様、ツール定義を圧縮すると、エージェントの機能が完全に破壊されます。エージェントは使用可能なツールを呼び出すことができなくなります。

2. 不透明圧縮をデバッグや成果物追跡に使用しない：最初のセッションが短い場合でも、これらのアクティビティにはプローブによる情報検証が必要です。

3. サマリーサイズの保存場所を忘れない：圧縮されたサマリー自体がコンテキストスペースを消費します。あまりにも多くの要約ラウンドを保存すると、節約したスペースを浪費する可能性があります。

4. アクセス許可と暗号化を決して省略しない：サマリーは多くの場合、機密性の高い決定、ファイルパス、エラーステートメントのトレイルを保存します。情報が異なるセッションに漏洩するのを防ぐために、適切なアクセス制御を維持します。