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

コンテキストエンジニアリングの基礎 は何をしますか？

コンテキストとは、推論時に言語モデルが利用できる完全な状態（システム命令、ツール定義、取得済みドキュメント、メッセージ履歴、ツール出力）です。コンテキストエンジニアリングとは、望ましい結果が得られる可能性を最大化する、最も小さく、シグナルの高いトークンセットを厳選する手法です。

このスキルは、このコレクション内の他のすべてのスキルが基盤とする概念的な基礎です。コンテキストとは何か、アテンション機構の仕組み、コンテキストの質が量よりも重要な理由、そして他のすべてのコンテキストエンジニアリングの決定を解釈するためのメンタルモデルについて説明します。このスキル自体は運用作業を担当しません。アテンション障害のデバッグは context-degradation、トークン効率化戦術は context-optimization、会話の要約は context-compression、ファイルベースのオフロードは filesystem-context、プロジェクト構成の決定は project-development が担当します。

アクティベートすべき時

作業が概念的な場合にこのスキルをアクティベートします。

• コンテキストとは何か、アテンション機構がエージェントの振る舞いをどのように制約するかを説明する場合。
• 運用スキルに取り組む前にメンタルモデルが必要な新しいコントリビューターをオンボーディングする場合。
• 特定の戦術を選択する前に、コンテキスト関連の設計上の決定を第一原理から推論する場合（この制約は何を意味するのか、なぜこのトレードオフが存在するのか）。
• 運用ガイダンスを基礎となるメカニズムに基づいて説明する必要があるドキュメントを作成またはレビューする場合。

運用作業ではこのスキルをアクティベートしないでください。専門スキルが実行を担当します。

• lost-in-middle、コンテキストポイズニング、またはアテンション障害の診断: context-degradation。
• マスキング、分割、プレフィックスキャッシング、バジェットによるトークンコスト削減: context-optimization。
• 長いセッションを引き継ぎ用サマリーに圧縮: context-compression。
• 大規模なツール出力のオフロード、または永続的なスクラッチパッドの維持: filesystem-context。
• LLMプロジェクトまたはパイプラインの構成決定: project-development。

コアコンセプト

コンテキストをストレージとしてではなく、有限のアテンション予算として扱います。追加されたトークンはすべて、モデルのアテンションを巡って競合し、推論中に補充できない予算を消費します。エンジニアリング上の問題は、3つの制約（ハードなトークン制限、よりソフトな実効容量の上限、中間に配置された情報にペナルティを与えるU字型アテンション曲線）に対して、トークンあたりのユーティリティを最大化することです。

コンテキストを組み立てる際には、4つの原則を適用します。

1. 網羅性よりも情報価値 — 現在の決定に重要なものだけを含めます。必要に応じて追加情報を取得できるシステムを設計します。
2. 位置を意識した配置 — 重要な制約はコンテキストの最初と最後に配置します。長期コンテキスト評価では、中間位置の情報は端の位置の情報よりも確実に回復できないことが示されています。
3. 段階的な開示 — 起動時にはスキル名と概要のみを読み込みます。特定のタスクに対してスキルがアクティブになった場合のみ、完全なコンテンツを読み込みます。
4. 反復的なキュレーション — コンテキストエンジニアリングは、一度限りのプロンプト作成作業ではなく、コンテンツがモデルに渡されるたびに適用される継続的な手法です。

詳細トピック

コンテキストの構造

システムプロンプト システムプロンプトは、XMLタグまたはMarkdownヘッダーを使用して、明確なセクション（背景、指示、ツールガイダンス、出力形式）に整理します。システムプロンプトは会話全体を通じて持続するため、最も重要な制約はアテンションが最も強い最初と最後に配置します。

指示の抽象度は、2つの失敗モードのバランスを取るように調整します。抽象度が低すぎると、条件が変わったときに壊れる brittle なロジックがハードコードされます。抽象度が高すぎると、あいまいなガイダンスとなり、望ましい振る舞いに対する具体的なシグナルを提供できません。ヒューリスティック駆動の指示を目指します。振る舞いを導くのに十分具体的でありながら、一般化できる柔軟性を持つ指示です。例えば、各ステップで判断の余地を残した番号付き手順など。

最小限から始め、エッジケースを先制的に詰め込むのではなく、観察された失敗モードに基づいて事後的に指示を追加します。考えられるすべてのシナリオを列挙するのではなく、期待される振る舞いを示す、多様で標準的な few-shot の例を厳選します。

ツール定義 ツールの説明は、そのツールが何をするか、いつ使うか、何を返すかの3つの質問に答えるように記述します。使用コンテキスト、パラメータのデフォルト値、エラーケースを含めます。エージェントは、人間のエンジニアでも区別できないツールを区別することはできません。

ツールセットは最小限に保ちます。重複するツールは統合します。ツールセットが肥大化すると、あいまいな決定ポイントが生まれ、JSONシリアライゼーション後（ツールスキーマは通常、同等のプレーンテキスト説明と比較して2〜3倍に膨らみます）に不釣り合いな量のコンテキストを消費するためです。

取得ドキュメント 軽量な識別子（ファイルパス、保存済みクエリ、Webリンク）を維持し、ジャストインタイム検索を使用してデータを動的にコンテキストに読み込みます。これは人間の認知を模倣しています。インデックスを維持し、コピーは保持しません。強力な識別子（例: customer_pricing_rates.json）を使用すると、エージェントは検索ツールがなくても関連ファイルを見つけられます。弱い識別子（例: data/file1.json）は、不必要な読み込みを強制します。

大きなドキュメントをチャンクする場合は、概念の途中で区切る任意の文字数制限ではなく、自然な意味的境界（セクションヘッダー、段落区切り）で分割します。

メッセージ履歴 メッセージ履歴は、エージェントのスクラッチパッドメモリとして機能し、進捗状況の追跡、タスク状態の維持、ターン間の推論の保持を行います。長時間実行されるタスクでは、履歴が成長してコンテキスト使用量を支配する可能性があります。アクティブな命令を圧迫する前に、履歴を監視して圧縮を適用します。

履歴を循環的に精製します。会話の深い部分でツールが呼び出された後、生の結果をそのまま保持する必要はほとんどありません。古いツール出力をコンパクトなサマリーや参照に置き換え、シグナルの低い部分を削減します。

ツール出力 ツール出力は、エージェントの軌跡においてコンテキストを支配することがよくあります。観測マスキングを適用します。エージェントが結果を処理した後は、冗長な出力をコンパクトな参照に置き換えます。最後に関連したファイルの内容のみを保持し、古いものは圧縮するか削除します。

コンテキストウィンドウとアテンション機構

アテンション予算 n個のトークンに対して、アテンション機構はnの二乗のペアワイズ関係を計算します。コンテキストが大きくなるにつれて、モデルがこれらの関係を維持する能力は低下します。これは急激な限界ではなく、パフォーマンスの勾配として現れます。主に短いシーケンスで学習されたモデルは、コンテキスト全体にわたる依存関係のための特殊なパラメータが少なく、公称ウィンドウサイズをはるかに下回る実効的な上限が生じます。

この勾配を考慮して設計します。ターゲットのワークロードで測定するまで、実効容量は宣伝されているウィンドウよりも大幅に低いと想定します。公称コンテキストウィンドウが大きいことは、タスク固有の劣化テストの必要性をなくすものではありません。

位置エンコーディングの制限 位置エンコーディングの補間により、トレーニング長を超えたシーケンスの処理が可能になりますが、位置精度の低下が生じます。拡張されたコンテキストでは、短い入力でのパフォーマンスと比較して、情報検索や長距離推論の精度が低下することが予想されます。

段階的な開示の実践 段階的な開示を3つのレベルで実装します。

1. スキル選択 — 起動時には名前と説明のみを読み込み、スキルの完全なコンテンツはオンデマンドでアクティブにします。
2. ドキュメント読み込み — 最初にサマリーを読み込み、タスクで必要になった場合のみ詳細セクションを取得します。
3. ツール結果の保持 — 最近の結果は完全に保持し、古い結果は圧縮するか削除します。

境界を明確に保ちます。スキルまたはドキュメントがアクティブになった場合は、部分的ではなく完全に読み込みます。部分的な読み込みは混乱を招くギャップを生み出し、推論の質を低下させます。

コンテキストの質と量

コンテキストウィンドウが大きいほどメモリの問題が解決するという前提を拒否します。処理コストはコンテキスト長に比例して不釣り合いに増加します。これは単なる線形コストの増加だけでなく、実効容量のしきい値を超えた場合のモデルパフォーマンスの低下も含みます。プレフィックスキャッシングを使用しても、長い入力は高コストのままです。

シグナル密度テストを適用します。コンテキストの各要素について、それを削除した場合にモデルの出力が変化するかどうかを問います。変化しない場合は削除します。冗長なコンテンツはトークンを無駄にするだけでなく、ハイシグナルコンテンツへのアテンションを積極的に希釈します。

実践的なガイダンス

このセクションでは、概念的な応用アドバイスを提供します。運用スキルへのポインタは明示的に示します。

コンテキスト決定に関する推論

コンテキスト関連の設計上の決定を行う必要がある場合、概念的な問題と運用上の問題を分離します。概念的な問題は「これは何を意味し、なぜ重要なのか」です。運用上の問題は「どの特定のテクニックを適用するのか」です。最初の問いに答えるためにはこのスキルを使用し、2番目の問いを所有する専門スキルにルーティングします。

例えば、長いエージェントセッションを要約するかどうかの決定には、2つの部分があります。(1) なぜ要約が必要なのか（アテンション予算は有限、U字型曲線は中間コンテンツを劣化させる、シグナル密度はボリュームよりも重要 - このスキル）と、(2) どの圧縮戦略が適切な状態を維持し、どの利用しきい値でトリガーするのか（context-compression）。

新規コントリビューターのための読み順

コンテキストエンジニアリングに初めて取り組むコントリビューターは、以下を読む必要があります。

1. このスキル。アテンション予算のフレーミングとU字型曲線を内面化するため。
2. context-degradation。実際のコンテキスト障害がどのように見えるか、そしてそれを診断する方法を理解するため。
3. プロジェクトに最も関連する運用上の関心事に応じて、context-optimization、context-compression、filesystem-context、memory-systems のうち2つまたは3つ。

ステップ1をスキップすると、なぜそうするのかを理解せずにテクニックを適用するオペレーターが生まれます。運用スキルをスキップすると、どのテクニックがどの失敗モードに適合するかを知らない理論家が生まれます。

例

例1: システムプロンプトの整理

重要な制約はアテンションが強い位置（最初と最後）に属し、明示的なセクション境界がモデルのプロンプト解析を助けるという概念的なポイントを示します。

<BACKGROUND_INFORMATION>
あなたは開発チームを支援するPythonの専門家です。
現在のプロジェクト: Python 3.9+ でのデータ処理パイプライン
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- クリーンで慣用的なPythonコードを書いてください
- 関数シグネチャに型ヒントを含めてください
- 公開関数にはdocstringを追加してください
- PEP 8スタイルガイドラインに従ってください
</INSTRUCTIONS>

<OUTPUT_DESCRIPTION>
コードブロックはシンタックスハイライト付きで提供してください。
明白でない決定についてはコメントで説明してください。
</OUTPUT_DESCRIPTION>

例2: メンタルモデルとしてのアテンション予算

大規模コンテキストモデルは、均等にアテンションが行き渡るコンテキストを持ちません。実効容量はワークロード固有であり、U字型曲線は中間に配置された情報にペナルティを与えます。上流の知識ベースをどれだけ読み込むかを決定する際のメンタルモデルは次のとおりです。「収まるか」ではなく、「モデルが重要な部分にまだアテンションを向けるか」を問います。

対応する運用上の質問（どのテクニックが負荷を軽減するか）は、context-optimization が担当します。

ガイドライン

1. コンテキストを収穫逓減する有限リソースとして扱う
2. 重要な情報はアテンションが強い位置（最初と最後）に配置する
3. 段階的な開示を使用して、読み込みを必要になるまで延期する
4. システムプロンプトを明確なセクション境界で整理する
5. 開発中にコンテキスト使用量を監視する
6. 利用が70〜80%になったら圧縮トリガーを実装する
7. コンテキスト劣化を回避しようと期待するのではなく、それを前提に設計する
8. シグナルの高い小さなコンテキストを、シグナルの低い大きなコンテキストよりも優先する

落とし穴

1. 公称ウィンドウは実効容量ではない: 大きなコンテキストウィンドウを謳うモデルでも、複雑な検索や推論タスクでは、その限界に達するずっと前に劣化する可能性があります。独自の劣化テストがそうでないことを証明するまで、公称ウィンドウよりも低い予算で設計してください。

2. 文字ベースのトークン見積もりは静かにずれる: 英語散文の約4文字/トークンのヒューリスティックは、コード（2〜3文字/トークン）、URLとファイルパス（スラッシュ、ドット、コロンはそれぞれ別のトークン）、非英語テキスト（多くの場合1〜2文字/トークン）では成り立ちません。予算が重要な計算には、プロバイダーの実際のトークナイザー（OpenAIモデル用の tiktoken、AnthropicのトークンカウンティングAPIなど）を使用してください。

3. ツールスキーマはJSONシリアライゼーション後に2〜3倍に膨らむ: ソースコードではコンパクトに見えるツール定義も、シリアライズされると大幅に拡大します（括弧、引用符、コロン、カンマがそれぞれトークンを消費します）。適度なスキーマを持つ10個のツールで、1つのメッセージが送信される前に5,000〜8,000トークンを消費する可能性があります。シリアライズされたツールのトークン数を監査し、ソースコードの行数ではありません。

4. メッセージ履歴はエージェントループで静かに膨張する: ツール呼び出しのたびに、リクエストと完全なレスポンスの両方が履歴に追加されます。20〜30回の反復後、履歴はウィンドウの70〜80%を消費し、エージェントは推論の質が低下するまで目に見える症状を示さない可能性があります。履歴にハードなトークン上限を設定し、事前に圧縮をトリガーしてください。

5. 中間の重要な指示は失われる: U字型アテンション曲線は、コンテキストの中間が最初と最後よりも10〜40%低い想起精度になることを意味します。安全制約、出力形式要件、動作ガードレールを長いシステムプロンプトの中間に決して配置しないでください。上部または下部に固定してください。

6. あまりに熱心に読み込む段階的な開示はその目的を無効にする: 「潜在的に relevant」なすべてのスキルやドキュメントを関連性の最初の兆候で読み込むと、コンテキスト詰め込み問題が再現します。厳格なアクティベーションしきい値を設定してください。スキルは、タスクがトリガー条件に明示的に一致する場合にのみ読み込むべきであり、トピックが単に隣接している場合ではありません。

7. 異なる抽象度の指示を混在させると、一貫性のない動作を引き起こす: ハイパー固有のルール（「常に3つの箇条書きを使用してください」）と高レベルの原則（「読みやすさを優先してください」）を同じシステムプロンプト内で組み合わせると、モデルがいつどのルールに従うべきかが不明確になります。各スキル内では、指示の抽象度を統一してください。運用スキルでは低い抽象度、概念スキルでは高い抽象度を使用します。

まとめ

コンテキストエンジニアリングの基礎は、アテンション予算のメンタルモデル、U字型曲線、シグナル密度の原則を内面化することです。これらを理解すると、なぜ context-optimization がプレフィックスキャッシングにこだわるのか、なぜ context-compression が中間トークンに注意するのか、なぜ context-degradation がアテンションの失敗を診断する方法に焦点を当てるのかがわかります。