上下文工程：管理 AI 能看到什么

AI 不是不知道，很多时候是没看到。上下文工程，就是决定 AI 在每次推理时看到什么、不看到什么。

需求篇产出了GMV 清洗迁移链路的规格。但如果这份规格只存在于一次聊天里，下一个会话、下一个 agent、下一个任务又会从零开始。上下文工程解决的就是这个问题：让项目约束成为 AI 的长期事实，而不是每次重新粘贴的运气。

一、反例：AI 不知道这是遗留逻辑迁移

你对 AI 说：

把这段 GMV SQL 改写成 Java Service。

如果 AI 只看到这句话，它很可能把 SQL 逐句翻译成 Mapper 和循环。代码能运行，但它不知道这段 SQL 只是九个平台之一，不知道预览模式不能写库，也不知道任一平台失败后禁止刷新完整汇总。

问题不在这句话写得不好，而在 AI 没看到旧文档、任务定义、调用关系、平台口径矩阵、执行器契约和汇总门禁。缺上下文时，模型只能按默认场景回答——这是认知篇机制的又一次显形。

二、从 prompt engineering 到 context engineering

2025 年前后，业内的注意力发生了一次明确的迁移：从"怎么措辞"（prompt engineering）转向"给模型看什么"（context engineering）。Karpathy 给后者的定义被广泛引用——为下一步推理，在上下文窗口里装配恰到好处的信息的艺术与科学。Anthropic 的工程实践总结则给出了更工程化的目标：找到最小的高信号 token 集合（the smallest possible set of high-signal tokens）。

注意两个定义共同强调的方向：不是"更多"，是"恰到好处"和"最小"。这背后有实证依据——上下文不是免费的仓库，而是稀缺的注意力预算：

• Lost in the Middle（Liu et al., 2023）：当关键信息位于长上下文中部时，模型的利用率显著下降，呈两头高、中间低的 U 型曲线。塞进去不等于被看到。
• Context Rot（Chroma, 2025）：对 18 个主流模型的测量显示，即使任务难度不变，仅仅增加输入长度就会让表现下降且愈发不稳定。上下文越长，单位信息的效用越低。

所以上下文工程的第一原则不是"把所有文件都给 AI"，而是：

在正确的时机，让正确的信息出现在窗口里；同样重要的是，让不相关的信息不出现。

三、四层信息架构：按变化频率分层

把项目信息按"变化频率 × 使用时机"分成四层，每层有对应的机制：

层	内容	变化频率	载体机制
① 常驻规则	技术栈、部署形态、硬性约束、禁改清单	极低	CLAUDE.md / Cursor rules 等规则文件，自动加载
② 决策记忆	关键决策及其理由（“为什么总控不放平台特例”）	低	ADR / 项目 memory
③ 按需检索	代码细节、调用链、表结构现状	随代码变化	代码索引、语义搜索、调用链分析
④ 任务注入	本次任务的规格、边界、验收标准	每任务一份	Agent 工作单

分层的逻辑：变化频率越低的信息越值得常驻，变化频率越高的信息越应该按需获取。 把易变的代码细节写进常驻规则，规则会立刻过时；把不变的部署形态依赖每次手动粘贴，则每次都在赌记忆。

落到GMV 清洗迁移链路上：

① 常驻规则（写进 CLAUDE.md）：

本项目把旧的生态店铺 GMV 清洗逻辑迁移为 Spring Boot 链路。
总控只负责编排，不直接依赖平台 Mapper，也不承载平台特殊口径。
save=false 禁止删除、写入和刷新汇总；save=true 只能写白名单目标表。
任一平台失败都不能刷新完整汇总。
AI 实现平台前必须引用已确认的口径证据并输出验收用例。

② 决策记忆（写进 ADR）：

决策：总控通过统一 PlatformExecutor 契约选择九个平台。
理由：平台销售、退款、日期与字段差异变化方向不同，应收敛在各平台模块；总控只保留稳定编排语义。
被否方案：在总控中按平台写大段 if-else，或把所有平台揉成一套大一统 SQL。

代码只能告诉 AI"现在是怎么写的"，决策记录才能告诉它"为什么不能随便改"。没有理由的约束在长会话里最先被牺牲。

③ 按需检索：让 AI 能查“总控入口在哪里、某平台执行器调用哪些 Mapper、汇总刷新由谁触发、改结果 DTO 影响哪些接口”，而不是把整个仓库粘进窗口。

④ 任务注入：每次任务只带本次相关的规格、契约、边界和验收标准——格式即执行篇的 Agent 工作单。

四、上下文的四类失效模式

上下文不仅会缺失，还会出错。业内对长上下文失效的总结可以归为四类，每类都有对应的工程处置：

失效模式	表现	处置
污染（poisoning）	早期的错误假设或幻觉进入上下文，被后续推理当成事实反复引用	发现错误假设立即开新会话，而不是在原会话里纠正——纠正的痕迹本身还留在窗口里
稀释（distraction）	大量无关内容摊薄注意力，模型开始忽视真正的约束	按需检索代替全量粘贴；任务注入只带本次所需
混淆（confusion)	相似但过时的信息（旧版规格、废弃接口）与现行信息并存	规格单一事实源：改规格文件，不在聊天里口头改
冲突（clash）	常驻规则、任务指令、历史对话互相矛盾	分层之间定义优先级；规则文件定期 review 去矛盾

第一类值得展开：这正是执行篇里"review 必须换上下文"的同一机制——被污染的上下文里，错误和审查者共享前提。

五、例子：同一句修复请求，两种结果

没有上下文工程：

把这段 GMV SQL 改写成 Java Service。
→ AI 逐句翻译，但把平台特例写进总控，也没有预览与失败边界

有上下文工程（常驻规则已声明多实例 + 编号分布式安全）：

按已确认的平台口径矩阵迁移当前平台执行器，并说明影响面。
→ AI 复用 PlatformExecutor 契约，只修改当前平台 service / mapper / test，
  同时验证 preview 无副作用、异常按契约返回且不刷新完整汇总

第二次提问甚至更短。差别不在提问技巧，在 AI 看到了什么——这就是"context engineering 的杠杆大于 prompt engineering"的具体含义。

六、维护成本：规则文件也会腐烂

上下文工程不是一次性投入，它有一个常被忽略的失效路径：规则文件本身的腐烂。

• 规则越积越多，常驻层膨胀，自己成为稀释源——规则文件同样要遵守"最小高信号"原则；
• 项目演进后旧规则失真（服务拆分了、约定改了），失真的规则比没有规则更危险，因为 AI 会认真执行它；
• 谁都往里加、没人删，最后互相矛盾（冲突模式的典型来源）。

处置方式是把规则文件当代码对待：进版本库、走 review、定期清理。一个实用的判据——每条常驻规则都应该能回答"删掉它，最近一个月内哪个任务会做错？" 答不上来的规则就该降级或删除。

七、本章小结

• 上下文工程管理的是"AI 每次推理时看到什么"；实证研究（Lost in the Middle、Context Rot）表明上下文是稀缺的注意力预算，目标是最小高信号集合，不是最大信息量。
• 四层架构按变化频率分层：常驻规则、决策记忆、按需检索、任务注入——越不变的越常驻，越易变的越按需。
• 决策要连同理由一起沉淀（ADR），没有理由的约束最先被牺牲。
• 四类失效模式（污染、稀释、混淆、冲突）各有工程处置；污染是"review 必须换上下文"的机制根源。
• 规则文件当代码维护：每条规则要能回答"删掉它会出什么错"。

下一章 规格驱动开发，讲结构性决策如何先于实现被定下来、记录下来。

---

参考资料

• Anthropic, Effective Context Engineering for AI Agents（2025）——"最小高信号 token 集合"的工程目标与实践。
• Liu et al., Lost in the Middle: How Language Models Use Long Contexts（2023）——长上下文中部信息利用率显著下降的实证研究。
• Chroma, Context Rot: How Increasing Input Tokens Impacts LLM Performance（2025）——输入长度增加导致模型表现下降且不稳定的跨模型测量。