上下文工程实战：让 AI 智能体始终围绕任务行动

智能体在演示中表现正常，一到实际工作就跑偏？先检查模型到底收到了什么，再考虑追加指令。上下文工程要管好每一步进入模型的 5 类输入：指令、工具、检索到的事实、记忆和历史记录。目标是为下一步正确行动提供足够的依据，同时减少夹带的无关信息。

什么是上下文工程？

上下文工程，就是决定模型在做下一步决策时能看到哪些信息。 其中既有你写下的指令，也有模型可选的工具、工具返回的证据、载入的记忆，以及保留下来的对话。

模型的上下文窗口是处理一次请求时的工作空间。Token 是模型处理文本或其他内容的单位。一份文档即使保存在系统里，也只是可供使用的信息；只有应用或智能体加载了它，其中的内容才会进入当前上下文。

这个区别能解释生产环境中一种常见故障：智能体明明有权读取正确的政策文件，却仍依据旧对话作答，因为做决策的那一刻，最新政策根本没有进入模型。同样，把所有政策一股脑加载进来，也可能混入无关的例外条款和过时版本。

Anthropic 在 2025 年 9 月 29 日的工程博客中，将这项工作描述为**“在 LLM 推理过程中，筛选并维护最合适的一组 token（信息）”**。它区分的是编写指令与管理执行期间提供给模型的全部信息。Anthropic 的上下文工程文章。

LangChain 在 2025 年 7 月 2 日的文章中，将其描述为**“在智能体执行过程的每一步，为上下文窗口填入恰到好处的信息”**。它把这项工作归为写入、选择、压缩和隔离：保存有用的状态、获取相关材料、精简保留的内容，并把彼此独立的调查分开。LangChain 的上下文工程文章。

实际变化在于，你要设计的对象变了。一条提示词可以始终不变，但智能体每读一个文件、收到一次工具结果、完成一项子任务，或发现之前的假设有误，下一次请求就会变化。因此，你需要一套贯穿整个任务的请求组装策略。

文档核验日期：2026 年 10 月 13 日。 下文涉及的工具行为已对照当时的 Anthropic 和 OpenAI 文档核验。文中的完整示例用于说明设计思路，并非生产环境基准测试。

上下文工程与提示词工程有什么区别？

提示词工程优化指令，上下文工程优化围绕指令组织起来的整个请求。 两者都需要。

对于编程智能体，提示词工程可能是把“修复注册问题”改成“找出注册重试为什么会重复发送欢迎邮件，提出最小修复方案和回归测试”。上下文工程则负责决定：在提出修复方案前，智能体应该拿到哪些注册相关文件、重试日志、项目规则和已有调查结论。

指令写得再漂亮，也弥补不了加载了错误环境日志的问题。日志片段选得再精准，也弥补不了指令没说清楚究竟要诊断、修改还是部署的问题。

上下文工程的关键能力：划清信息边界

对每条信息，都要决定它何时进入上下文、何时可以离开。长期项目规则、临时任务状态和原始证据，不应采用同一种保留周期。

编码规范适合写进持久指令。“重试分支尚未测试”应放进当前任务的交接说明。服务提供方的完整响应则应保存在可访问的证据文件里，等其中某些字段会影响决策时，再加载这些字段。

这也解释了为什么检索增强生成（RAG）只是其中一环。RAG 为模型检索支撑材料，但指令、工具、保留的历史，以及检索结果中最终进入上下文的内容，仍然需要你来选择。

AI 智能体的上下文管理：从哪里下手？

先处理出错步骤中最大的无关信息来源。 不要一次引入所有机制。一个被日志淹没的调试智能体，与一个总是忘记项目约束的助手，需要不同的起手方案。

上下文压缩要保留决策状态，不能只剩话题摘要

Anthropic 的编程智能体 Claude Code 提供 /context 查看上下文用量，也提供 /compact 压缩对话。它的自动管理机制会先清理较早的工具输出，再在必要时总结对话。文档明确提醒：对话前面给出的详细指令可能丢失。Claude Code 上下文管理文档。

压缩时要说明保留什么。排查欢迎邮件问题时，可以使用 /compact Preserve the current goal, change boundaries, relevant file paths, observed evidence, failed hypotheses, and the next unresolved question. 这条命令给出了针对当前任务的保留要求，并不保证所有细节都能留下。

继续之前，检查摘要是否仍区分已观察到的事实、推断和尚未检查的内容。“已调查邮件重试”只是一个话题标签；“已知服务提供方接受了请求，本地确认路径仍待检查”才是能指导下一步行动的状态。

压缩必然有损。应保留原始证据的访问路径，并把长期规则写进项目指令，让后续步骤能重新取回所需细节。

需要证据时再检索

先获取能回答下一个问题的来源，结果不足时再扩大搜索范围。Anthropic 的工程文章将这种方式描述为：保留轻量引用，需要时通过工具加载信息。按需加载上下文。

Claude Code 的文件读取和 shell 工具可以支持这种流程。让它先定位重试处理函数，读取该函数及其调用方，再查看对应的错误序列。如果启用了专用 Grep 工具，它可以只返回文件路径、匹配内容或数量，而不必返回整个文件。Claude Code 工具参考。

如果你在开发自己的智能体，工具结果应包含来源标识、相关片段，以及足以确定适用范围的元数据，例如环境、记录标识、版本或生效日期。后续工具调用可以再打开周边内容。

检索可能漏掉相关证据，因此要保留扩大搜索范围的规则。窄范围搜索没有结果时，应先调整范围或查询条件，再判断某个事实是否不存在。如果片段不足以确定某项例外是否适用，就加载它所在的完整小节。

工具结果进入对话前，先去掉冗余

返回下一步决策需要的结果，同时保留找回省略细节的方式。对于输出冗长的工具，Anthropic 建议使用过滤、分页、范围选择和截断，并在缩短结果时提供有用的后续指引。Anthropic 工具设计指南。

Claude Code 对成功执行但输出量很大的 shell 命令，就采用了这种具体做法：超过内联输出上限后，返回保存文件的路径和预览，让智能体在需要时搜索或读取该文件。文档对失败命令的处理另有说明，所以不能假定每段被截断的错误输出都有可找回原文的文件路径。Shell 输出处理说明。

对于排查注册问题的智能体，有用的日志结果应包括匹配事件、前一个操作、错误信息和来源位置。重复出现的正常请求可以留在日志文件中。错误码和事件标识必须原样保留；如果只概括成“某个地方超时了”，就可能抹掉决定修复方向的线索。

盲目截断可能删掉关键异常。应明确标示哪些内容被省略，并提供后续查询方式或文件引用。先删重复噪声，再考虑删减相互矛盾的证据。

用不继承主对话的子智能体独立调查

Claude Code 子智能体可以在独立的上下文窗口中完成范围明确的调查，再返回结果。非分叉子智能体根据自身定义和收到的任务，从空白上下文开始；对话分叉则继承主智能体的历史记录。两者都能隔离后续工作，但只有前者从一开始就拥有干净的上下文。子智能体与对话分叉。

委派任务时，可以这样写：“检查邮件重试路径，不要修改文件。返回相关路径、支持重复投递判断的证据、其他可能解释，以及下一步检查项。”应把执行者需要的约束直接写进任务，而不是假定它了解主对话。

返回内容要精简到便于使用：结论、证据引用和不确定性。如果执行者把全部阅读历史都返回，只是把膨胀的上下文又搬回了主对话。

子智能体会自行发起请求，也会消耗用量。如果任务说明遗漏了主智能体已经确定的结论，它们可能重复工作。只有当调查可以独立拆分、过程输出不必保留时，才适合委派。紧密关联的推理应放在一起。具体配置方式见 Claude Code 子智能体指南。

记忆文件只承担少量、稳定的职责

CLAUDE.md 是项目指令文件，不适合用来粘贴每次已完成的对话。Claude Code 还提供自动记忆，用于保存工作中学到的笔记。文档明确区分了这两者与强制配置：在记忆文件中写下禁止某项操作，并不等于从技术上阻止该操作。Claude Code 记忆文档。

小型产品团队可以把仓库专属规则、实际可用的构建与测试命令、修改边界，以及深入参考资料的入口放进常驻文件。临时调查状态则单独保存在任务笔记里。文件组织方式可参考 CLAUDE.md 团队记忆指南。

一个容易忽略的限制是：将长文档导入 CLAUDE.md，也会把其中的内容加载进来。把文字移到被导入的文件中，可能让组织方式更清晰，却未必减少当前上下文。只在仓库某些区域需要的指令，可以考虑文档介绍的按路径限定规则。对于可复用的工作流，Claude Code 技能通常先展示描述，调用时才加载完整指令。记忆导入与作用范围规则、技能加载机制。

持久文件既能保存有用知识，也能同样牢固地保留过时假设。应删除已解决的故障记录和已被替代的命令；对会变化的事实，记录来源或修订版本。会话、工作上下文与持久存储之间更完整的区别，见智能体记忆详解。

Claude Agent SDK 和 Codex 如何落实这些方法？

这些工具已经提供相应机制，但证据选择和任务边界仍由你的应用决定。 自动上下文管理无法替你判断，工作流漏检索了哪条业务事实。

Claude Agent SDK：把智能体循环接入应用

Claude Agent SDK 将 Claude Code 背后的工具、智能体循环和上下文管理能力带到 Python 与 TypeScript 应用中。需要把智能体嵌入自己运营的产品或自动化流程时，可以使用它。Agent SDK 概览。

当上下文窗口接近上限时，SDK 会自动压缩较早的历史记录，并发出 compact_boundary 系统事件。把这个事件与任务结果一起记录，就能识别哪些故障出现在摘要生成之后。SDK 中的非分叉子智能体将中间工作留在各自的对话内，只返回最终消息。SDK 智能体循环、SDK 子智能体。

项目指令的加载方式要明确。当前 query() 的默认选项会启用用户和项目来源。如果在 TypeScript 中指定 settingSources，或在 Python 中指定 setting_sources，需要加载项目指令时，就必须包含 project，才能载入项目的 CLAUDE.md；空数组会阻止它加载。这由设置来源控制，并不取决于是否选择了 claude_code 系统提示词预设。SDK 指令加载说明。

循环机制再完善，也仍然需要针对业务领域的检索策略。客服智能体依然需要你定义谁是当前客户、哪些政策适用，以及行动前必须取得哪些证据。

Codex：仓库指令与进行中的对话分开管理

OpenAI 的 Codex 会在开始工作前读取 AGENTS.md 指令。它会将全局指导与从仓库根目录到当前工作目录沿途的项目文件合并；后加载的指导优先，同一目录下则优先采用 AGENTS.override.md。Codex 项目指令说明。

可以利用这个层级，把通用构建规则放在根目录，把专用规则放在相关工作附近。Codex CLI 还提供 /compact 来总结可见对话，以及 /init 来创建指令文件的初始框架。在把生成的框架作为正式依据之前，先对照仓库实际情况检查。Codex 命令说明。

仓库指令文件不会自动记录正在进行的任务。应另行保存当前目标、已确认的发现、待完成的工作和证据位置。重启或压缩后，下一次请求应能取得这些任务状态，而不必重放整个调查过程。

上下文工程案例：给一个信息过载的智能体做减法

精简决策周围的材料，同时保留决策所依赖的信息。 假设有一个编程智能体，要排查注册重试后重复发送欢迎邮件的问题。下面的文件名和证据用于说明设计，并非来自已部署系统的实际结果。

它最初收到的材料十分臃肿：整本工程手册、大范围的仓库内容、无关服务的日志、此前所有调试对话，以及处理无关管理事务的工具。真正的任务要窄得多：找到重复发送路径、提出最小修改，并确定一个回归测试。数据库结构变更不在范围内。

1. 1

   保留当前任务和长期约束

   用当前目标和验收标准，替换对话记录中相互竞争的要求。让禁止修改数据库结构的限制始终可见。只提供本任务所需的仓库工具，不把无关管理工具的定义带入这次执行。将稳定的仓库约定移到合适的项目指令文件，临时观察结果留在任务笔记中。不要把整本手册放进会自动加载的导入文件。

2. 2

   用证据索引替代大批文件

   保留指向 signup-handler.ts、welcome-job.ts、重试测试和相关日志文件的引用。这些名称仅作示例。当处理函数和执行任务的代码能回答下一个问题时，再读取它们；需要时，再检查依赖。索引让证据触手可及，但不能代替实际阅读。

3. 3

   围绕故障筛选工具结果

   请求受影响的注册事件及其重试序列。假设这条示例记录显示：服务提供方接受了请求，随后缺少本地确认，又有一次尝试进入队列。保留这段序列、事件标识和来源位置。无关的成功请求留在原始日志中。第二次尝试是否真的完成投递，仍应标为未确定。

4. 4

   隔离范围明确的查找任务

   让一个非分叉子智能体查找防止重复发送的逻辑实现在哪里。提供任务范围和相关路径，要求返回位置与证据；如果搜索不完整，也要明确说明。将查找结论交回主智能体，探索过程中的读取内容则留在子智能体一侧。

5. 5

   把调查过程压缩成可用的交接说明

   保留当前目标、已知证据、已排除的解释、尚未解决的问题和下一步行动。务必区分重试已入队与重复投递已确认。归档原始对话，让智能体可以找回细节，而不是凭空猜测。

6. 6

   用保留下来的信息组装下一次请求

   加载任务、长期规则、相关处理函数片段、筛选后的事件序列和子智能体结论。下一步是检查确认路径与防重复发送路径，并提出回归测试。如果这个行动需要更多证据，就继续加载；不要习惯性地重新附上整个归档。

整理后的任务笔记可以这样写：

目标： 解释注册重试后欢迎邮件重复发送的原因，提出最小修复方案并配套回归测试。
约束： 不修改数据库结构。
证据： 选定的日志序列显示，服务提供方接受了请求，但缺少本地确认，随后又有一次尝试进入队列。保留事件引用和原始日志位置。
未知项： 队列中的重试是否完成投递，以及防重复发送逻辑在哪些位置生效。
下一步检查： 查看所引用的处理函数与任务执行代码中的确认路径和防重复发送路径。

这份假设性的笔记明确保留了不确定性。模型做诊断时，会同时收到笔记和对应的支撑片段。

最终缩小的是内容清单，这里并未声称 token 用量减少了多少。精确的 token 数取决于实际请求和分词器。开支是否降低、任务完成率是否提高，都需要测量；这个示例只说明哪些内容应删除、哪些应保留。

上下文工程交接模板

任务笔记可以采用以下字段，并填入本次执行中的真实证据：

• 目标与完成条件： 当前请求是什么，达到什么标准才算完成。
• 约束： 下一步必须遵守的边界。
• 已确认事实： 每项发现都附上来源位置，以及相关修订版本或适用范围。
• 不确定性： 哪些仍是推断，哪些存在矛盾，哪些尚未检查。
• 下一步行动： 接下来检查什么，到哪里获取所需证据。

发现变化时，要同步更新笔记。只追加新想法、从不修订旧内容，会在一个更小的文件里重现原来的问题。

上下文大小与成本，要分开核算

优化的是每项通过验收的任务所需的成本，而不是某一次请求的长度。 主对话缩短了，子智能体调用、检索请求或失败尝试却可能更多。

文档中的两项指令用量约定，说明了为什么必须看清单位。Codex 默认的项目文档合计上限为 32 KiB，也就是 32 × 1,024 = 32,768 字节。这是字节限制，不是 token 预算。Claude Code 建议每个 CLAUDE.md 保持在 少于 200 行；这是编写建议，不是上下文窗口的硬上限。两个数字都不能用来预测节省了多少成本。Codex 指令限制、Claude Code 编写建议。

对于生产工作流，应记录主智能体、子智能体、压缩、检索和重试的成本，再计算：

每项通过验收的任务成本 = 所有尝试的工作流总成本 ÷ 满足验收标准的任务数。

核算月度预算时，应把模型用量费用与工具、检索、存储和托管费用相加。上下文工程没有统一月费；如果不了解你的工作负载和适用的服务费率，也就无法给出有依据的美元节省金额。

缓存会让比较更复杂。OpenAI 的提示词缓存会复用渲染后相匹配的前缀。压缩可能改变这个前缀，导致请求虽然更短，缓存复用却更少。应尽可能保持可复用指令稳定，并比较改动前后的总成本。仅凭缓存命中率下降，不能认定优化失败。OpenAI 提示词缓存说明。

可以借助 GPT-6 提示词缓存诊断指南，区分前缀变化造成的问题与无关内容过多造成的问题。缓存能降低重复输入的处理成本，但不能判断这些输入是否应该出现在任务中。

上下文工程最佳实践：先改哪一处？

执行轨迹显示上下文出了问题时，再采取能解决它的最小改动。 执行轨迹记录了请求、工具调用与结果的顺序，也包括模型在每次决策前看到了什么。

对于开发者，先检查错误行动之前的那一步。缺少证据，就修复检索；证据被重复输出淹没，就过滤工具结果；先前讨论盖过了当前任务，就修正任务状态和交接说明；可独立拆分的调查挤满了主对话，就把它隔离出去。

对于运营者，先定义什么结果算通过验收，再保留有代表性的失败案例用于评估。在相同任务上，比较完成质量、无依据的断言、重试、延迟和总成本。每次只改一项上下文策略，才能解释结果为何变化。可以利用已有执行轨迹设计离线评估用例。

对于采购者，要问清楚：产品能否展示答案背后的上下文和工具结果？总结之后是否保留来源引用？能否控制持久指令？如果一个“记忆”功能无法让你看见实际加载了什么，就很难排查问题。

如果一个简短、边界明确的工作流已经可靠运行，先别急着增加机制。你可能只需要更清晰的指令或更有用的工具报错，未必需要记忆服务或一组子智能体。如果故障源于权限错误、应用逻辑损坏或源数据不可用，就直接解决这些原因；仅靠整理上下文无法修复它们。

上下文工程有哪些被夸大的说法？

更大的上下文窗口、更多记忆和更多智能体，说明容量增加了，并不能证明决策更好了。 真正该问的是：它们有没有帮助这个工作流把正确信息带到下一步？

“把所有东西都塞进提示词”省去了筛选，却引入了相互竞争的材料。“把所有东西都总结一遍”则可能筛得太狠，抹掉关键例外。“交给子智能体处理”只有在任务跨越这个边界时不会丢失关键决策信息，才有帮助。

最昂贵的误判，是把请求缩短当成系统已经得到验证。一个低成本但依据错误政策作答的智能体，答案依然是错的。好的上下文策略应该让答案更容易核验：决定行动的规则清楚可见，支撑证据有据可查，尚未解决的不确定性也被明确保留。

智能体总跑偏，开发者最关心的问题

智能体演示正常、上线就出错，上下文工程能解决吗？

它可以处理证据缺失、指令过时、工具输出过多和任务状态丢失等问题。先检查出错的那次请求。工具损坏、应用逻辑错误，或任务超出模型能力，都需要各自的修复办法。应根据有代表性的任务是否通过验收，判断改动有没有效果。

开始做上下文工程，必须先上向量数据库或多智能体框架吗？

不需要。先做好明确的项目指令、聚焦的文件或文档检索、有边界的工具结果，以及任务交接。确实需要语义搜索才能找到相关材料时，再引入语义搜索；独立调查能从分开的上下文中受益时，再引入子智能体。

怎么判断上下文是不是删得太多了？

检查下一步决策是否仍有适用规则、支撑证据、适用范围和重要例外。如果智能体必须猜测某个被删掉的事实，上下文就过于精简了。保留可检索的来源；片段无法回答问题时，就扩大阅读范围。

周一就能动手： 找出一次已有的失败执行，检查它第一次采取错误行动之前的请求。把其中内容标成长期指令、当前任务状态、此刻所需证据，或可以留在存储中的材料。做出对应的最小改动，再用同一组评估用例比较结果和工作流总成本。

订阅邮件通讯，获取构建和运营实用智能体的操作指南。