context-fundamentals

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

コンテキストとは、推論時に言語モデルが利用できる状態のすべてです。システム指示、ツール定義、取得したドキュメント、メッセージ履歴、ツールの出力が含まれます。コンテキストエンジニアリングとは、望ましい結果が得られる可能性を最大化する、信号対雑音比の高い最小限のトークンセットを選定する分野です。

このスキルは運用上の作業を担いません。注意機構の失敗のデバッグは context-degradation に、トークン効率化の手法は context-optimization に任せてください。

有効化するタイミング

概念的な作業を行う場合に有効化します。

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

運用上の作業では、このスキルを有効化しないでください。実作業は専門スキルが担当します。

• lost-in-middle、コンテキスト汚染、注意機構の失敗を診断する場合：context-degradation。
• マスキング、分割、プレフィックスキャッシュ、予算を利用してトークンコストを削減する場合：context-optimization。

中核となる概念

コンテキストは保存場所ではなく、有限の注意予算として扱います。追加されるすべてのトークンがモデルの注意を奪い合い、推論の途中で補充できない予算を消費します。エンジニアリング上の課題は、次の3つの制約のもとで、トークンあたりの有用性を最大化することです。厳密なトークン上限、より緩やかな実効容量の上限、そしてコンテキストの中央に配置された情報に不利な影響を与えるU字型の注意曲線です（claim-context-degradation-lost-middle-ruler）。

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

1. 網羅性より情報性を重視する — 現在の判断に必要な情報だけを含め、追加情報は必要に応じて取得できるシステムを設計します。
2. 位置を考慮して配置する — 長文コンテキストの評価では、中央にある情報は端にある情報よりも確実に取り出されにくいことが示されているため、重要な制約はコンテキストの先頭と末尾に配置します（claim-context-degradation-lost-middle-ruler）。
3. 段階的に開示する — 起動時にはスキル名と概要を読み込み、特定のタスクでスキルが有効化された場合にのみ全文を読み込みます。
4. 反復的に選定する — コンテキストエンジニアリングは一度限りのプロンプト作成作業ではなく、コンテンツをモデルに渡すたびに適用する継続的な取り組みです。

詳細なトピック

コンテキストの構成要素

システムプロンプト システムプロンプトは、XML タグや Markdown の見出しを使って（背景、指示、ツールのガイダンス、出力形式などの）個別のセクションに整理します。システムプロンプトは会話全体を通じて有効なため、最も重要な制約は注意が向きやすい冒頭と末尾に配置します。

指示の抽象度を調整して、2 つの失敗パターンのバランスを取ります。抽象度が低すぎると、条件が変わったときに機能しなくなる硬直したロジックをハードコードしてしまいます。抽象度が高すぎると、望ましい動作を具体的に示せない曖昧なガイダンスになります。ヒューリスティックに基づく指示を目指します。つまり、動作を導くのに十分な具体性を持たせつつ、汎用性も確保します。たとえば、各ステップで判断の余地を残した番号付きの手順が有効です。

まずは最小限の指示から始め、エッジケースをあらかじめ詰め込むのではなく、観察された失敗パターンに応じて指示を追加します。あらゆるシナリオを列挙するのではなく、期待する動作を示す多様で代表的な数ショット例を厳選します。

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

ツールセットは最小限に保ちます。重複するツールは統合します。肥大化したツールセットは判断を曖昧にし、JSON シリアライズ後にコンテキストを不釣り合いに消費するためです（ツールスキーマは、通常、同等のプレーンテキストの説明と比べて2～3倍に膨らみます）。

取得したドキュメント ファイルパス、保存済みクエリ、ウェブリンクなどの軽量な識別子を保持し、ジャストインタイム取得を使ってデータを動的にコンテキストへ読み込みます。これは人間の認知を模倣した方法です。コピーではなく、インデックスを保持します。customer_pricing_rates.json のような明確な識別子があれば、検索ツールがなくてもエージェントは関連ファイルを見つけられます。一方、data/file1.json のような不明瞭な識別子では、不要な読み込みが発生します。

大きなドキュメントをチャンクに分割する際は、概念の途中で切断される任意の文字数制限ではなく、セクション見出しや段落の区切りなど、意味上自然な境界で分割します。

メッセージ履歴 メッセージ履歴は、進捗の追跡、タスク状態の維持、ターンをまたいだ推論の保持に使うエージェントのスクラッチパッドメモリーです。長時間にわたるタスクでは、履歴が増えてコンテキストの使用量を占めることがあります。有効な指示を圧迫する前に、使用量を監視して圧縮します。

履歴は周期的に整理します。会話のかなり前にツールを呼び出した場合、その生の結果を逐語的に残す必要はほとんどありません。古くなったツール出力は、簡潔な要約や参照に置き換えて、情報密度の低いデータを減らします。

ツール出力 エージェントの実行過程では、ツール出力がコンテキストの大部分を占めることがよくあります（claim-context-optimization-tool-output-dominance）。観察内容のマスキングを適用し、エージェントが結果を処理した後は、冗長な出力を簡潔な参照に置き換えます。保持するのは直近で関連性のあるファイル内容だけにし、それより古い内容は圧縮するか削除します。

コンテキストウィンドウと注意の仕組み

注意の予算 n 個のトークンに対して、注意機構は n² 個のペア間の関係を計算します。コンテキストが大きくなるにつれて、モデルがこうした関係を維持する能力は低下します。これは明確な境界で急激に起きるのではなく、性能が段階的に低下します。主に短いシーケンスでトレーニングされたモデルは、コンテキスト全体にまたがる依存関係を扱う専用パラメーターが少ないため、公称ウィンドウサイズを大きく下回る実効上限が生じます。

この段階的な低下を前提に設計してください。対象のワークロードで測定するまでは、実効容量は公称のウィンドウサイズを大幅に下回ると想定します。公称のコンテキストウィンドウが大きくても、タスク固有の劣化テストは引き続き必要です（claim-context-degradation-lost-middle-ruler）。

位置エンコーディングの限界 位置エンコーディングの補間により、トレーニング時の長さを超えるシーケンスを処理できるようになりますが、位置精度は低下します。長いコンテキストでは、短い入力での性能と比べて、情報検索や長距離推論の精度が低下することを想定してください。

実践における段階的な情報開示 段階的な情報開示を、次の3つのレベルで実装します。

1. スキルの選択 — 起動時には名前と説明だけを読み込み、必要に応じてスキルの全内容を有効化します。
2. ドキュメントの読み込み — まず要約を読み込み、タスクで必要になった場合にのみ詳細セクションを取得します。
3. ツール結果の保持 — 最近の結果は完全な状態で保持し、それより古い結果は圧縮するか破棄します。

境界を明確に保ってください。スキルやドキュメントを有効化したら、部分的ではなく全体を読み込みます。部分的な読み込みは分かりにくい欠落を生み、推論の質を低下させます。

コンテキストの質と量

コンテキストウィンドウを大きくすればメモリの問題が解決するという前提は退けてください。コンテキストの長さが増すと処理コストは不釣り合いに増大します。コストが線形に増えるだけでなく、実効容量のしきい値を超えるとモデルの性能も低下します。プレフィックスキャッシュを使っても、長い入力には引き続きコストがかかります。

情報密度のテストを適用します。コンテキストの各要素について、それを削除するとモデルの出力が変わるかを確認してください。変わらない場合は削除します。冗長な内容はトークンを無駄にするだけでなく、重要度の高い内容への注意を積極的に薄めます。

実践的な指針

このセクションでは、概念を実際に適用するためのアドバイスを示します。運用スキルへの参照先も明記しています。

コンテキストに関する判断を考える

コンテキストに関する設計上の判断が必要なときは、概念上の問いと運用上の問いを分けて考えます。概念上の問いは「これは何を意味し、なぜ重要なのか」であり、運用上の問いは「具体的にどの手法を適用するのか」です。前者への回答にはこのスキルを使い、後者については、その手法を担当する専門スキルを参照します。

たとえば、長いエージェントのセッションを要約するかどうかを決める際には、2つの観点があります。（1）そもそもなぜ要約が必要なのか（注意の予算は有限であり、U字型の曲線では中間部分の内容が劣化し、情報密度が量より重要です。このスキルで扱います）。（2）適切な状態を保持するにはどの圧縮戦略を使い、どの利用率しきい値で実行するのか（セッションの圧縮を担当する運用スキルを参照します）。

新しいコントリビューター向けの読む順序

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

1. このスキル。注意の予算という考え方とU字型の曲線を理解するためです。
2. context-degradation。コンテキストの失敗が実際にどのようなものか、またその診断方法を理解するためです。
3. プロジェクトで最も重要な運用上の課題に応じて、context-optimization と memory-systems のうち2つまたは3つ。

手順1を省くと、なぜその手法が有効なのかを理解しないまま適用する担当者が生まれます。運用スキルを省くと、どの失敗モードにどの手法が適しているかを知らない理論家が生まれます。

例

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

重要な制約は、注意が向きやすい位置（冒頭と末尾）に置くべきであり、明確なセクション境界があるとモデルがプロンプトを解析しやすくなる、という概念を示します。

<BACKGROUND_INFORMATION>
You are a Python expert helping a development team.
Current project: Data processing pipeline in Python 3.9+
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- Write clean, idiomatic Python code
- Include type hints for function signatures
- Add docstrings for public functions
- Follow PEP 8 style guidelines
</INSTRUCTIONS>

<OUTPUT_DESCRIPTION>
Provide code blocks with syntax highlighting.
Explain non-obvious decisions in comments.
</OUTPUT_DESCRIPTION>

例 2：メンタルモデルとしての注意力の予算

大きなコンテキストを扱えるモデルでも、コンテキスト全体に均等に注意が向くわけではありません。実効容量はワークロードによって異なり、U字型の曲線により、中央に配置された情報は不利になります。上流のナレッジベースからどれだけ読み込むかを決めるときは、次のメンタルモデルを使います。「収まるか」ではなく、「重要な部分にモデルが引き続き注意を向けられるか」を考えてください。

負荷を軽減する手法を選ぶという、対応する運用上の問いは context-optimization の範囲です。

ガイドライン

1. コンテキストを、効果が逓減する有限のリソースとして扱います
2. 重要な情報は、注意が向きやすい位置（冒頭と末尾）に置きます
3. 必要になるまで読み込みを遅らせるために、段階的な開示を使います
4. 明確なセクション境界を設けてシステムプロンプトを整理します
5. 開発中はコンテキストの使用状況を監視します
6. 使用率が70-80%になったら圧縮を開始するよう設定します
7. コンテキストの劣化を避けられると期待するのではなく、劣化を前提に設計します
8. 低シグナルで大きなコンテキストよりも、小さく高シグナルなコンテキストを優先します

注意点

1. 公称ウィンドウサイズは実効容量ではありません：大きなコンテキストウィンドウをうたうモデルでも、複雑な検索や推論タスクでは、その上限に達するかなり前に性能が低下することがあります。独自の劣化テストで確認できるまでは、公称ウィンドウサイズより少ない量を予算として設定してください。

2. 文字数に基づくトークン推定は、気づかないうちにずれていきます：英語の文章に対する「1トークンあたり約4文字」という経験則は、コード（1トークンあたり2-3文字）、URLやファイルパス（スラッシュ、ピリオド、コロンはそれぞれ個別のトークン）、英語以外のテキスト（多くの場合、1トークンあたり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. 段階的な開示でも、早く読み込みすぎると目的が損なわれます：「関連する可能性のある」スキルや文書を、関連性が少しでも見えた段階ですべて読み込むと、コンテキストを詰め込む問題が再発します。厳格な有効化のしきい値を設定してください。スキルを読み込むのは、タスクがその発動条件に明確に一致したときだけにし、話題が単に隣接しているだけのときは読み込まないでください。

7. 抽象度の異なる指示を混在させると、一貫性のない振る舞いになります：「箇条書きを必ず3つにする」のような非常に具体的なルールと、「役に立つようにする」のような曖昧な指示を同じプロンプトに組み合わせると、互いに矛盾するシグナルが生じます。指示を抽象度ごとにまとめ、各セクション内に一貫性を持たせてください。経験則に基づく指示か、規範的な指示かのどちらかに統一し、両者を交互に混在させないでください。

統合

このスキルは概念的な基盤です。運用上の作業は担当せず、運用スキルが前提とする思考モデルを提供します。

運用作業の振り分けマップ：

• context-degradation：注意の失敗、情報の中間部分の喪失、汚染、注意散漫の診断。
• context-optimization：トークン効率化の手法（マスキング、分割、キャッシュ、予算）。
• memory-systems：エンティティ追跡を伴う、セッションをまたいだメモリーアーキテクチャ。
• multi-agent-patterns：コンテキストを分離するために作業をエージェント間で分担するタイミング。
• tool-design：適切に振り分けられるツールの説明とスキーマの作成。

まずこのスキルを読んで思考モデルを身につけ、実際に作業するときは、タスクに適した運用スキルを読んでください。

参考資料

内部資料：

• コンテキストコンポーネントのリファレンス - 次の場合に読みます：特定のコンテキストコンポーネント（システムプロンプト、ツール定義、メッセージ履歴、ツール出力）のデバッグ、またはチャンク化、観測のマスキング、予算配分テーブルの実装

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

• context-degradation - 次の場合に読みます：会話が長くなるにつれてエージェントのパフォーマンスが低下する、またはコンテキストが容量の60%を超えて埋まる
• context-optimization - 次の場合に読みます：トークンコストが高すぎる、またはコンパクション／圧縮戦略が必要

外部リソース：

• Anthropic の「Effective Context Engineering for AI Agents」— コンパクション、サブエージェント、ハイブリッド検索の本番環境向けパターン
• Transformer の注意機構と情報の中間部分の喪失に関する研究
• エージェント型ソフトウェアエンジニアリングにおけるトークン配分のトークノミクス研究