context-fundamentals

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

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

このスキルは、このコレクションにあるほかのすべてのスキルの概念的な基盤です。コンテキストとは何か、注意の仕組みがどのように働くか、量より質が重要な理由、そしてコンテキストエンジニアリングに関するほかのあらゆる判断を理解するために必要なメンタルモデルについて説明します。運用作業は対象にしません。注意の失敗のデバッグは context-degradation、トークン効率化の手法は context-optimization、会話の要約は context-compression、ファイルを使ったオフロードは filesystem-context、プロジェクトの構成に関する判断は project-development が担当します。

有効化するタイミング

作業が概念的な内容である場合は、このスキルを有効にしてください。

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

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

• 情報の中間位置での見落とし、コンテキストの汚染、注意の失敗を診断する：context-degradation。
• マスキング、分割、プレフィックスキャッシュ、予算設定によってトークンコストを削減する：context-optimization。
• 長いセッションを引き継ぎ用の要約に圧縮する：context-compression。
• 大量のツール出力をオフロードする、または永続的なスクラッチパッドを維持する：filesystem-context。
• LLM プロジェクトやパイプラインの構成を決める：project-development。

コアコンセプト

コンテキストは保管場所ではなく、有限の注意予算として扱ってください。追加されるトークンはすべてモデルの注意を奪い合い、推論中に補充できない予算を消費します。エンジニアリング上の課題は、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）どの圧縮方法なら適切な状態を保持できるか、また利用率がどのしきい値に達したら圧縮を開始するか（context-compression）です。

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

コンテキストエンジニアリングに初めて取り組むコントリビューターは、次の順序で読んでください。

1. 注意の予算という捉え方と U 字型の曲線を理解するために、このスキルを読みます。
2. 実際にどのようなコンテキストの失敗が起きるか、またその診断方法を知るために、context-degradation を読みます。
3. プロジェクトで最も関連性の高い運用上の課題に応じて、context-optimization、context-compression、filesystem-context、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：注意力の低下、lost-in-middle、ポイズニング、注意散漫の診断。
• context-optimization：トークン効率化の手法（マスキング、分割、キャッシュ、予算設定）。
• context-compression：判断、ファイル、リスクを保持しながら、長時間のセッションを圧縮。
• filesystem-context：大きな出力を外部に移し、ファイルを永続的なスクラッチパッドとして活用。
• memory-systems：エンティティ追跡を伴う、セッションをまたいだメモリアーキテクチャ。
• multi-agent-patterns：コンテキストを分離するために、作業をエージェント間で分担すべき状況。
• tool-design：適切に振り分けられるツールの説明とスキーマの作成。
• project-development：LLM の適合性を判断し、多段階のパイプラインを設計。

まずこのスキルを読み、メンタルモデルを構築してください。実際に作業を行う際は、タスクに適した運用スキルを読んでください。

参考資料

内部リファレンス：

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

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

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

外部リソース：

• Anthropic の「AI エージェントのための効果的なコンテキストエンジニアリング」 — コンパクション、サブエージェント、ハイブリッド検索の本番環境向けパターン
• Transformer のアテンションメカニズムと lost-in-the-middle 効果に関する研究
• エージェント型ソフトウェアエンジニアリングにおけるトークン分布に関する Tokenomics の研究

---

スキルのメタデータ

作成日: 2025-12-20 最終更新日: 2026-05-15 作成者: Agent Skills for Context Engineering Contributors バージョン: 2.2.0