夜雨聆风来源：Anthropic Engineering原文：Effective context engineering for AI agents
发布时间：2025年9月29日
这个系列要学什么
从2025年9月到2026年4月，Anthropic发布了关于AI agent的几篇文章。我根据原文，整理出了一套系列文章，逐篇学习 AI Agent 工程里的几个重点主题（关注公众号，回 复” agent“ ， 获取完整原文文档）：
1. Effective context engineering for AI agents 2. Writing effective tools for agents 3. Equipping agents for the real world with Agent Skills 4. Code execution with MCP 5. Harness design for long-running application development
本篇是AI agent系列的第一篇文章：Context Engineering。后面四个主题会每天8:31推出，敬请期待
简介
这篇文章讲的是：当 AI Agent 不再只是回答一个问题，而是要持续多轮使用工具、读取资料、处理任务时，工程重点会从“写好提示词”变成“管理好模型每一步看到的上下文”。
Anthropic 给出的核心原则很直接：找到最小的一组高信号 token，让模型最有可能做出期望行为。
Context engineering 和 prompt engineering 的区别
在 prompt engineering 之后，context engineering 正在成为使用语言模型的新重点。
早期使用 LLM 时，很多任务是一轮完成的，比如分类、摘要、生成一段文字。这个时候，主要工程工作是写好 prompt，尤其是 system prompt：告诉模型角色、目标、输出格式和约束。
但 Agent 不一样。Agent 会在循环里运行：读信息、调用工具、观察结果、继续决策。它的行为不只由一段 prompt 决定，还由整个上下文状态决定。
这里的 context，可以理解为模型在采样下一段输出时能看到的所有 token。它包括：
• system instructions • tool definitions • MCP • external data • message history • tool outputs • examples • Agent 自己在任务过程中积累的中间状态
Prompt engineering 关注的是“怎样写指令”。Context engineering 关注的是“在这一刻，应该把哪些信息放进模型有限的上下文窗口里”。
Anthropic 把 context engineering 看作 prompt engineering 的自然演进。随着 Agent 任务时间变长，系统会不断产生新的数据：工具调用结果、错误信息、文件内容、搜索结果、对话历史、计划变更。这些信息都可能对下一轮有用，也都可能变成噪声。
所以 context engineering 的工作，不是一次性写一段完美 prompt，而是在不断变化的信息集合中，反复选择什么应该进入有限的 context window。
为什么 context engineering 对 Agent 很重要
LLM 和人一样，信息一多就容易失焦。
Anthropic 引用了 needle-in-a-haystack benchmark 里的一个现象：context window 变长之后，模型在上下文中准确回忆信息的能力会下降。这个现象被称为 context rot。不同模型的退化曲线不一样，但所有模型都会受到影响。
这说明 context 不是越多越好。它是一种有限资源，而且会有边际收益递减。
一个白话类比是人的 working memory。人可以看很多资料，但当眼前同时摆着太多内容时，注意力会被稀释。LLM 也有类似的 attention budget。每增加一个 token，都在占用模型的注意力预算。
这个问题来自 transformer 架构本身。理论上，每个 token 都可以 attend 到其他 token。n 个 token 之间会形成 n² 级别的两两关系。上下文越长，模型越难稳定捕捉这些关系。Context size 和 attention focus 之间天然存在张力。
还有训练数据分布的问题。模型在训练中见到的短序列更多，对长距离依赖的经验和专门参数相对更少。position encoding interpolation 可以帮助模型处理更长序列，但 token 位置理解也会出现退化。
这不是一个突然断崖式的问题，而是一个 performance gradient。模型在长上下文里仍然有能力，但检索精度和长距离推理能力通常不如短上下文。
所以，能不能把相关、清晰、高信号的信息放进上下文，直接影响 Agent 能否稳定工作。
有效 context 的组成
Anthropic 给出的总原则是：
找到最小的 possible set of high-signal tokens，以最大化期望结果出现的概率。
这个原则贯穿 system prompts、tools、examples、message history 等所有内容。
1. System prompts：要具体，但不能写成脆弱程序
System prompt 应该非常清楚，用简单直接的语言，把想法放在合适的 altitude 上。
这里的 altitude，可以理解为“指导的抽象层级”。太低层，会像硬编码程序；太高层，又会变得空泛。
Anthropic 说 system prompt 有两个常见失败模式：
第一种是把复杂、脆弱的逻辑硬编码进 prompt，试图精确诱导 Agent 行为。比如写一堆 if-else 式规则，让模型在各种情况中机械匹配。这会让 prompt 变得难维护，也更容易在边界情况中失效。
第二种是 guidance 太高层、太模糊，缺少具体信号，或者错误假设模型已经和人类共享背景。比如只说“做得专业一点”“保持高质量”，但没有说明什么叫专业、什么叫高质量。
比较好的位置是 Goldilocks zone：具体到能引导行为，又灵活到能让模型自己处理相似情况。
在结构上，可以用清晰 section 组织 prompt，例如：
• <background_information>• <instructions>• ## Tool guidance• ## Output description
XML tags 和 Markdown headers 都可以。随着模型能力变强，具体格式可能会越来越不重要，但清晰结构仍然能帮助模型理解不同信息的作用。
这里的 minimal 不等于 short。目标不是写得短，而是只放入完整描述期望行为所需的信息。
实际调 prompt 时，Anthropic 建议先用最小 prompt 加最好的模型测试，再根据失败模式加入明确指令和例子。
2. Tools：工具定义是 Agent 和外部世界的 contract
工具让 Agent 能和环境交互，也会把新 context 拉回模型。
一个工具定义，实际上是 Agent 与信息/行动空间之间的 contract。它告诉模型：这个工具能做什么、输入是什么、输出是什么、什么时候应该用。
好的工具应该促进效率。这里有两层意思：
第一，工具返回的信息要 token efficient。它不应该把大量无关内容塞回 context。
第二，工具设计本身要鼓励 Agent 高效行动。模型应该容易判断该不该用这个工具、怎样传参数、返回结果该怎样解释。
Anthropic 把好工具类比成好代码库里的函数：自包含、错误鲁棒、用途清楚、功能边界明确。
Input parameters 要描述清楚，避免含糊。参数设计要发挥模型的强项，而不是让模型在一堆模糊选项之间猜。
常见失败是 bloated tool sets：工具太多，功能重叠太多，决策点模糊。如果人类工程师都说不清什么时候该用哪个工具，AI Agent 更不可能稳定做得更好。
因此，工具集也要策划。给 Agent 最小可用工具集，有助于长交互中的 context 维护和剪枝。
3. Examples：少量高质量例子仍然很有效
Few-shot prompting 仍然值得使用。
但 Anthropic 不建议把大量边界情况塞进 prompt，试图列出所有规则。这样会让 context 变重，也会让模型在长任务里被局部规则牵着走。
更好的方式是选择 diverse、canonical examples。也就是挑不同类型、足够典型的例子，清楚展示期望行为。
对 LLM 来说，examples 有点像“pictures worth a thousand words”。一个好例子能比一大段抽象说明更快地传达行为模式。
Context retrieval 和 agentic search
Anthropic 之前在 Building effective AI agents 中区分过 workflow 和 agent。这里文章用了一个更简单的定义：Agent 是 LLM autonomously using tools in a loop。
模型越强，Agent 可以被赋予越多自主性。它可以更独立地处理细微问题空间和错误恢复。
过去很多 AI-native 应用会使用 embedding-based retrieval：在模型推理之前，从外部知识库里检索相关内容，放进 context。
现在，方向正在从“预先把所有相关数据准备好”，转向 just-in-time context。
做法是：Agent 维护轻量引用，而不是把完整对象放进上下文。轻量引用可以是：
• file paths • stored queries • web links • 数据库查询入口 • 其他可按需展开的线索
运行时，Agent 再用工具动态加载需要的数据。
Claude Code 就用了类似方法。在大数据库上做复杂数据分析时，模型不需要把完整数据库放进 context。它可以写定向 query，把结果存下来，再用 Bash 的 head、tail 等命令查看数据形态。
这和人类工作方式很像。人不会把所有语料都记在脑子里，而是依靠文件系统、收件箱、书签、笔记和索引系统，在需要时找到相关信息。
轻量引用本身也有信息价值。比如同名 test_utils.py：
• 如果它在 tests文件夹里，很可能是测试辅助代码。• 如果它在 src/core_logic/里，它的用途可能完全不同。
层级、命名、时间戳，都会给人和 Agent 提供行为信号，帮助判断信息应该如何使用、什么时候使用。
这种自主导航和检索，也支持 progressive disclosure。Agent 可以通过探索逐步发现相关 context：
• 文件大小暗示复杂度。 • 文件命名暗示用途。 • 时间戳可以作为相关性的 proxy。 • Agent 可以 layer by layer 建立理解。 • 必要时用 note-taking 把额外状态持久化。
这样，Agent 不会一开始就被大量“可能相关但未必相关”的信息淹没，而是先维持必要 working memory，再按需扩展。
代价是速度。Runtime exploration 通常比预先检索慢。
它也要求工程设计更有主见：要给 LLM 合适的工具和 heuristics，让它能导航信息 landscape。否则 Agent 会误用工具、追 dead ends、错过关键信息，反而浪费 context。
所以 Anthropic 推荐 hybrid strategy。某些任务适合一部分 upfront retrieval 加速，另一部分交给 Agent 自主探索。
Claude Code 就是混合模式：CLAUDE.md 会预先放入 context，作为项目指导；同时用 glob、grep 等 primitives 在运行时查找文件。这样可以绕过 stale indexing 和复杂 syntax trees 带来的问题。
法律、金融这类内容变化较少的场景，可能更适合混合策略。
总体建议仍然是：do the simplest thing that works。模型越强，agentic design 会更倾向于让智能模型自主探索，减少人类预先策划。但不是每个场景都需要一开始就给 Agent 最大自主权。
面向长任务的 context engineering
长任务的问题更难。
如果一个 Agent 要执行超过 context window 的 action sequence，它就需要在很长时间里保持 coherence、context 和 goal-directed behavior。
大型代码迁移、综合研究这类任务，可能持续几十分钟到数小时。它们需要特殊技术绕过 context window 限制。
等更大的 context window 看起来像一个直接解法，但 Anthropic 提醒：无论未来窗口有多大，context pollution 和 relevance 问题仍然会存在。尤其在需要最强 Agent performance 的地方，仍然要管理 context。
文章介绍了三种技术：
• compaction • structured note-taking • sub-agent architectures
1. Compaction：接近上限时，把历史压缩成新上下文
Compaction 是当 conversation 接近 context limit 时，总结内容，并用 summary 重新初始化新的 context window。
这是提升长期 coherence 的第一 lever。
它的核心是高保真压缩 context window 内容，让 Agent 以最小性能损失继续任务。
Claude Code 中的做法是：把 message history 交给模型做总结压缩，保留架构决策、未解决 bug、实现细节，丢弃重复 tool outputs 和 messages。然后 Agent 用压缩 context 加最近访问的 5 个文件继续工作。
Compaction 的难点是选择保留什么、丢弃什么。太激进会丢掉一些当下看起来不重要、后来才显示重要性的 subtle context。
工程上，Anthropic 建议用复杂 Agent traces 来调 compaction prompt。先 maximize recall，捕获每个相关信息；再迭代提高 precision，去除多余内容。
比较容易清理的内容，是很早之前的 tool calls 和 tool results。工具调用结果如果已经在历史深处，Agent 通常不再需要原始输出。
一种安全、轻量的 compaction 形式是 tool result clearing。Claude Developer Platform 最近也把它作为功能推出。
2. Structured note-taking：把长期记忆写到 context 外面
Structured note-taking，也可以叫 agentic memory，是让 Agent 定期把 notes 写到 context window 外部的持久存储里，之后需要时再拉回 context。
它用较小 overhead 提供 persistent memory。
比如 Claude Code 会创建 todo list。自定义 Agent 也可以维护一个 NOTES.md。这些笔记帮助 Agent 在复杂任务中跟踪进度、关键 context 和依赖，避免几十次 tool calls 后丢失方向。
Anthropic 举了 Claude playing Pokémon 的例子。Agent 在几千步中维护精确计数，比如训练 Pikachu 走了 1234 步；还会在没有额外提示的情况下开发地图、记录成就、维护战斗策略，并知道不同攻击对不同对手的效果。
当 context reset 后，Agent 读取自己之前写下的 notes，就能继续多小时的训练和 dungeon exploration。
Sonnet 4.5 发布时，Anthropic 在 Claude Developer Platform 推出了 public beta memory tool。它用文件系统方式存储和查询 context window 外的信息，让 Agent 能积累知识库、维护跨 session 的 project state、引用旧工作，而不需要把一切都放进 context。
3. Sub-agent architectures：把大任务拆给干净上下文的小 Agent
Sub-agent architecture 是另一种绕过 context limitation 的方式。
它不是让一个 Agent 维持整个项目状态，而是让专门的 sub-agent 处理 focused tasks 和 clean context windows。
Main agent 负责 high-level plan。Subagents 负责深度技术工作，或者用工具寻找信息。
每个 subagent 可以消耗数万 tokens 做探索，但只返回 condensed、distilled summary，通常是 1000 到 2000 tokens。
这种方式的优势是 separation of concerns。详细 search context 被隔离在 sub-agent 内部，lead agent 可以专注综合各路结果，而不是把所有搜索过程都背在一个上下文里。
Anthropic 在多智能体研究系统文章中提到，这种模式在复杂研究任务上相比单 Agent 有显著提升。
三种方法的选择可以这样理解：
• Compaction：适合需要大量 back-and-forth 的任务，可以保持 conversational flow。 • Note-taking：适合有清晰 milestones 的 iterative development。 • Sub-agent：适合复杂 research and analysis，尤其当 parallel exploration 有价值时。
即使模型继续进步，长交互 coherence 仍然会是构建有效 Agent 的核心挑战。
这篇文章最后的结论
Context engineering 代表的是用 LLM 构建系统方式的变化。
模型更强之后，挑战不只是 crafting perfect prompt，而是在每一步 thoughtful curate 进入有限 attention budget 的信息。
无论是 compaction、token-efficient tools，还是 just-in-time exploration，背后的原则都是同一个：
找到最小的一组高信号 token，让期望结果最有可能发生。
技术会继续演进。更聪明的模型需要更少 prescriptive engineering，也能承担更多自主探索。但 context 作为 precious finite resource，仍然会是可靠、有效 Agent 的核心。
关键术语说明
• Context：模型在一次推理中能看到的 token 集合，包括指令、工具、外部数据、历史消息和中间结果。 • Context engineering：选择、组织、压缩和维护 context 的工程方法，目标是让模型在有限注意力预算内稳定完成任务。 • Prompt engineering：主要围绕提示词和指令设计的工程方法，是 context engineering 的一部分。 • Context rot：上下文变长后，模型准确使用其中信息的能力下降。 • Attention budget：模型处理上下文时有限的注意力资源。 • Just-in-time context：不预先加载所有资料，而是在运行时按需检索和展开。 • Progressive disclosure：逐层展开信息，让 Agent 先看必要线索，再按需要深入。 • Compaction：把接近上限的历史上下文压缩成摘要，用于继续任务。 • Structured note-taking：让 Agent 把长期状态写到上下文窗口外部的持久笔记里。 • Sub-agent architecture：用多个专门 Agent 处理子任务，主 Agent 只接收压缩后的结果。
使用场景和注意点
这篇文章最适合用在三类场景：
第一，正在做 Agent 产品或内部工具，需要设计 system prompt、工具集、历史消息和外部数据加载方式。
第二，正在用 Claude Code、Codex 这类编码 Agent，希望理解为什么它们会读文件、搜索、做笔记、压缩历史，而不是一次性加载整个仓库。
第三，正在做长任务 Agent，比如研究、代码迁移、数据分析、运营自动化，需要让 Agent 在几十分钟甚至更长时间里保持方向。
实际使用时要注意：不要把 context engineering 理解成“塞更多信息”。它更像信息整理和筛选。真正关键的是高信号、低噪声、可检索、可压缩、可恢复。
可复习要点
1. Prompt engineering 是 context engineering 的一部分；Agent 场景里，完整 context state 比单段 prompt 更重要。 2. Context 是有限资源，长上下文会带来 attention 分散和 context rot。 3. 有效 context 的原则是：最小的一组高信号 token。 4. 工具设计会直接影响 context 质量；工具集越臃肿，Agent 越容易误用。 5. 长任务需要 compaction、structured note-taking 和 sub-agent architectures 来维持 coherence。
