context-optimization

コンテキスト最適化の手法

コンテキスト最適化では、圧縮、マスキング、キャッシュ、分割を測定に基づいて適用することで、限られたコンテキストウィンドウの実効容量を拡張します。以下の手法は、効果とリスクの順に並んでいます。

有効化するタイミング

• コンテキストの予算やトークンコストがタスクの複雑さを制限している
• 観測のマスキングにより、冗長なツール出力を参照可能な情報に置き換えられる
• プレフィックスまたは KV キャッシュのヒット率を改善する必要がある
• 検索範囲を絞ることで、無関係なコンテキストの読み込みを減らせる
• コンテキストの分割により、エージェント間で実効容量を拡張できる
• マスキング、圧縮、分割を実行するための予算トリガーが必要である
• コンテキストが増えるにつれてエージェントの品質が低下する、または明らかな理由もなく出力が誤っていたり無関係になったりする（診断モード）

モード

モード	使用する状況	参照先
最適化（デフォルト）	トークンコストや予算の制限がタスクに影響しており、コンテキストに問題がない場合	このファイルを読んでから、references/optimization_techniques.md
診断	品質がすでに低下している場合：中間部の情報の見落とし、汚染、注意散漫、混乱、または矛盾	references/degradation.md、続いて検出コードと復旧方法について references/degradation-patterns.md
解説	現在問題が発生しておらず、コンテキストの仕組みについて学ぶ場合	references/fundamentals.md

問題が発生しているエージェントを最適化する前に、まず診断してください。汚染や矛盾があるコンテキストに圧縮やマスキングを適用すると、誤りがそのまま引き継がれます。まず、コンテキスト長が短い場合にプロンプトが機能することを確認してください（2K トークンで失敗するなら、問題はプロンプトにあります）。次に、症状をパターンと照合して、最初の対処を行います。

パターン	典型的な症状	最初の対処	最適化手法
中間部の情報の見落とし	コンテキスト内の正しい事実が無視される。初期の指示が忘れられる	重要な内容を冒頭または末尾に移動する。要約を先頭に追加する	重要な知見を両端に残す圧縮
汚染	訂正後も誤った主張が残る。ツールが誤用される	誤った主張の前まで切り詰め、検証済みの情報源だけを再読み込みする	クリーンな分割で再開する
注意散漫	文書を追加で読み込んだ後に品質が低下する	読み込む前に検索結果を絞り込む。参照資料をツール呼び出しの背後に置く	検索範囲の絞り込み、観測のマスキング
混乱	別のタスクの制約やツールが混入する	タスクを別々のコンテキストに分割する	コンテキストの分割
矛盾	矛盾する情報源により回答が予測不能になる	情報源の優先順位を定め、読み込む前に古いバージョンを除外する	検索範囲の絞り込み

症状が現れてからではなく、モデルごとに劣化が始まる既知の時点より十分前（その時点のおよそ70％）に圧縮を実行してください。

コアコンセプト

次の4つの主要な戦略を、優先順位の高い順に適用します。

1. KV キャッシュの最適化 — 推論エンジンがキャッシュされた Key/Value テンソルを再利用できるよう、プロンプトの構造を並べ替えて安定させます。ランタイムがプレフィックスキャッシュに対応している場合、これは最も低コストな最適化です。品質へのリスクが低く、コストとレイテンシをすぐに削減できます。安定したプレフィックスがある場合は、最初に適用してください。

2. オブザベーションのマスキング — 役目を終えた冗長なツール出力を、簡潔な参照に置き換えます。ツール出力がエージェントの軌跡を大きく占めることがあるため（claim-context-optimization-tool-output-dominance）、マスキングは容量を最も大きく増やせることがよくあります。元の内容は、後続の処理で必要になれば取得できます。

3. コンテキストの圧縮 — モデルで測定した性能劣化の開始点の約70%（ウィンドウ全体の70%ではありません）で、蓄積されたコンテキストを要約し、その要約で再初期化します。これにより、タスクに不可欠な状態を保ちながら、ウィンドウの内容を凝縮できます。圧縮には情報の損失が伴うため、価値の低い大部分をマスキングで取り除いてから適用してください。

4. コンテキストの分割 — 1つのウィンドウに問題全体を収められない場合は、コンテキストを分離したサブエージェントに作業を分担させます。各サブエージェントは、担当するサブタスクに集中できるクリーンなコンテキストで動作します。連携には実際にオーバーヘッドが生じるため、推定コンテキストがウィンドウ上限の60%を超えるタスクに限って使用してください。

基本原則は、コンテキストの量より品質が重要だということです。すべての最適化で、ノイズを減らしながらシグナルを維持します。最適化の前に測定し、最適化の効果も測定してください。

詳細なトピック

圧縮戦略

測定した性能劣化の開始点の約70%で圧縮を開始します（開始点がウィンドウの60%の場合、使用率約42%です）。現在のコンテキストを要約してから、その要約で再初期化します。これによりウィンドウの内容を高い忠実度で凝縮し、パフォーマンスの低下を最小限に抑えて作業を続行できます。まずツール出力（トークンの80%以上を消費します）、次に古い会話ターン、最後に取得したドキュメントの順に圧縮してください。システムプロンプトは決して圧縮しないでください。システムプロンプトはモデルの動作の基盤であり、取り除くと予測不能な性能劣化が生じます。

メッセージの種類に応じて、異なる要素を保持します。

• ツール出力：重要な知見、指標、エラーコード、結論を抽出します。冗長な生の出力、スタックトレース（デバッグ中の場合を除く）、定型的なヘッダーを削除します。
• 会話ターン：決定事項、約束、ユーザーの好み、コンテキストの変化を保持します。すでに記録された結論に至るまでの、不要な言葉、儀礼的な表現、探索的なやり取りを削除します。
• 取得したドキュメント：現在のタスクに関連する主張、事実、データポイントを保持します。一度きりの推論に使われた裏付けや詳細な説明を削除します。

品質の劣化を5%未満に抑えながら、トークンを50〜70%削減することを目指します。圧縮率が70%を超える場合は、重要な情報が失われていないか要約を確認してください。過剰な圧縮は、最もよくある失敗要因です。

オブザベーションのマスキング

新しさと現在の関連性に基づいて、オブザベーションを選択的にマスキングします。一律には適用しないでください。次のルールに従います。

• 決してマスキングしないもの：現在のタスクに不可欠なオブザベーション、直近のターンのオブザベーション、進行中の推論チェーンで使われているオブザベーション、デバッグ中のエラー出力。
• 3ターン以上経過したらマスキングするもの：要点がすでに会話の流れに抽出されている冗長な出力。次の簡潔な参照に置き換えます：[Obs:{ref_id} elided. Key: {summary}. Full content retrievable.]
• 常に直ちにマスキングするもの：繰り返しや重複のある出力、定型的なヘッダーとフッター、会話の前の部分ですでに要約された出力。

品質への影響を2%未満に抑えながら、マスキングしたオブザベーションを60〜80%削減することを目指します。重要なのは、取得可能な状態を保つことです。元の内容を外部に保存し、エージェントが必要に応じて元の内容を要求できるよう、参照 ID をコンテキストに残してください。

KV キャッシュの最適化

安定した内容がプレフィックスを占め、動的な内容が末尾に来るようプロンプトを構成し、プレフィックスキャッシュのヒット率を最大化します。KV キャッシュは推論中に計算された Key と Value のテンソルを保存します。連続するリクエストで同一のプレフィックスが共有される場合、キャッシュされたテンソルが再利用され、コストとレイテンシの両方を削減できます。

すべてのプロンプトで、次の順序を適用します。

1. システムプロンプト（最も安定 — セッション中は変更しません）
2. ツール定義（リクエスト間で安定）
3. 頻繁に再利用されるテンプレートと少数例
4. 会話履歴（増えていきますが、前のターンとのプレフィックスは共有されます）
5. 現在のクエリと動的な内容（最も不安定 — 常に末尾に配置します）

キャッシュの安定性を考慮してプロンプトを設計します。システムプロンプトからタイムスタンプ、セッションカウンター、リクエスト ID を削除します。プレフィックスを壊さないよう、動的なメタデータは別のユーザーメッセージまたはツールの結果に移します。プレフィックスの空白が 1 つ変わるだけでも、その変更箇所以降のキャッシュブロック全体が無効になります。それ以前の履歴を圧縮またはマスキングした場合も、後続のテキストを再処理する必要があります。これらの編集はまとめて行い、ランタイムが許す場合は末尾に近い箇所の編集を優先します。トークン削減の効果が無条件に得られると考えず、キャッシュとレイテンシへの影響を測定します。

安定したワークロードでは、キャッシュヒット率 70％以上を目指します。大規模運用では、キャッシュされたトークンのコストを 50％以上、レイテンシを 40％以上削減できます。

コンテキストの分割

積極的な圧縮を発生させずに 1 つのコンテキストに問題全体を収められない場合は、サブエージェント間で作業を分割します。各サブエージェントは、担当するサブタスクに集中できるクリーンなコンテキストで作業し、構造化された結果をコーディネーターエージェントに返します。

推定されるタスクのコンテキストがウィンドウ上限の 60％を超える場合は、分割を計画します。タスクを独立したサブタスクに分解して、それぞれをサブエージェントに割り当て、結果を統合します。統合前にすべての分割タスクが完了していることを確認し、互換性のある結果を統合します。統合後の出力が予算を超える場合は、要約を適用します。

この方法では、関心事を分離できます。詳細な検索コンテキストはサブエージェント内に保たれ、コーディネーターは統合に集中できます。ただし、調整には実際にトークンコストがかかります。コーディネーターのプロンプト、結果の集約、エラー処理はいずれもトークンを消費します。分割による削減量がこのオーバーヘッドを上回る場合にのみ、分割を行います。

予算管理

セッション開始前に、システムプロンプト、ツール定義、取得したドキュメント、メッセージ履歴、ツール出力、予備バッファー（合計の 5〜10％）などのコンテキストカテゴリごとに、明示的なトークン予算を割り当てます。予算に対する使用状況を継続的に監視し、いずれかのカテゴリが割り当てを超えた場合、または全体の使用率が 70％を超えた場合に最適化を開始します。

定期的な最適化ではなく、トリガーベースの最適化を使用します。次のシグナルを監視します。

• トークン使用率が 80％を超える — 圧縮を開始
• 注意力低下の兆候（反復、指示の見落とし） — マスキングと圧縮を開始
• 品質スコアがベースラインを下回る — 最適化の前にコンテキストの構成を監査

実践的なガイダンス

最適化手法の選択フレームワーク

コンテキストの大部分を占める要素に基づいて、最適化手法を選択します。

コンテキストの構成	最初の対応	2 番目の対応
ツール出力が大半を占める（50％超）	観測結果のマスキング	残りのターンを圧縮
取得したドキュメントが大半を占める	要約	ドキュメントが独立している場合は分割
メッセージ履歴が大半を占める	選択的に保持しながら圧縮	新しいサブタスクを分割
複数の要素が占める割合が大きい	まず KV キャッシュを最適化し、次にレイヤーマスキングと圧縮を実施	—
上限間近でデバッグ中	解決済みのツール出力のみをマスキング — エラーの詳細は保持	—

パフォーマンス目標

最適化の効果を検証するため、以下の指標を追跡します。

• 圧縮：トークンを50～70％削減し、品質の低下を5％未満に抑え、圧縮処理自体によるレイテンシの増加を10％未満にします
• マスキング：マスク対象の観測データを60～80％削減し、品質への影響を2％未満に抑え、レイテンシの増加をほぼゼロにします
• キャッシュの最適化：安定したワークロードで70％以上のヒット率を達成し、コストを50％以上削減し、レイテンシを40％以上短縮します
• 分割：コーディネーターのオーバーヘッドを考慮したうえで、トークンを純削減します。損益分岐点に達するには、通常3つ以上のサブタスクが必要です

測定結果に基づいて戦略を反復します。最適化手法によって目標指標が測定可能なほど改善しない場合は、その手法を取り除いてください。最適化の仕組み自体がトークンを消費し、レイテンシを増加させるためです。

例

例1：圧縮のトリガー

if context_tokens / context_limit > 0.8:
    context = compact_context(context)

例2：観測データのマスキング

if len(observation) > max_length:
    ref_id = store_observation(observation)
    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"

例3：キャッシュに適した順序

# Stable content first
context = [system_prompt, tool_definitions]  # Cacheable
context += [reused_templates]  # Reusable
context += [unique_content]  # Unique

例4：予算をトリガーとする最適化ポリシー

budgets:
  tool_outputs: 35%
  message_history: 30%
  retrieved_documents: 20%
  reserved_buffer: 15%
triggers:
  tool_outputs_over_budget: mask resolved observations
  total_context_over_70_percent: compact message history
  repeated_irrelevant_retrievals: tighten retrieval scope

ガイドライン

1. 最適化の前に測定し、現状を把握します
2. 圧縮の前にマスキングを適用します。まず価値の低い大容量データを取り除き、残った内容を要約します
3. 一貫性のあるプロンプトを使用して、キャッシュが安定するように設計します
4. コンテキストが問題になる前に分割します
5. 最適化の効果を継続的に監視します
6. トークンの削減と品質の維持のバランスを取ります
7. 本番環境の規模で最適化をテストします
8. エッジケースに備えて、適切に機能を縮退できるようにします

注意点

1. 空白文字はKVキャッシュを無効にします：プロンプトのプレフィックスに空白文字や改行が1つでも変更されると、その位置より後のKVキャッシュブロック全体が無効になります。システムプロンプトは変更不可の文字列として固定し、タイムスタンプ、バージョン番号、セッションIDを埋め込まないでください。デプロイ間でプロンプトテンプレートをバイト単位で比較してください。

2. システムプロンプトのタイムスタンプはキャッシュヒット率を低下させます：Current date: {today}などの動的な内容をシステムプロンプトに含めると、新しい日になるたびに（時刻も含める場合はリクエストごとに）キャッシュミスが発生します。動的なメタデータは、ユーザーメッセージ内、または安定したプレフィックスの後に追加する別のツール結果内に移してください。

3. 負荷が高い状態での圧縮は重要な状態を失わせます：圧縮を行うモデル自体がコンテキストの負荷にさらされている場合（使用率が85％を超える場合）、要約の品質が低下し、タスクの目標やユーザーの制約を省略したり、細やかな状態を平板化したりします。圧縮は90％以上ではなく、70～80％の時点でトリガーしてください。圧縮が遅れてしまう場合は、要約対象の内容だけを含むクリーンなコンテキストで、別のモデル呼び出しを使用してください。

4. エラー出力のマスキングはデバッグの反復を妨げます：過剰なマスキングによって、エージェントが後続のターンで問題を診断・修正するために必要なエラーメッセージ、スタックトレース、失敗の詳細が隠されることがあります。デバッグ中（直近3ターン以内にエラーがある場合）は、問題が解決するまでエラー関連の観測データすべてに対するマスキングを一時停止してください。

5. 分割のオーバーヘッドが削減量を上回ることがあります：各サブエージェントには、それぞれのシステムプロンプト、ツール定義、調整メッセージが必要です。独立したサブタスクが3つ未満の場合、調整のオーバーヘッドがコンテキストの削減量を上回ることがよくあります。分割を決定する前に、コーディネーターとすべてのサブエージェントを合わせた総トークン数を見積もってください。

6. デプロイ後にキャッシュミスのコストが急増することがあります：デプロイ間でツールの順序を変更したり、システムプロンプトを書き換えたり、少数ショット例を変更したりすると、プレフィックスキャッシュ全体が無効になり、新しいキャッシュが温まるまで一時的にコストが2～5倍になります。プロンプトの変更は段階的に展開し、デプロイ期間中のキャッシュヒット率を監視してください。

7. 圧縮によって古い要約を過信することがあります：コンテキストを圧縮すると、要約は確かな情報に見えますが、古い状態を反映している可能性があります。圧縮後にタスクが変化した場合（新たなユーザー要件や前提の訂正など）、要約には古い情報が気付かれないまま引き継がれます。圧縮後は、作業を進める前に、現在のタスク目標に照らして要約を再検証してください。

統合

このスキルは、トークン効率化の手法、予算ポリシー、劣化の診断を担います。隣接するスキルは、ストレージとアーキテクチャを担います。

• multi-agent-patterns：分離されたエージェントコンテキスト間で作業を分割します。
• evaluation：最適化によって品質、コスト、レイテンシーが改善したかを測定します。
• memory-systems：必要なタイミングでコンテキストに情報を渡す永続的な検索レイヤーです。

参考資料

内部資料：

• コンテキストの基礎 - 次の場合に参照してください：コンテキストとは何か、ウィンドウの構成、注意の仕組みとU字カーブを説明するとき、またはコンテキストエンジニアリングの入門を行うとき。コンポーネントごとのリファレンスと scripts/context_manager.py の使用方法も記載しています。

• 最適化手法リファレンス - 次の場合に参照してください：特定の最適化手法を実装する際に、このスキルの本文にない詳細なコードパターン、しきい値テーブル、統合例が必要なとき。

• コンテキストの劣化 - 次の場合に参照してください：エージェントのパフォーマンスが低下した原因を診断し、最適化を選択する前に、どの劣化パターンが発生しているかを特定する必要があるとき。degradation-patterns.md には検出コードと復旧手順が記載されており、scripts/degradation_detector.py でチェックを実行できます。

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

• evaluation - 次の場合に参照してください：最適化手法によって実際に成果が向上したかを測定するためのメトリクスとベンチマークを設定するとき。

外部リソース：

• コンテキストウィンドウの制限に関する研究 - 次の場合に参照してください：モデル固有のコンテキスト挙動（例：Lost-in-the-Middle効果、注意の減衰曲線）を評価するとき。
• KVキャッシュの最適化手法 - 次の場合に参照してください：推論インフラレベル（vLLM、TGI、またはクラウドプロバイダーのAPI）でプレフィックスキャッシュを実装するとき。
• 本番環境向けエンジニアリングガイド - 次の場合に参照してください：本番パイプラインにコンテキスト最適化をデプロイし、運用パターン（監視、アラート、ロールバック）が必要なとき。