コンテキストエンジニアリング

出力契約が決まったら、今回モデルに渡す資料を選びます。制約と必要な根拠を保ち、出力容量を予約し、安定した前置部分を再利用し、履歴を原資料へ戻れる要約にします。永続化・検索・モデル重みとは役割が異なります。

知識と状態の3つの階層

モデルの言語能力や膨大な知識は、トレーニング後の重みに由来します。コンテキストは、現在の問題、制約、および利用可能な証拠を提供します。「リクエスト間でチャット内容を自動的に記憶しない」という事実を、「モデルの全知識が今回の入力に含まれている」と誤解してはいけません。もう一つの独立した階層は、アプリケーションが維持するセッション履歴、ファイル、データベースです。これらは長期にわたって存在し得ますが、存在しているからといって、現在の推論プロセスに組み込まれているわけではありません。

例えば、リポジトリに最新のテストレポートが存在しても、モデルの重みに直近生成されたレポートの内容が含まれることはありません。アプリケーションはレポートを読み取り、関連する結果をモデルに渡す必要があります。単にパスを渡すだけでは、モデルは通常、本文を取得するためにツールを呼び出す必要があります。ファイルはセッションをまたいで状態を復元するのに役立ちますが、単発のコンテキストを自動的に拡張するわけではありません。

「API はステートレスである」という場合も、インターフェースに限定して考える必要があります。履歴を明示的に渡すメッセージインターフェースは、通常、呼び出し側が会話の継続を構成します。ホストされたセッションでは、サーバー側で履歴が保存され補完される可能性があり、推論サービスではプレフィックス状態が再利用されることもあります。アプリケーションにとってより有用な質問は、「今回の推論で実際に何が受け取られたのか、誰が履歴を補完し、どこに回復可能な真の状態が保存されているのか？」 です。Claude のウィンドウドキュメントは、トレーニング知識と現在の作業コンテキストを区別しており、入力、出力、および thinking の具体的なカウント規則を説明しています。Claude 上下文窗口

ウィンドウ予算と出力の余裕

次ステップのためにスペースを確保する

まず、ターゲットモデルの入出力制限とカウント規則を確認し、資料を割り当てます。以下は、⁠仮に入力と出力の合計上限が 128,000 token である場合の計画例です。表中の K は 1,000 を表し、特定のモデルの固定設定を意味するものではありません。

入力部分は 65K です。もし次のツール呼び出しで 50K のログが返ってきた場合、計画された合計は 139K となり、11K 超過します。この場合、リクエストエラーが発生してから適当に古い履歴を削除するのではなく、まずログをフィルタリングするか、重要な区間のみを読み取るべきです。ストリーミング出力は配信方法を変更するだけで、ウィンドウ容量を増やすものではありません。

以下の独立した計算例で予算を確認できます。これは算数の検証のみを行い、実際のリクエストでは、メッセージテンプレート、ツール定義、マルチモーダルコンテンツを含むために、ターゲットモデルのカウントツールを使用する必要があります。

limit = 128_000
parts = {"rules_tools": 8_000, "history": 32_000,
         "evidence": 24_000, "question": 1_000}
reserve, margin = 16_000, 8_000
planned = sum(parts.values()) + reserve + margin
assert planned == 89_000
assert limit - planned == 39_000
incoming = 50_000
print("少なくとも", max(0, planned + incoming - limit), "token を削減する必要があります")
# 少なくとも 11000 token を削減する必要があります

異なるトークナイザー間で固定倍率による変換はできません。ベンダーのカウントエンドポイントを使用する場合でも、結果はリクエスト前の見積もりとして扱い、レスポンスの usage で補正する必要があります。Claude 公式では、両者の間にわずかな差異が生じる可能性があることを明確に指摘しています。Token counting

次の処理を入れる余裕はあるか

固定の49K は規則・履歴・質問・余裕です。出力と根拠は別々に調整します。超過は算数でも、何を削るかは根拠の判断です。棒を短くするために結論を左右する条件を消してはいけません。

証拠の必要性に応じた資料の選択

コンテキストの選択は、まず証拠のカバー範囲の問題です。「ある関数がどこで定義されているか」を問う場合、通常、シンボルとその周辺の少量のコードを特定するだけで十分です。一方、「移行案に互換性要件の見落としがないか」を問う場合、複数の完全な章を同時に読み取る必要があるかもしれません。検索で2つの断片にヒットしても、否定条件を見逃す方が、完全な読取よりも危険です。

「この設定は本番環境に適しているか」という例では、検索は enabled: true を含む例文にヒットするかもしれませんが、制限事項は前の段落に「単一ノードテストのみ」と記載されています。証拠ユニットには、キーワードを含む行だけでなく、設定とその適用条件を含めるべきです。各資料にはファイルやドキュメントの識別子、バージョン、位置を付与し、矛盾する証拠は並べて保持し、モデルに矛盾を認識させ、必要に応じて原文を再読します。

検索内容は分析対象のデータであり、コンテキストに含まれているからといって、実行コマンドの権限を得るわけではありません。「以前の指示を無視する」という文言がウェブページに含まれている場合、出典の身元を保持し、資料の内容として処理する必要があります。タスクの権限は、アプリケーションの信頼できる設定とユーザーの認可によって決定されます。関連する実行の境界については セキュリティと保護 を参照してください。

研究では、重要な証拠を長い入力の異なる位置に配置するとパフォーマンスに影響を与えることが観察されており、一部のタスクでは中央部で性能が低下しやすいことが示されています。これは位置感応性のテストを行うべきであることを支持しますが、すべてのモデルが「中央部を見えていない」ことを証明するものではなく、結論を末尾にコピーすれば正しいとも限りません。Lost in the Middle

キャッシュの再利用範囲

KV キャッシュは、推論において注意の履歴状態を再利用するメカニズムです。プロンプトキャッシュは、サービスが繰り返されるプロンプトのプレフィックスに対して提供する再利用機能であり、内部ではこのような状態を使用している可能性があります。これらは異なる抽象階層に位置しており、完全に無関係というわけではありません。API キャッシュがヒットしたからといって、モデルが「答えを覚えている」わけではありません。変化があったサフィックスは依然として生成する必要があります。

プレフィックスキャッシュでは、ツール定義と安定した指示は、動的なメッセージの前に配置するのが適しています。毎回先頭にランダムな ID を挿入すると、本来同じだった資料でも再利用できなくなる可能性があります。最後に問題のみを変更する場合、それまでの共通プレフィックスは依然として再利用の対象となります。ここで言う境界は、キャッシュの粒度、有効期限、モデルやサービスの設定にも影響を受けるため、可視される本文のみを比較することはできません。

Claude を例にとると、キャッシュは tools、system、messages の階層に関与し、ヒットは最小長さ、キャッシュブレイクポイント、有効期限によって制約されます。cache_read_input_tokens などの usage フィールドから検証できます。費用や制限はモデルやプラットフォームによって変化するため、接続時に該当ページを確認し、特定の価格倍率をキャッシュメカニズムそのものとして扱わないでください。Prompt caching

変更で接頭部の再利用はどこまでになるか

先頭の動的 ID と末尾の質問だけの変更を比べます。安定した順序の価値が分かりますが、実際の命中には版・長さ・有効期間・設定の条件も必要です。

履歴を回復可能な状態に圧縮する

要約の目的は、次のラウンドで作業を継続できるようにすることです。「いくつかの問題について議論し、修正した」とだけ書いても、どこを修正し、何を検証し、次のステップで何に依存しているかが不明瞭であるため、回復価値はほとんどありません。

タスクがインポーターの修正中であると仮定します。古い案は却下され、現在のパッチは適用済みですが、ユニットテストのみが実行されています。有用な要約は、事実、未完了事項、制約を明確に区別すべきです。

{
  "goal": "インポーターの重複送信問題を修正",
  "constraints": ["既存のファイル形式を維持", "公共インターフェースは変更しない"],
  "current_artifacts": ["src/importer.py", "tests/test_importer.py"],
  "decisions": ["入力バッチ ID を使用して重複排除；プロセス内コレクションは使用しない"],
  "verified": ["ユニットテスト通過；詳細結果は artifacts/unit-test.txt にあり"],
  "pending": ["プロセス再起動後の重複送信を検証"],
  "next_action": "現在のパッチとテストレポートを読み取り、復旧シナリオの検証を追加"
}

これはアプリケーションのカスタム状態フォーマットであり、ベンダーの compaction プロトコルではありません。復元時には、ファイルやレポートがまだ存在し、現在の修正に対応しているかどうかを最初に確認します。要約内の「テスト通過」はテスト成果物を代替するものではなく、後続の修正もテストに合格したことを自動的に意味するものではありません。

サーバー側の compaction を使用する場合は、そのインターフェースに従って構造化状態を保持・返送する必要があり、任意の要約 JSON をプロトコルブロックに詰め込んではいけません。具体的な互換範囲とフローについては Claude Compaction を参照してください。セッションをまたぐ設計については メモリと状態 を参照してください。

コンテキスト変更の有効性をどう検証するか

一連のタスクと正解の根拠を固定し、元の履歴、圧縮された履歴、検索材料という3つの入力を比較します。タスクの正答率、必要な証拠の再現率、入力量、最初の可視出力までのレイテンシ、および総コストを記録します。その後、「圧縮後の復元」を再度行い、すでに失敗した案を繰り返していないか、ユーザーの制約を見落としていないか、完了していないステップが完了したと主張していないかを確認します。

入力量が減少したにもかかわらず復元エラーが増加した場合、重要な状態が削除されたことを意味します。入力量が増加したが正答率が変わらない場合、ツール出力が重複して保持されていないか確認します。事実回答は正しいが、支持する位置を示せない場合、証拠インデックスを確認します。これにより、コンテキストの選択がタスクを改善したのか、単にプロンプトが整って見えるようになったのかを判断できます。後続の評価方法については 評価と観測可能性 を参照してください。

次に読む：検索・RAG・根拠。