context-optimization

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

コンテキスト最適化では、戦略的な圧縮、マスキング、キャッシュ、分割によって、限られたコンテキストウィンドウの実効容量を拡張します。効果的な最適化を行えば、より大きなモデルや長いウィンドウを必要とせずに有用な容量を増やせます。ただし、それには測定を徹底する必要があります。以下の手法は、効果とリスクの順に並んでいます。

使用するタイミング

次の場合に、このスキルを使用してください：

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

他のスキルが担当する関連作業では、このスキルを使用しないでください：

• アテンションやコンテキストウィンドウがこのように動作する理由の説明：context-fundamentals。
• 進行中の中間部での情報喪失、ポイズニング、注意散漫、混乱、衝突の診断：context-degradation。
• 長い会話のための構造化された引き継ぎ要約の設計：context-compression。
• 大量の出力、計画、ログのファイルへの保存：filesystem-context。
• モデルが自らのコンテキストを書き換える処理と、それに伴う再プリフィルコスト：self-managed-context。

主な概念

次の優先順位で、4 つの主要な戦略を適用します：

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

2. 観測マスキング — 用途を終えた冗長なツール出力を、簡潔な参照情報に置き換えます。ツール出力はエージェントの処理経路の大部分を占めることがあるため（claim-context-optimization-tool-output-dominance）、マスキングによって最大の容量増加が得られることがよくあります。必要になれば、元の内容を後続の処理で取得できます。

3. 圧縮 — 使用率が 70% を超えたら、蓄積したコンテキストを要約し、その要約を使って初期化し直します。これにより、タスクに不可欠な状態を保ちながら、ウィンドウの内容を要約できます。圧縮は情報を失うため、価値の低い大量の情報をマスキングで取り除いてから適用してください。

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

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

詳細なトピック

コンパクション戦略

コンテキスト使用率が70％を超えたら、コンパクションを実行します。現在のコンテキストを要約してから、その要約を使って初期化し直します。これにより、ウィンドウ内の内容を高い忠実度で凝縮し、パフォーマンスの低下を最小限に抑えながら処理を続けられます。まずツールの出力（トークンの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％以上削減できます。

コンテキストの分割

単一のコンテキストでは積極的な圧縮が発生してしまうほど問題全体を保持できない場合は、サブエージェントに作業を分割します。各サブエージェントは、対象のサブタスクに集中できるクリーンなコンテキストで作業し、その後、構造化された結果をコーディネーターエージェントに返します。

推定されるタスクのコンテキストがウィンドウ上限の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 キャッシュを無効にします：プロンプトのプレフィックス内で空白文字や改行がひとつ変わるだけでも、その箇所以降の KV キャッシュブロック全体が無効になります。システムプロンプトは変更不可の文字列として固定し、タイムスタンプ、バージョン番号、セッション ID を埋め込まないでください。デプロイ間でプロンプトテンプレートをバイト単位で比較してください。

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

3. 負荷が高い状態での圧縮は重要な状態を失わせます：圧縮を実行するモデル自体のコンテキストに余裕がない場合（使用率が 85% 超）、要約の品質が低下し、タスクの目標が抜け落ちたり、ユーザーの制約が省かれたり、細かな状態が単純化されたりします。圧縮は 90% 以上ではなく、70～80% の時点で実行してください。遅い段階で圧縮せざるを得ない場合は、要約対象の資料だけを含むクリーンなコンテキストで、別のモデル呼び出しを使用してください。

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

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

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

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

統合

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

• context-fundamentals：コンテキストの品質と注意の配置が重要である理由を理解するためのメンタルモデル。
• context-degradation：出力品質がすでに低下している場合の診断。
• context-compression：情報を失う要約と引き継ぎの戦略。
• filesystem-context：出力全体やログをファイルに退避する方法。
• multi-agent-patterns：分離されたエージェントのコンテキスト間で作業を分割する方法。
• latent-briefing：互換性のあるランタイムで、オーケストレーターとワーカーの境界を越えて KV の保持を選択的に行う方法。
• self-managed-context：ハーネスではなくモデルが、実行中のコンテキストをいつ、何を編集するかを決定する方法。
• evaluation：最適化によって品質、コスト、レイテンシーが改善したかどうかの測定。
• memory-systems：コンテキストに必要な情報を適切なタイミングで提供する、永続的な検索レイヤー。

参考資料

内部リファレンス：

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

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

• context-fundamentals - 次の場合に参照してください：コンテキストウィンドウの仕組み、トークンのカウント、または注意の配分の基本に詳しくない場合
• context-degradation - 次の場合に参照してください：エージェントのパフォーマンスが低下した原因を診断し、最適化を選択する前に、どの劣化パターンが発生しているかを特定する必要がある場合
• evaluation - 次の場合に参照してください：最適化手法によって実際に成果が向上したかを測定するためのメトリクスとベンチマークを設定する場合

外部リソース：

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

---

スキルのメタデータ

作成日：2025-12-20 最終更新日：2026-05-15 作成者：Context Engineering Contributors 向け Agent Skills バージョン：2.1.0