上下文翻车案例集

系列入口：如何使用 Agent。本篇是 M3 上下文工程模块的收尾。

一、为什么要按「类型」记案例

上下文导致的错误五花八门，但归归类，绝大多数落在四种模式：污染、过期、冲突、缺失。把症状和类型对应起来，你就能从「它怎么又错了」的茫然，变成快速定位「哦这是上下文冲突，我去查规则」。下面逐类看。

二、污染：无关信息混进来了

案例：让它改支付模块，结果它用了订单模块里的一套相似但不同的约定——因为它之前为别的任务读过订单模块，那套信息还留在上下文里，干扰了判断。

信号：它的方案里冒出与当前任务无关的概念、文件、风格；改着改着「串味」到别的模块。

排查与修复：检查窗口里是否残留无关背景；及时清理、开新会话或明确声明「忽略之前关于 X 的内容，以 Y 为准」；下任务时划清边界。

污染之所以隐蔽，是因为它读的信息往往「看起来相关」——同项目、同领域、命名相似，模型很难自动分辨哪些对当前任务有效。一个更完整的例子：你在同一个会话里先让它研究了订单模块的错误处理风格（用错误码 + 不抛异常），紧接着让它改支付模块，而支付模块的约定其实是抛领域异常。它带着前一个任务的背景，把支付也写成了错误码风格，单看代码毫无破绽，却破坏了支付模块的一致性。

修复这类问题，光说「注意点」不够，几个更可靠的动作：尽量一个会话聚焦一个任务，任务切换就新开；切换时显式声明作用域（「现在开始只处理支付模块，忽略之前订单模块的风格，以支付现有约定为准」）；并让它动手前先复述「这个模块现有的约定是什么」，把错误背景在执行前暴露出来。污染的本质是「信号串台」，靠隔离和显式重置来治，而不是期待它自己分清。

三、过期：它用的是旧信息

案例：一个接口上周改过签名，但长会话里 Agent 还在用对话早期的旧签名；或者规则文件更新了，已经开着的会话没感知到，仍按旧规矩办。

信号：它引用的写法、文件路径、约定，和当前代码对不上；改动基于「以前是这样」。

排查与修复：让它重新读一遍当前文件而不是依赖记忆；规则更新后开新会话让其重新加载；长任务里对「事实类」信息保持警惕，必要时让它先确认现状。

过期问题最典型的陷阱是「它说得非常肯定」。因为模型读到的旧信息在当时确实正确，它没有理由怀疑，于是会自信地基于过时事实作答。一个完整例子：某会话早期读过配置，当时超时设为 30 秒；之后另一位同事把它改成了 10 秒并提交。会话里的 Agent 并不知道文件已变，后面分析超时问题时一直按 30 秒推断，得出错误结论，而且语气笃定。

这类问题的关键认知是：上下文里的信息是某个时间点的快照，不代表当前真实状态。 尤其在多人协作、文件可能随时变化时，对「事实类、且改动可能影响结论」的信息，要让它在关键决策前重新读取确认，而不是沿用会话早期的版本。一个好习惯是区分两类信息：相对稳定的约定可以沿用，而易变的事实（配置值、接口签名、文件路径）在使用前重读。规则文件更新后，旧会话通常不会自动重新加载，开新会话让它重新读取，比指望它「发现规则变了」更可靠。你也可以让它在引用某事实时说明「这是基于哪个文件、何时读的」，便于判断是否需要重新确认。

四、冲突：多份信息互相矛盾

案例：全局规则写「用双引号」，项目规则写「用单引号」；或者 CLAUDE.md 和某个目录规则对同一件事说法相反。Agent 在矛盾前可能随机挑一个，或行为不稳定。

信号：同样的要求，它有时这样做、有时那样做；它明确表示「规则有冲突」或表现出摇摆。

排查与修复：搜出所有涉及该点的规则文件，对齐成一条；遵循具体层优先、同条约定只定义一次（见 规则分层组织）；暂时无法统一时，在任务里显式指定「本任务以 X 为准」。

冲突比污染更难自查，因为矛盾往往分散在不同文件、由不同人在不同时期写下。一个完整例子：全局规则里早期写了「代码注释用英文」，后来项目规则为照顾团队写了「关键业务注释用中文」，而目录层某个服务又写了「本服务注释一律英文」。三层说法不一，Agent 每次可能引用不同层级，导致同一仓库注释语言飘忽，review 时很难统一。

排查冲突最有效的办法，是针对一个具体争议点横向搜全部规则文件，而不是凭印象判断。可以用一个固定动作：当你发现它行为摇摆，先让它「列出它能看到的、关于这件事的所有规则及其来源文件」，矛盾往往立刻显形——模型其实能同时读到冲突条目，只是没人要求它摆出来。根本修复是把同一件事对齐成唯一定义，其他层引用；暂时无法统一的过渡期，在具体任务里显式指定以哪条为准，别让它在矛盾前自行选择。还要警惕「隐性冲突」：两条规则字面上不矛盾，但在某个具体场景里要求无法同时满足，这类只有在实际任务触发时才暴露，发现后同样应收口成一条或写明取舍优先级。

五、缺失：它根本没拿到关键信息

案例：它写出的功能违反了一条只存在于老员工脑子里、文档里没有的业务规则；或者改错文件，因为没人告诉它真正的逻辑在另一个文件。

信号：「它怎么连这个都不知道」——产出在技术上合理，却违背了你以为不言自明的东西。

排查与修复：把隐性规则显式写进规则/记忆文件；用 @引用把关键文件喂给它；复盘每一次「没想到它不知道」，都补一条上下文，避免重犯。

缺失是四类里最值得改变心态的一类。人容易把自己天天接触的背景当成「不言自明」，于是高估 Agent 的初始认知——它没有在你团队待过，那些「大家都知道」的事，对它来说根本不存在。一个完整例子：团队有条不成文规定，退款金额超过一千元必须走人工复核，这条只在口头和老员工经验里。你让它实现自动退款，它技术上做得完美、测试全绿，却把大额退款也全自动放行了——它不是疏忽，而是从不知道有这条规则，而你以为「这么重要的规定它总该想到」。

应对缺失，核心是把「隐性」持续转成「显性」。两个具体机制：一是每当出现一次「没想到它不知道」，就在收尾时把那条规则补进规则或记忆文件，让一次暴露永久生效；二是在进入一个业务复杂的模块前，主动梳理关键业务规则喂给它，而不是等它踩雷。还要纠正一个认知：模型不会因为「这事很重要」就自动推断出它不知道的规则——重要性是你的判断，信息是否提供才是它能依赖的全部。你认为再显然的事实，没进上下文就等于不存在。缺失类问题暴露时不要责怪它「怎么连这都不懂」，而应把它看作一条该被补进知识库的资产。

类型	一句话特征	首选修复
污染	带了无关背景	清理 / 开新会话
过期	用了旧事实	重新读取现状
冲突	规则自相矛盾	对齐成一条
缺失	关键信息没给	写规则 / @喂文件

六、一个通用排查顺序

下次 Agent 出错，可以按这个顺序想：它是不是读到了不该读的（污染）→ 它用的信息是不是过时了（过期）→ 我的规则有没有打架（冲突）→ 有没有什么我以为它知道其实没给（缺失）。 四步走完，绝大多数上下文问题都能现形。每修好一类，就把教训固化进规则文件——这正是让 Agent 越用越稳的积累方式。

实际执行这个排查时，建议让 Agent 自己参与而不是你独自翻记录。可以直接发一个统一的诊断指令：「先不要继续改。请基于当前上下文回答：你正在使用哪些关键信息、分别来自哪个文件或哪一轮、其中有没有可能过时或互相矛盾的、为了完成任务你是否还缺少什么。」这种让它把信息来源摊开的做法，能一次性把过期、冲突、缺失三类线索都暴露出来，比你逐个文件排查快得多。模型通常有能力识别这些问题，只是在没人要求时会默认继续推进。

还要记住一个原则：排查的目的是找到「信息层面的根因」，而不是急着让它再试一次。 当上下文本身有缺陷，立即重试大概率重现同样的错，这也是为什么空转和缺失常相伴出现——信息没补齐，尝试只是在重复。先把信息状态修对，再让它行动，顺序不要反。把「诊断信息流」放在「继续执行」之前，是这一节最核心的实操要点。

七、四类问题的快速诊断对照表

为了让你在 Agent 出错的现场能一分钟归类，把「观察点—典型台词/迹象—提问—动作」并排整理如下，跑任务时扫一眼即可：

类型	最先观察什么	典型迹象	你该问它的话	立即动作
污染	窗口里有没有别任务残留	突然冒出无关模块的概念/风格	「这些信息来自哪个任务？与当前模块有关吗」	隔离、显式重置、开新会话
过期	它引用的事实是否可能已变	用旧签名、旧路径且语气肯定	「这是基于哪个文件、何时读的，现在重读一次」	重新读取、新会话重载
冲突	同一争议点有多份规则	行为摇摆、它主动提到规则矛盾	「列出关于此事的全部规则及来源」	对齐成唯一定义
缺失	关键背景是否从未提供	技术合理却违背隐性业务规则	「做这件事还需要知道哪些规则/文件」	写规则、@喂文件

这张表的价值，是把排查从「凭感觉乱试」变成「按列对照」。尤其对新手，你不需要先成为专家，只要判断信息在窗口里的状态，就能定位方向。

再给一个判断优先级的小经验：当问题现象很乱、一时分不清是哪类时，先排「缺失」和「过期」，因为这两类最常见、且补齐/重读后往往立竿见影；再看冲突；最后处理污染。这不是绝对顺序，而是一个能快速见效的排查路径。很多看似复杂的错误，其实只是它没读到某个文件、或沿用了旧事实，一两步就能解决，不必一上来就怀疑模型整体不行。

八、如何防止同一类问题反复发生

这四类问题之所以值得专门总结，是因为它们都很「规律」——不是随机失误，而是可以靠机制预防的模式。防止复发的关键，是把每次排查的结论沉淀成对的地方：

• 暴露的是硬约定（以后每次都要守）→ 写进 rules；
• 暴露的是项目事实或背景（知道即可）→ 写进 memory；
• 暴露的是不能违反、需要强制的红线 → 用钩子硬性拦截；
• 暴露的是某个「怎么做」的流程缺口 → 沉淀成 Skill。

这样每踩一次坑，系统就多长一道防线，而不是只靠你下次记得小心。一个实用的收尾习惯：任务复盘时问一句「这次错误属于四类里的哪一类、根因信息现在落在哪、下次它还会不会再犯」。如果答案是「还会」，说明还没真正修复，只是把这次的问题处理掉了。把修复动作和知识资产绑定，Agent 才会随项目时间推移越来越稳，这也是整个上下文工程模块想达成的最终效果。

九、常见问题

Q：四类问题看起来有点重叠，实际怎么快速区分？ 抓住各自的根因：污染是「多了不该有的」，过期是「信息曾对但现在变了」，冲突是「同时存在互相矛盾的要求」，缺失是「压根没给」。先判断信息在窗口里的状态（多余、过时、矛盾、不存在），就能归类。

Q：我每次都要这样系统排查吗？会不会很累？ 简单任务凭经验很快，且随熟练度会变成直觉。真正值得完整走流程的是反复出错或影响较大的任务。把高频检查固化进规则和钩子后，需要你人工排查的情况会越来越少。

Q：有没有可能四类问题同时出现？ 有可能，尤其在很长、很混乱的会话里。这时最有效的做法往往不是逐个修补，而是回到一个干净状态、用一份清晰的状态/规则重新开始，成本反而更低。

Q：怎么判断错误到底是上下文问题还是模型能力问题？ 先做信息补齐实验：把该读的文件、该统一的规则、该给的事实都明确提供后再看。补齐后改善即上下文问题；信息完备仍做不到，再考虑能力边界。这个顺序能避免误判。

总结

上下文翻车逃不出污染、过期、冲突、缺失四类：无关的清掉、过时的重读、矛盾的对齐、缺的补上——再把每次教训写进规则，你的 Agent 就会在这个项目里越来越少犯同类错误。