上下文工程

After a few years of prompt engineering being the focus of attention in applied AI, a new term has come to prominence: context engineering. Building with language models is becoming less about finding the right words for your prompts, and more about answering "what configuration of context is most likely to generate the model's desired behavior?" Context refers to the set of tokens included when sampling from an LLM. The engineering problem is optimizing the utility of those tokens against the inherent constraints of LLMs.

经过几年"提示工程"占据应用 AI 中心舞台之后，一个新术语开始流行：上下文工程（context engineering）。用语言模型构建产品，越来越少是"找到提示词里正确的措辞"，而越来越多是回答一个更宏大的问题——"什么样的上下文配置最可能让模型产生我们想要的行为？"上下文就是从大语言模型采样时包含的那一组 token。而这里的工程问题，是在 LLM 固有的约束下，优化这些 token 的效用，从而稳定地达成预期结果。

上下文工程 vs. 提示工程

At Anthropic, we view context engineering as the natural progression of prompt engineering. Prompt engineering = methods for writing and organizing LLM instructions. Context engineering = strategies for curating and maintaining the optimal set of tokens (information) during inference, including everything that lands in context outside the prompts. As we engineer more capable agents that operate over many turns and longer horizons, we need strategies to manage the entire context state. An agent running in a loop constantly generates more data that could be relevant for the next turn — this information must be cyclically refined.

Anthropic 把上下文工程视为提示工程的自然延伸。提示工程指的是编写和组织 LLM 指令的方法；上下文工程则指在 LLM 推理过程中策展和维护最优 token 集合的策略——包括除提示之外、所有可能进入上下文的信息。早期 LLM 工程以"写好提示"为主，因为多数用例是一次性的分类或文本生成。但随着我们要构建在多轮推理、更长的时间跨度上运作的更强大 Agent，就必须管理整个上下文状态（系统指令、工具、MCP、外部数据、消息历史等）。在一个循环里运行的 Agent 会不断产生可能与下一轮相关的数据，这些信息必须被循环式地精炼。

为什么上下文工程对构建 Agent 至关重要

Despite managing ever-larger volumes of data, LLMs — like humans — lose focus at a certain point. "Needle-in-a-haystack" benchmarking revealed context rot: as the number of tokens in the context window grows, the model's ability to accurately recall information decreases. Context must be treated as a finite resource with diminishing marginal returns. LLMs have an "attention budget" drawn down by every token. Architecturally, the transformer lets every token attend to every other token — n² pairwise relationships — so as context length grows, attention gets stretched thin. The result is a performance gradient rather than a hard cliff: models stay capable but show reduced precision for retrieval and long-range reasoning.

尽管 LLM 能处理越来越大的数据量，但和人类一样，它会在某个临界点失去焦点。"大海捞针"式基准测试揭示了一个现象——上下文腐烂（context rot）：随着上下文窗口里的 token 越来越多，模型准确回忆其中信息的能力反而下降。所有模型都存在这一特征，只是程度不同。因此，上下文必须被视为一种边际收益递减的有限资源。LLM 有一个"注意力预算"，每个新 token 都会消耗一部分。从架构上看，Transformer 让每个 token 都能关注其他所有 token——形成 n² 对关系——上下文越长，注意力被拉得越稀薄。结果是一个性能梯度而非悬崖：模型依然能干，但在信息检索和长程推理上精度会下降。

有效上下文的解剖学

Given a finite attention budget, good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of a desired outcome. We apply this across components: system prompts, tools, and examples. System prompts should use simple, direct language at the right altitude — the Goldilocks zone between brittle if-else hardcoded logic and overly vague guidance. Organize prompts into distinct sections (background, instructions, tool guidance, output description) with XML tags or Markdown headers. Aim for the minimal set of information that fully outlines expected behavior; start minimal, then add instructions based on real failure modes.

在有限的注意力预算下，好的上下文工程意味着找到最小的高信号 token 集合，去最大化达成预期结果的概率。这条原则贯穿各个组件：

① 系统提示。应当使用简单、直接的语言，处在正确的高度——这是两种常见失败模式之间的"金发姑娘区间"：一端是把复杂脆弱的逻辑硬编码进提示来强行规定行为（造成脆弱和高维护成本），另一端是给出过于笼统、缺乏具体信号或错误假设共享上下文的指引。建议把提示组织成清晰的区段（如 background_information、instructions、## Tool guidance、## Output description），用 XML 标签或 Markdown 标题分隔。追求"完整描述预期行为的最小信息集"——注意"最小"不等于"短"，你仍要给足信息。先用最强模型测试一个最小提示，再根据真实失败模式添加说明和示例。

Tools let agents operate on their environment and pull in new context. Because tools define the contract between agents and their information/action space, they must promote efficiency — token-efficient returns and efficient agent behaviors. Tools should be self-contained, robust, and unambiguous. A common failure mode is bloated tool sets with overlapping functionality; if a human engineer can't definitively pick the right tool, an AI agent can't either. Curate a minimal viable set of tools. Few-shot examples (the "pictures worth a thousand words") should be a diverse, canonical set portraying expected behavior — not a laundry list of edge cases.

② 工具。工具让 Agent 操作环境、引入新上下文。因为工具定义了 Agent 与其信息/动作空间之间的契约，所以工具必须促进效率——既返回 token 高效的信息，也鼓励高效的 Agent 行为。工具应当自包含、容错、用途极其清晰，输入参数要描述性强且无歧义。一个常见失败模式是臃肿的工具集：功能重叠、难以判断该用哪个。如果连人类工程师都无法确定某个场景该用哪个工具，就不能指望 AI Agent 做得更好。策展一个最小可用工具集往往能带来更可靠的长期维护。

③ 示例（少样本）。提供示例是强烈推荐的最佳实践，但不要把一堆边界情况塞进提示来穷举规则。相反，应策展一组多样、典范式的示例来有效呈现 Agent 的预期行为——对 LLM 来说，示例就是"胜过千言"的图。

贯穿系统提示、工具、示例、消息历史的总指引：深思熟虑，让上下文既有信息量又紧凑（informative yet tight）。

上下文检索与 Agentic 搜索

We use a simple definition for agents: LLMs autonomously using tools in a loop. As models improve, autonomy can scale. Many AI-native apps use embedding-based pre-inference retrieval; increasingly, teams augment this with "just-in-time" context. Rather than pre-processing all data up front, agents keep lightweight identifiers (file paths, stored queries, web links) and dynamically load data at runtime via tools. Claude Code writes targeted queries, stores results, and uses Bash (head/tail) to analyze large data without loading it all. This mirrors human cognition: we don't memorize entire corpuses — we use file systems, inboxes, bookmarks to retrieve on demand. Metadata (folder hierarchies, naming, timestamps) provides signals for progressive disclosure: each interaction yields context that informs the next decision.

我们对 Agent 用一个简单定义：LLM 在循环中自主地使用工具。随着模型变强，Agent 的自主性可以随之扩展。如今很多 AI 原生应用采用基于嵌入的推理前检索来提前浮现上下文；越来越多团队在此基础上叠加"即时"（just-in-time）上下文策略。与其预先处理所有相关数据，Agent 反而维护轻量标识符（文件路径、存储的查询、网页链接），在运行时用工具动态地把数据加载进上下文。

Anthropic 的 Agentic 编码方案 Claude Code 就用这种方式对大型数据库做复杂数据分析：模型写定向查询、存储结果，并用 head、tail 等 Bash 命令分析海量数据，而不必将完整数据对象载入上下文。这镜像了人类认知——我们通常不记忆整个语料库，而是借助文件系统、收件箱、书签等组织与索引系统按需检索。这些引用的元数据（文件夹层级、命名约定、时间戳）也提供了渐进式披露（progressive disclosure）的信号：每一次交互都产生指导下一步决策的上下文——文件大小暗示复杂度，命名暗示用途，时间戳可作为相关性代理。

There's a trade-off: runtime exploration is slower than pre-computed retrieval, and requires thoughtful engineering so the LLM has the right tools and heuristics. Claude Code uses a hybrid: CLAUDE.md files are loaded up front, while glob/grep let it navigate and retrieve just-in-time, bypassing stale indexing. The decision boundary for autonomy depends on the task. As models improve, design trends toward letting intelligent models act intelligently, with progressively less human curation. "Do the simplest thing that works" remains our best advice.

当然有权衡：运行时探索比检索预计算数据慢，还需要精心设计工程，确保 LLM 拥有合适的工具和启发式规则去有效导航信息景观——否则 Agent 会因误用工具、追逐死胡同或找不到关键信息而浪费上下文。在某些场景，最有效的 Agent 采用混合策略：部分数据预先检索以换取速度，其余按需自主探索。Claude Code 就是混合模型：CLAUDE.md 文件被预先朴素地放入上下文，而 glob、grep 等原语让它即时导航环境、检索文件，有效绕过了陈旧索引和复杂语法树的问题。自主性的"正确"边界取决于任务。随着模型能力提升，Agentic 设计会趋向于让智能模型智能地行动，逐步减少人工策展。鉴于领域进展之快，"做最简单且有效的那个"仍是我们对基于 Claude 构建 Agent 的团队的最佳建议。

长程任务的上下文工程

Long-horizon tasks require maintaining coherence over sequences where token count exceeds the context window — like multi-hour codebase migrations or research projects. Waiting for larger windows won't fully solve this; windows of all sizes will still face context pollution. Three techniques address it: compaction, structured note-taking, and multi-agent architectures.

长程任务要求 Agent 在 token 数超出上下文窗口的动作序列上维持连贯性、上下文和目标导向行为——比如持续几十分钟到数小时的大型代码库迁移或综合研究项目。等更大的上下文窗口并非解药：可预见的未来里，任何尺寸的窗口都会受到上下文污染和信息相关性问题的困扰——至少在你追求最强 Agent 性能时如此。为此 Anthropic 发展了三种技术：压缩、结构化笔记、多智能体架构。

Compaction takes a conversation nearing the window limit, summarizes it, and restarts with the summary. In Claude Code, the model summarizes message history — preserving architectural decisions, unresolved bugs, implementation details while discarding redundant tool outputs — then continues with the compressed context plus the five most recently accessed files. The art is selecting what to keep vs. discard; tune prompts to maximize recall first, then iterate on precision. Tool-result clearing is a safe, light-touch form of compaction.

① 压缩（Compaction）。把一个接近上下文窗口上限的对话总结后重新开启一个新窗口。它通常是上下文工程里改善长期连贯性的第一杠杆。核心是高保真地蒸馏窗口内容，让 Agent 几乎无性能损失地继续。在 Claude Code 中，做法是把消息历史交给模型去总结压缩——保留架构决策、未解决的 bug、实现细节，丢弃冗余的工具输出或消息，然后带着压缩后的上下文加上最近访问的 5 个文件继续。用户获得连续性而无需操心窗口限制。压缩的艺术在于取舍：过于激进的压缩会丢失那些重要性后来才显现的微妙但关键的信息。建议先最大化召回率（确保捕获每条相关信息），再迭代提升精确度（剔除多余内容，比如清除消息历史深处的工具原始结果）。工具结果清除是最安全、最轻量的压缩形式。

Structured note-taking (agentic memory): the agent regularly writes notes persisted outside the context window, pulled back in later. Claude Code's to-do list, or a custom agent's NOTES.md, tracks progress across complex tasks. Claude playing Pokémon maintains tallies across thousands of steps — training objectives, maps of explored regions, combat strategies — and after context resets reads its own notes to continue multi-hour sequences. A file-based memory tool (beta) lets agents build knowledge over time and reference prior work without keeping it all in context.

② 结构化笔记（Agent 记忆）。Agent 定期把笔记写到上下文窗口之外的持久记忆里，之后按需拉回上下文。这种策略以极小开销提供持久记忆。就像 Claude Code 创建 to-do 清单，或你的自定义 Agent 维护一个 NOTES.md——这个简单模式让 Agent 能在复杂任务中跟踪进度，保住那些否则会在几十次工具调用间丢失的关键上下文与依赖。Claude 玩宝可梦展示了记忆如何改变非编码领域的 Agent 能力：它跨数千个游戏步骤维持精确计数（如"过去 1234 步我一直在 1 号道路练级，皮卡丘朝 10 级的目标升了 8 级"），自动绘制已探索区域的地图、记住已解锁的成就、记录对哪种对手用哪种攻击最有效的战斗策略笔记。上下文重置后，它会读取自己的笔记继续数小时的训练或地牢探索。这种跨总结步骤的连贯性，使得仅靠 LLM 上下文窗口不可能实现的长程策略成为可能。Anthropic 还在 Sonnet 4.5 发布时推出了一个基于文件的内存工具（公测），让 Agent 随时间积累知识库、跨会话维护项目状态、引用先前工作。

Sub-agent architectures: rather than one agent holding all state, specialized sub-agents handle focused tasks with clean context windows. The main agent coordinates a high-level plan while subagents do deep work — each might use tens of thousands of tokens but returns only a condensed summary (1,000–2,000 tokens). This separates concerns: detailed search context stays isolated in sub-agents; the lead agent synthesizes. Which approach fits depends on the task: compaction for extensive back-and-forth; note-taking for iterative work with milestones; multi-agent for parallel research.

③ 子智能体架构。与其让一个 Agent 跨整个项目维护状态，不如让专门的子智能体用干净的上下文窗口处理聚焦任务。主控智能体用一个高层计划做协调，子智能体执行深度技术工作或用工具查找相关信息。每个子智能体可能大量探索（耗费数万 token），但只返回一份浓缩的总结（通常 1000–2000 token）。这实现了清晰的关注点分离——详细搜索上下文被隔离在子智能体内部，主控智能体专注于综合与分析结果。

三种方法的选择取决于任务特性：压缩适合需要大量来回、要保持对话流的任务；笔记适合有清晰里程碑的迭代开发；多智能体架构适合并行探索能带来红利的复杂研究与分析。即便模型持续改进，跨长程交互维持连贯性仍将是构建更有效 Agent 的核心挑战。

结论

Context engineering is a fundamental shift in how we build with LLMs. As models grow more capable, the challenge isn't just the perfect prompt — it's thoughtfully curating what enters the model's limited attention budget at each step. Whether compaction, token-efficient tools, or just-in-time exploration, the guiding principle stays the same: find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome. Smarter models need less prescriptive engineering, but treating context as a precious, finite resource will remain central to building reliable agents.

上下文工程代表了我们用 LLM 构建方式的根本性转变。随着模型变得更强，挑战不再只是写出完美提示——而是在每一步深思熟虑地策展进入模型有限注意力预算的信息。无论是为长程任务做压缩、设计 token 高效的工具，还是让 Agent 即时探索环境，指导原则始终如一：找到最小的高信号 token 集合，去最大化预期结果的概率。这些技术会随模型进步而演化——更聪明的模型需要更少的规定性工程，Agent 能以更高自主性运作。但即便能力不断攀升，把上下文当作珍贵、有限的资源来对待，仍将是构建可靠、有效 Agent 的核心。