ai-docs

Effective context engineering for AI agents

Properties1
tagscontext, agents, memory, subagents, compaction, prompting

11 min read

一行要約

prompt engineering が「単発タスクの指示をどう書くか」なのに対し、context engineering はエージェントループの各ターンで「モデルに何を渡すか」を毎回決める反復的な営みであり、有限の attention budget をどう配分するかの問題である。

要点

context engineering と prompt engineering の違い

Context engineering refers to the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference, including all the other information that may land there outside of the prompts. context engineering とは、LLM の推論中に最適なトークン（情報）の集合をキュレートし維持するための戦略の総体を指す。プロンプト以外の経路でそこに入り込みうるあらゆる情報も含む。

Context engineering is the art and science of curating what will go into the limited context window from that constantly evolving universe of possible information. context engineering とは、絶えず移り変わる「ありうる情報」の宇宙の中から、限られた context window に何を入れるかを選び取る技であり科学である。

決定的な違いは反復性にある。

In contrast to the discrete task of writing a prompt, context engineering is iterative and the curation phase happens each time we decide what to pass to the model. プロンプトを書くという離散的な作業とは対照的に、context engineering は反復的であり、キュレーションの段階はモデルに何を渡すかを決めるたびに発生する。

context rot と attention budget

Studies on needle-in-a-haystack style benchmarking have uncovered the concept of context rot: as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases. needle-in-a-haystack 型のベンチマーク研究が context rot という概念を明らかにした。context window 内のトークン数が増えるにつれ、その context から情報を正確に思い出す能力は低下する。

Like humans, who have limited working memory capacity, LLMs have an “attention budget” that they draw on when parsing large volumes of context. working memory の容量が限られている人間と同じく、LLM も大量の context を解釈するときに引き出す「attention budget」を持っている。

Every new token introduced depletes this budget by some amount, increasing the need to carefully curate the tokens available to the LLM. **新しいトークンが1つ入るたびに、この予算はいくらか目減りする。**そのぶん、LLM が使えるトークンを注意深く選ぶ必要が高まる。

なぜそうなるのか:

LLMs are based on the transformer architecture, which enables every token to attend to every other token across the entire context. This results in n² pairwise relationships for n tokens. LLM は transformer アーキテクチャに基づいており、context 全体にわたって各トークンが他のすべてのトークンに注意を向けられる。その結果、n 個のトークンに対して n² 個の対関係が生じる。

短い系列で訓練されたモデルは、長距離依存のためのパラメータが相対的に少ない、という要因も挙げられている。 結論として、context は「多いほど良い」資源ではなく、配分すべき予算として扱う。

system prompt の「altitude（高度）」

最適な system prompt は両極端の間の Goldilocks zone にある。

  • 低すぎる: if-else を人手でハードコードしたような脆い指示
  • 高すぎる: 文脈を勝手に前提とした曖昧な指示

The optimal altitude strikes a balance: specific enough to guide behavior effectively, yet flexible enough to provide the model with strong heuristics to guide behavior. 最適な高度は釣り合いを取る。振る舞いを効果的に導けるだけ具体的でありながら、振る舞いを導く強いヒューリスティクスをモデルに与えられるだけ柔軟である。

主要テクニック 4種

1. Just-in-time context retrieval

Rather than pre-processing all relevant data up front, agents built with the “just in time” approach maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools. 関連データをすべて事前に処理しておくのではなく、「just in time」方式で作られたエージェントは軽量な識別子（ファイルパス、保存したクエリ、web リンクなど）を保持し、それらの参照を使って実行時にツールで動的にデータを context へロードする。

Claude Code がこの方式の実例。head、tail、bash などによる的を絞ったクエリで、巨大なデータを context に載せずに分析する。

2. Compaction

Compaction is the practice of taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window with the summary. compaction とは、context window の限界に近づいた会話を取り上げ、その内容を要約し、その要約で新しい context window を初期化し直すという実践である。

  • 保持すべきもの: アーキテクチャ上の決定、未解決のバグ、実装の詳細
  • 捨てるもの: 冗長な出力

チューニングには順序がある。

Start by maximizing recall to ensure your compaction prompt captures every relevant piece of information from the trace, then iterate to improve precision by eliminating superfluous content. まず recall を最大化し、compaction のプロンプトが trace から関連情報を漏れなく捉えるようにせよ。その後、余計な内容を削って precision を高める方向に反復せよ。

3. Structured note-taking (agentic memory)

Structured note-taking, or agentic memory, is a technique where the agent regularly writes notes persisted to memory outside of the context window. These notes get pulled back into the context window at later times. structured note-taking（agentic memory）とは、エージェントが context window の外にあるメモリへ定期的にノートを書き出して永続化する手法である。それらのノートは、後の時点で context window へ引き戻される。

例: Claude が Pokémon をプレイする際、数千ステップにわたって集計・マップ・戦闘戦略を維持した。

4. Sub-agent architectures

Rather than one agent attempting to maintain state across an entire project, specialized sub-agents can handle focused tasks with clean context windows. 1つのエージェントがプロジェクト全体にわたって状態を保とうとするのではなく、専門化された sub-agent が、きれいな context window で焦点の絞られたタスクを扱える。

Each subagent might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens). 各 subagent は数万トークン以上を使って広範に探索しうるが、返すのは自分の仕事を凝縮し蒸留した要約だけである（多くの場合 1,000〜2,000 トークン）。

詳細な探索の文脈と、高レベルの統合の文脈を分離する。

その他の指針

ツール設計: 重複を最小化し、パラメータ名が説明的かつ曖昧でないこと。機能を詰め込みすぎたツールはエージェントを迷わせる。

Tools should be self-contained, robust to error, and extremely clear with respect to their intended use. ツールは自己完結的で、エラーに対して頑健で、意図された用途に関して極めて明確であるべきだ。

few-shot examples: エッジケースを網羅列挙するのではない。

We recommend working to curate a set of diverse, canonical examples that effectively portray the expected behavior of the agent. エージェントに期待する振る舞いを効果的に描き出す、多様で canonical な例の集合を厳選することを勧める。

  • hybrid 戦略: 速度のための事前 retrieval と、実行時の自律的探索を組み合わせる。変化の少ないコンテンツ（法務、金融）や、効率と柔軟性の両方が要るときに適する。

長期タスクでの手法選択

状況選ぶ手法
会話の流れを保つ必要がある、広範な往復Compaction
明確なマイルストーンを伴う反復的な開発Structured note-taking
並列探索が効く複雑なリサーチMulti-agent (sub-agents)

原典の結語

Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome. 望む結果が得られる見込みを最大にする、高信号なトークンの最小集合を見つけよ。

そのまま使える具体例

原典は概念中心で、コード断片は提示していない。実務への落とし込みとして原典が挙げているのは以下の対応。

  • just-in-time の実装例 = Claude Code の head / tail / bash によるファイル探索
  • structured note-taking の実装例 = Claude Plays Pokémon の外部ノート
  • sub-agent の返却サイズ目安 = 1,000〜2,000 トークンの要約

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク