context-fundamentals

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

コンテキストとは、推論時に言語モデルが利用できる完全な状態のことです。これには、モデルが応答を生成する際に注目できるすべてのものが含まれます。システム指示、ツール定義、取得したドキュメント、メッセージ履歴、ツール出力などです。コンテキストの基礎を理解することは、効果的なコンテキストエンジニアリングの前提条件です。

使用する場面

次の場合にこのスキルを有効にします。

• 新しいエージェントシステムを設計する場合、または既存のアーキテクチャを変更する場合
• コンテキストに関連する可能性のある、予期しないエージェントの動作をデバッグする場合
• トークンコストを削減したりパフォーマンスを向上させたりするためにコンテキストの使用を最適化する場合
• 新しいチームメンバーにコンテキストエンジニアリングの概念をオンボーディングする場合
• コンテキストに関連する設計上の決定をレビューする場合

中核となる概念

コンテキストはいくつかの異なるコンポーネントで構成されており、それぞれに異なる特性と制約があります。アテンション機構は有限の予算を生み出し、それが効果的なコンテキストの使用を制約します。プログレッシブディスクロージャーは、必要な情報だけを読み込むことでこの制約を管理します。エンジニアリングの規律とは、望ましい成果を達成する最小の高シグナルトークンセットを選別することです。

詳細なトピック

コンテキストの構成要素

システムプロンプト システムプロンプトは、エージェントの中核となるアイデンティティ、制約、行動指針を定めます。セッション開始時に一度読み込まれ、通常は会話全体を通じて保持されます。システムプロンプトは非常に明確で、エージェントに適した抽象度で、簡潔かつ直接的な言葉を使う必要があります。

適切な抽象度は、2つの失敗パターンのバランスを取ります。一方の極端では、エンジニアが複雑で脆弱なロジックをハードコードし、壊れやすさやメンテナンスの負担を生みます。もう一方の極端では、エンジニアが曖昧で高レベルな指針を提示するため、望ましい出力を示す具体的な手がかりが不足したり、共通の文脈があると誤って想定したりします。最適な抽象度は、効果的に行動を導くのに十分具体的でありながら、強力なヒューリスティックを提供できる柔軟性も備えています。

背景情報、指示、ツールの使用方法、出力の説明を区別できるよう、XML タグまたは Markdown の見出しを使ってプロンプトを明確なセクションに整理します。モデルの能力が向上するにつれて厳密な書式の重要性は低くなりますが、構造を明確にすることには引き続き価値があります。

ツール定義 ツール定義は、エージェントが実行できる操作を指定します。各ツールには、名前、説明、パラメーター、戻り値の形式が含まれます。ツール定義はシリアライズ後のコンテキストの前方、通常はシステムプロンプトの前後に配置されます。

ツールの説明は、全体としてエージェントの行動を方向付けます。不十分な説明ではエージェントに推測を強いることになりますが、最適化された説明には使用する状況、例、既定値が含まれます。統合の原則によれば、人間のエンジニアが特定の状況でどのツールを使うべきか明確に判断できないなら、エージェントにそれ以上の判断を期待することはできません。

取得したドキュメント 取得したドキュメントは、特定の分野の知識、参考資料、またはタスクに関連する情報を提供します。エージェントは検索拡張生成を利用し、考えられるすべての情報を事前に読み込むのではなく、実行時に関連するドキュメントをコンテキストに取り込みます。

ジャストインタイム方式では、軽量な識別子（ファイルパス、保存済みクエリ、ウェブリンク）を保持し、それらの参照先からデータを動的にコンテキストへ読み込みます。これは人間の認知にも似ています。私たちは通常、情報のコーパス全体を暗記するのではなく、外部の整理・索引システムを使い、必要に応じて関連情報を取得します。

メッセージ履歴 メッセージ履歴には、過去のクエリ、応答、推論を含む、ユーザーとエージェントの会話が記録されます。長時間にわたるタスクでは、メッセージ履歴が増加し、コンテキストの使用量の大部分を占めることがあります。

メッセージ履歴はスクラッチパッドメモリとして機能し、エージェントが進捗を追跡し、タスクの状態を維持し、ターンをまたいで推論を保持するのに役立ちます。長期にわたるタスクを完了するには、メッセージ履歴を効果的に管理することが重要です。

ツール出力 ツール出力は、エージェントが操作した結果です。ファイルの内容、検索結果、コマンドの実行結果、API の応答などが含まれます。一般的なエージェントの実行過程では、ツール出力がトークンの大部分を占めます。調査によると、一部のワークロードでは観測結果（ツール出力）が支配的になることがありますが、このツリーは普遍的な割合を裏付けるデータセットを提供していません。

ツール出力は、現在の判断に関連しているかどうかにかかわらず、コンテキストを消費します。そのため、観測結果のマスキング、圧縮、選択的なツール結果の保持といった戦略が必要になります。

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

注意予算の制約 言語モデルは、コンテキスト内のすべてのトークン間にペアごとの関係を作り出す注意メカニズムを通じて、トークンを処理します。密な自己注意では、系列長に対する事前処理時の相互作用数は二次関数的に増加します。最適化されたカーネル、スパースアーキテクチャ、キャッシュを利用したデコードでは、メモリや実行時の特性がそれぞれ異なります。コンテキストが長くなるにつれて、こうした関係を捉えるモデルの能力は手薄になります。

モデルは、短い系列が多くを占める学習データの分布から注意パターンを身につけます。つまり、モデルはコンテキスト全体にわたる依存関係に触れる機会が少なく、そのための専用パラメーターも少なくなります。その結果、コンテキストが拡大するにつれて「注意予算」が枯渇します。

位置エンコーディングとコンテキストの拡張 位置エンコーディングの補間により、モデルが当初学習した短いコンテキストに適応させることで、より長い系列を扱えるようになります。しかし、この適応によってトークン位置の理解が劣化します。モデルはより長いコンテキストでも高い能力を保ちますが、短いコンテキストの場合と比べて、情報検索や長距離推論の精度が低下します。

段階的開示の原則 段階的開示では、必要な場合にのみ情報を読み込むことで、コンテキストを効率的に管理します。起動時にエージェントが読み込むのはスキル名と説明だけで、あるスキルが役立つ可能性のある場面を判断するには十分です。特定のタスクでスキルが有効化された場合に限り、完全な内容が読み込まれます。

この方法により、エージェントは高速さを保ちながら、必要に応じてより多くのコンテキストにアクセスできます。この原則は、スキルの選択、ドキュメントの読み込み、さらにはツールの結果の取得など、複数のレベルに適用できます。

コンテキストの質と量

コンテキストウィンドウを大きくすれば記憶の問題が解決するという前提は、実証的に否定されています。コンテキストエンジニアリングとは、望ましい結果が得られる可能性を最大化する、高い信号を持つ最小限のトークンを見つけることです。

コンテキストの効率化が求められる要因はいくつかあります。処理コストはコンテキスト長とともに不均衡に増加します。トークンを2倍にするとコストも単純に2倍になるのではなく、密な注意では事前処理の作業量が超線形に増える可能性がありますが、実際のコストはアーキテクチャ、カーネル、キャッシュ、プロバイダーの料金設定によって異なります。ウィンドウが技術的により多くのトークンに対応していても、特定の長さを超えるとモデルの性能は低下します。プレフィックスキャッシュを使った場合でも、長い入力にはコストがかかります。

指針となる原則は、網羅性よりも情報量です。目の前の判断に重要な情報を含め、重要でない情報は除外し、必要に応じて追加情報にアクセスできるシステムを設計します。

限りあるリソースとしてのコンテキスト

コンテキストは、限りあるリソースであり、限界効用が逓減するものとして扱う必要があります。作業記憶に限界のある人間と同じように、言語モデルにも、大量のコンテキストを解析する際に消費される注意予算があります。

新しいトークンが追加されるたびに、この予算はある程度消費されます。そのため、利用可能なトークンを慎重に選別する必要があります。エンジニアリング上の課題は、固有の制約のもとで有用性を最適化することです。

コンテキストエンジニアリングは反復的なものであり、モデルに何を渡すかを決めるたびに選別を行います。一度きりのプロンプト作成作業ではなく、継続的なコンテキスト管理の実践です。

読み込み、シリアライズ、プレフィックスキャッシュ、指示の保持は、クライアントやモデルによって異なります。すべてのツール定義やルールファイルが常に存在すると想定せず、実際の動作を確認してください。「注意予算」はエンジニアリング上の比喩であり、トークンごとに消費される文字どおりのリソースではありません。取得したドキュメントやツール出力は信頼できない根拠として扱い、指示の権限を分け、コンテキストや要約を保存する前に秘密情報を削除してください。70～80％といったしきい値は調整可能な経験則であり、タスクごとの測定が必要です。

実践的なガイダンス

ファイルシステムベースのアクセス

ファイルシステムにアクセスできるエージェントは、プログレッシブディスクロージャーを自然に活用できます。参考資料、ドキュメント、データは外部に保存します。必要なときだけ、標準的なファイルシステム操作を使ってファイルを読み込みます。このパターンにより、関連しない可能性のある情報でコンテキストが埋め尽くされるのを防げます。

ファイルシステム自体が、エージェントがたどれる構造を提供します。ファイルサイズから複雑さを推測でき、命名規則から用途の手がかりが得られ、タイムスタンプは関連性の目安になります。ファイル参照のメタデータにより、動作を効率的に調整できます。

ハイブリッド戦略

最も効果的なエージェントは、ハイブリッド戦略を採用します。一部のコンテキスト（CLAUDE.md ファイルやプロジェクトのルールなど）は速度を重視して事前に読み込みますが、必要に応じて追加のコンテキストを自律的に探索できるようにします。どちらを選ぶかは、タスクの特性とコンテキストの変化によって決まります。

内容の変化が少ないコンテキストでは、より多くの情報をあらかじめ読み込むのが適しています。急速に変化する情報や、きわめて具体的な情報については、必要なときに読み込むことで古くなったコンテキストを避けられます。

コンテキストの予算管理

明確なコンテキスト予算を念頭に置いて設計します。モデルとタスクで実際に使えるコンテキストの上限を把握してください。開発中はコンテキストの使用量を監視します。適切なしきい値で圧縮を開始するトリガーを実装します。コンテキストが劣化しないことを期待するのではなく、劣化することを前提にシステムを設計してください。

効果的なコンテキスト予算管理には、単純なトークン数だけでなく、注意の分布パターンを理解することも必要です。コンテキストの中央部は、冒頭や末尾よりも注意が向けられにくくなります。重要な情報は、注意を向けられやすい位置に置いてください。

例

例 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>

<TOOL_GUIDANCE>
Use bash for shell operations, python for code tasks.
File operations should use pathlib for cross-platform compatibility.
</TOOL_GUIDANCE>

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

例 2：段階的なドキュメントの読み込み

# Instead of loading all documentation at once:

# Step 1: Load summary
docs/api_summary.md          # Lightweight overview

# Step 2: Load specific section as needed
docs/api/endpoints.md        # Only when API calls needed
docs/api/authentication.md   # Only when auth context needed

ガイドライン

1. コンテキストは限りあるリソースであり、利用するほど効果が薄れるものとして扱う
2. 重要な情報は、注意を向けられやすい位置（冒頭と末尾）に置く
3. プログレッシブディスクロージャーを使い、必要になるまで読み込みを遅らせる
4. システムプロンプトは、セクションの境界を明確にして整理する
5. 開発中はコンテキストの使用量を監視する
6. 使用率が 70～80% に達したら圧縮を開始するトリガーを実装する
7. コンテキストの劣化を避けられると期待するのではなく、劣化を前提に設計する
8. 低シグナルで大きなコンテキストよりも、高シグナルで小さなコンテキストを優先する

統合

このスキルは、他のすべてのスキルの土台となるコンテキストを提供します。次の内容を調べる前に、まずこのスキルを学習してください。

• context-degradation - コンテキストがどのように機能しなくなるかを理解する
• context-optimization - コンテキスト容量を拡張する手法
• multi-agent-patterns - コンテキストの分離によってマルチエージェントシステムを実現する方法
• tool-design - ツール定義がコンテキストとどのように連携するか

参考資料

内部資料：

• Context Components Reference - 詳細な技術リファレンス

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

• context-degradation - コンテキストの失敗パターンを理解する
• context-optimization - コンテキストを効率的に利用する手法

外部リソース：

• Transformer の注意機構に関する研究
• 主要な AI 研究機関による本番環境向けエンジニアリングガイド
• コンテキストウィンドウ管理に関するフレームワークのドキュメント

---

スキルのメタデータ

作成日：2025-12-20 最終更新日：2025-12-20 作成者：Agent Skills for Context Engineering Contributors バージョン：1.0.0

制限事項

• このスキルは、タスクが上記の説明範囲に明確に当てはまる場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。