Effective Context Engineering for AI Agents（AI Agent 的有效上下文工程）
📄 来自 Claude 官方博客
- 原文标题
- Effective Context Engineering for AI Agents（AI Agent 的有效上下文工程）
- 原文链接
- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- 作者
- Anthropic Applied AI 团队（Prithvi Rajasekaran、Ethan Dixon、Carly Ryan、Jeremy Hadfield）
- 发布日期
- 2025-09-29
⚠️ 本页是原文的中文结构化整理笔记（保留架构、数据、案例、结论），并非逐字翻译。具体参数与功能名更新很快，落地前请点击上方链接核对原文。
🎯 一句话
上下文工程 = 决定在每一步给模型看什么。⭐ 它比提示词工程更根本，因为提示词只是上下文的一部分，而真正影响长任务表现的是整个上下文窗口里都装了什么、以什么顺序装的。
📑 本页目录
随着模型能力增强、Agent 交互周期变长，AI 工程的重心正从「提示词优化」转向「整个上下文窗口的战略管理」。上下文是有限资源，工程师必须精心筛选哪些 token 进入模型的「注意力预算」。
上下文工程 vs 提示词工程
- 提示词工程：为单次任务撰写指令
- 上下文工程：管理多轮交互中的完整状态——系统指令、工具、外部数据、消息历史的策划与维护
为什么重要：上下文腐烂（Context Rot）
- 大海捞针类基准研究表明：上下文窗口中 token 越多，模型准确召回信息的能力越差
- 架构原因：Transformer 需要计算 n 个 token 之间 n² 的两两关系；训练数据中长序列更少；位置编码插值带来性能梯度式下降
- 类比人类有限的工作记忆：LLM 有一个随 token 增加而消耗的「注意力预算」
有效上下文的构成
系统提示词的校准
在两个极端之间找「刚好」的区间： - 过度规定式的硬编码逻辑 → 脆弱、维护成本高 - 过于含糊的指导 → 缺乏具体行为信号 - 最佳实践：用 XML 标签或 Markdown 标题分节；追求「完整刻画预期行为的最少信息」；先在强模型上用最小提示词测试，再针对失败模式补充指令
工具设计
- 自包含、抗错误、用途明确、无功能重叠、返回信息省 token
- 常见失败：臃肿的工具集覆盖太多功能，造成决策点模糊
Few-shot 示例
- 不要穷举边界情况，而是策划一组多样化、有代表性的典型示例
- 「对 LLM 来说，示例就是『一图胜千言』里的图」
检索策略：即时（Just-in-Time）上下文
- 从「预处理所有数据」转向「维护轻量级标识符（文件路径、查询、URL），运行时按需加载」
- Claude Code 的例子：写针对性查询、存储结果、用 head/tail 分析大数据而不把完整数据对象载入上下文
- 元数据（目录层级、命名约定、时间戳）为 Agent 提供隐式信号
- 渐进式披露：Agent 通过探索逐步发现相关上下文
- 混合策略：CLAUDE.md 预加载 + glob/grep 即时检索
长周期任务的三种技术
1. 压缩（Compaction）
- 接近上下文上限时总结对话内容，用压缩摘要重新开始
- Claude Code 的实现：保留架构决策、未解决的 bug、实现细节，丢弃冗余的工具输出
- 平衡点：过度压缩会丢失后期才显现重要性的细节；先追求最大召回，再改进精度
- 最安全的轻量压缩：清除旧的工具结果（tool result clearing）
2. 结构化笔记（Structured Note-Taking）
- Agent 定期把笔记写到上下文之外持久化，之后再取回
- 例子：Claude 玩宝可梦时跨数千步游戏维护精确计数，上下文重置后读笔记继续多小时的连续任务
- 平台支持：memory 工具（公测）
3. 子 Agent 架构（Sub-Agent Architectures）
- 专门化子 Agent 用干净的上下文处理聚焦任务，主 Agent 负责协调综合
- 子 Agent 探索时可能消耗数万 token，但只返回 1,000–2,000 token 的浓缩摘要
- 实现关注点分离：详细的搜索上下文隔离在子 Agent 内
技术选型
- 压缩：适合需要大量来回对话的场景
- 笔记：适合有清晰里程碑的迭代式开发
- 多 Agent：适合复杂研究和可并行探索的分析
关键概念速查
| 概念 | 定义 |
|---|---|
| Context Rot | 上下文 token 增加导致的召回性能退化 |
| 注意力预算 | 模型处理大量上下文的有限能力 |
| Just-in-Time 上下文 | 运行时通过工具按需加载数据 |
| 渐进式披露 | Agent 通过探索逐步发现相关上下文 |
| Compaction | 总结历史并用摘要重启 |
| 结构化笔记 | Agent 自建的外部持久化记忆 |
结论
指导原则：「找到能最大化预期结果概率的最小高信号 token 集合」。模型越智能，所需的规定性工程越少、自主性越高；但把上下文当作宝贵有限资源来对待，将始终是构建可靠 Agent 的核心。实践建议：「做能起作用的最简单的事」。
✅ 检查点
- 上下文工程和提示词工程的区别是什么？
- 什么是「上下文腐烂」（context rot）？
- 既然上下文窗口越来越大，为什么还要精心管理？
- 实践中有哪些具体的上下文管理手段？
👀 答案
- 提示词工程关注「怎么把一次请求说清楚」；上下文工程关注「在整个任务过程中，每一步该让模型看到什么」。⭐ 提示词是上下文的一个子集——还有工具定义、历史消息、检索结果、工具返回值，它们加起来往往远超提示词本身。
- ⭐ 上下文越长，模型对其中任一部分的注意力越稀释、越容易忽略中间的信息。表现为：塞了很多资料，模型却只用到开头和结尾的；或者早期的重要约束在几十轮之后被「忘记」。
- 因为窗口大小和有效利用是两回事。⭐ 三个理由：①注意力稀释（上下文腐烂）；②成本和延迟随长度上升；③无关信息会主动干扰决策——模型看到不相关的工具或资料时，有一定概率去用它们。「能装下」不等于「装了有好处」。
- ①压缩/摘要（把旧轮次浓缩成要点）②外置记忆（写进文件，需要时再读回）③按需加载（Skills 的渐进式披露、工具搜索）④结构化排布（把稳定内容放前面以利用缓存，把最关键的约束放在靠近末尾处）⑤子 Agent 隔离（让子任务在自己的上下文里跑完，只回传结论）。
🛑 可以停在这里
⚡ 走神救援
⭐⭐上下文工程 = 决定在每一步给模型看什么，比提示词工程更根本——提示词只是上下文的子集，还有工具定义、历史消息、检索结果、工具返回值，加起来远超提示词本身。⭐上下文腐烂：上下文越长，模型对其中任一部分的注意力越稀释、越容易忽略中间信息。窗口大 ≠ 该装满，三个理由：注意力稀释、成本和延迟上升、无关信息会主动干扰决策（模型看到不相关的工具有概率去用）。五种管理手段：压缩摘要、外置记忆（写文件需要时读回）、按需加载（Skills 渐进式披露/工具搜索）、结构化排布（稳定内容放前面利用缓存，关键约束放靠近末尾）、子 Agent 隔离（子任务在自己上下文里跑完，只回传结论）。