1. context-mode 到底解决什么问题，为什么我现在离不开它
先讲一个我自己的翻车现场。今年年初我接了一个订单模块的重构任务，开了一个很长的 AI 辅助编程会话，把项目 README、历史设计文档、错误日志、甚至两年前的一个需求讨论全塞给了助手。结果很“经典”：我只想让它调整退款状态机，它却顺着旧文档里的逻辑，把支付回调那一段也改了，还改错了。我当时的第一反应是怪工具笨，后来仔细一查才发现，是我给的上下文太杂了，AI 分不清哪些信息是当前任务需要的事实，哪些只是过期背景。
后来我认真研究并实践了所谓 context-mode，也就是“上下文模式”。这个词在现在的 AI 编程工具里并不算统一按钮，更准确地说，它是一整套控制“AI 能看什么、该看什么、以什么顺序看”的方法。核心思路很简单：别让 AI 助手像个刚入职的实习生一样翻遍整栋楼的资料，而是给它划好工位、给好图纸、限定它只需要看哪几个文件夹，它的注意力才能真正集中在你现在要做的事情上。
这篇文章会把我在这个过程中沉淀下来的配置逻辑、实操流程、踩坑记录全部写出来。不管你是用 Cursor、Copilot 还是其他带 AI 助手的编辑器，只要你的工作流里有“AI 改代码”这一环，这套东西都值得参考。尤其适合三类人：独立开发者、维护老项目的人、以及带小团队但希望统一 AI 使用规范的技术负责人。
1.1 一次改错文件的现场复盘
那次翻车不是偶发，后来我在团队里复盘，发现很多人都有类似经历。表面上看是“AI 乱改代码”，实际是上下文管理出了问题。当时的会话里至少混了这么几类信息：项目总览、旧版接口定义、某个客户反馈帖子、还有一份勉强能跑的测试报告。这些信息彼此之间没有优先级，AI 在处理我的提问“订单退款后是否要同步关闭渠道侧订单”时，把旧文档里的“渠道侧订单由外部回调关闭”当成当前结论，自然就走歪了。
切换到 context-mode 之后，我的做法完全不同。我先新建一个会话，只加载两个文件：当前订单模块的核心数据模型，以及本次重构要用的状态机设计草案。其余文档一律不进上下文。同样的提问，AI 的回答立刻变精准，还会主动提醒我“当前上下文里没有渠道侧回调实现，需要再补充确认”。这一个细节说明问题：AI 不是不知道能力边界，是你没有帮它划定信息边界。
那次之后我养成了一个习惯：开新会话之前，先问自己一句“如果今天只让 AI 看三个文件，我会选哪三个？”这个问题的答案，就是最合适的 context-mode 输入范围。绝大多数项目需求，其实不需要把整个代码仓库塞给 AI，甚至不需要把整个模块塞进去，只需要关键数据模型、关键接口定义、以及当前任务的约束，就足够让 AI 完成相当一部分工作。
1.2 context-mode 真正管住的三个变量
在我把 context-mode 拆给团队听的时候，我喜欢用“三个变量”来讲：范围（scope）、状态（state）、规则（rules）。
范围说的是 AI 能接触哪些文件。比如当前任务只涉及order_service.py和refund_flow.py，那就明确告诉 AI“你只需要看这两个文件里的内容，其他代码不要自动参考”。很多工具支持@文件路径精确引用，这就是最轻量的范围控制。更重一点的做法，是把相关文件整理成一份索引文件，再让 AI 在 context-mode 下按需展开。状态指的是当前任务的目标和进度，比如“今天的目标是把退款状态机改成三段式，已完成 1、2 段，第 3 段需要用新的异常处理逻辑”。这部分信息不来自代码，而来自你对任务的理解，它解决的是“AI 对当前该干什么缺乏锚点”的问题。规则则是一系列约束条件，比如代码风格、禁止修改的文件、必须遵守的命名规范、测试命令的统一写法。规则文件不需要很长，但必须可执行。
这三个变量想明白之后，context-mode 就不神秘了。它就是给 AI 构建一个“临时工作记忆”：范围告诉它看哪里，状态告诉它现在做到哪、下一步做什么，规则告诉它怎么做才符合这个项目的套路。三者缺一个，AI 都会开始自由发挥。自由发挥的 AI 在简单任务里问题不大，一旦项目复杂度上来，错误率就指数增长。
2. 搭一套适合自己的 context-mode 配置，我是这么弄的
很多教程只讲“用上下文模式”，却很少讲“上下文怎么组织”。我一开始也踩了很长的弯路：规则写了一长串，结果 AI 每条都读到，但每条都没执行到位；目录索引做得过于详细，反而让 AI 在读取阶段就消耗了大量 token。后来我总结出一套相对稳定的配置方式，核心就三条：分区管理代码文档、用清单控制加载顺序、规则分层避免互相打架。
2.1 把代码库拆成“上下文分区”
我先在仓库里建了一个独立目录，叫ai-context/，不参与业务代码编译。里面不是随便丢几个 markdown，而是按用途分成四块：specs/放功能说明、rules/放项目级行为约束、tasks/放当前迭代的任务描述、archives/放已经结束的旧方案和复盘记录。这四块的读取优先级是不一样的。
比如在一次支付模块改造中，我只需要specs/payment-redesign.md和rules/backend-rules.md，旧方案在archives/payment-v1.md里，虽然也相关，但我不希望 AI 默认加载它。我就在 context 清单里写明“archives 目录需要显式指定才读取”。这样设计的目的很简单：把“可能有用”和“当前必须有用”分开。AI 上下文窗口再大也是有限的，与其让它把 token 花在“读过但不一定对”的旧文档上，不如把位置留给当前需求的核心描述。
目录本身不需要很复杂，关键是稳定。别今天叫specs，明天叫requirements，后天又叫docs。AI 工具通常对路径很敏感，项目越大，这种路径一致性带来的收益越明显。我自己见过最夸张的情况是，某团队把一个“项目背景”文件写了四个版本，分布在三个目录里，AI 每次可能读到不同版本，最后结论自然对不上。所以我在实际操作里几乎只维护一份 specs 下的最新版，其他相关历史内容一律进 archives。
2.2 用上下文清单控制加载范围
真正让 context-mode 跑起来的，是一份清单文件，我习惯叫它CONTEXT.md。这个文件不写长篇大论，只写路径和优先级。它像是一份给 AI 的“阅读地图”，明确告诉 AI：当前模式下，你主要看这些文件；如果你想理解全局，再按需翻这几个文件；其余文件除非我明确提到，否则不要主动读。
我的一份典型CONTEXT.md大概是这样的：
MODE: context-mode PRIORITY_1: - ai-context/specs/refund-state-machine.md - ai-context/tasks/2025-refund-refactor.md - src/order/service.py PRIORITY_2: - ai-context/specs/legacy-payment-flow.md - src/payment/client.py EXCLUDE: - ai-context/archives/** - test/fixtures/**它不需要是标准格式，只要是 AI 能一眼看懂的结构就行。我在实际使用中还会在清单里加一句话：“每当我提问时，先按 PRIORITY_1 的范围回答；如果信息不足，再询问我是否读取 PRIORITY_2。”这句话效果很好，它让 AI 不会在我问一个订单问题时突然跑去读支付客户端的完整实现。清单的真正意图，不是建一座文件索引大而全，而是建立一层“过滤网”，把高频读取的文件暴露给 AI，把低频或者过期信息隔离出去。
这层过滤网还有一个好处：你会被迫去维护它。因为一旦新需求涉及新文件，你就得更新清单，这个过程本身就是一次需求澄清。我记得有一次做优惠券模块，业务方说“跟以前一样”，但我打开清单发现自己根本没有为优惠券建过 spec，只好拉着业务方把规则逐条口述清楚，再写进清单。最终 AI 的表现也因此稳定很多，因为没有这些规则，AI 确实不知道该怎么做。
2.3 规则文件怎么分层才不会互相打架
规则文件是另一个容易出问题的地方。很多团队喜欢把所有规则堆在一个大文件里，比如“不要用拼音命名”“用 HTTPS”“错误处理必须统一”“注释用中文”等等。问题在于：当规则数量超过一定阈值，AI 会把它当背景噪音，或者在某些任务里选择性地忽略部分规则。
我最终采用三层规则结构。第一层是用户级规则，写在 AI 工具的全局配置里，适合“我写代码必须遵守个人习惯”这类内容，比如缩进风格、写注释的偏好。第二层是项目级规则，放在ai-context/rules/下，每个文件聚焦一个主题，比如api-rules.md、db-rules.md、error-handling-rules.md。第三层是任务级规则，写在每次会话的开头，只对当前任务生效，通常三五条就够，避免泛化。
这三层规则的执行优先级从高到低是：任务级 > 项目级 > 用户级。我踩过的一个典型坑是：用户级规则里写了“所有注释都用中文”，但项目级规则里恰好要求“公共 API 的示例代码注释保留英文”，结果 AI 一致遵守了用户级规则，导致特定文件里的注释被统一成中文，反而偏离了项目约定。后来我明确规定“存在冲突时，越具体的规则越优先”，并把这条写进项目级规则文件的首行，问题才解决。
规则文件本身不建议太长，每个文件控制在几十行以内，超过就拆。因为 AI 对规则文件的读取并不像人类那样会“跳着重读重点”，它通常是整体读入，然后按注意力分配权重。一条规则如果埋在 200 行文件里，它被实际执行的概率并不高。与其这样，不如让规则文件保持短、清晰、高频版本更新。
3. context-mode 的完整实操流程：从一个需求到验收
配置是一回事，真正跑起来是另一回事。我拿一个比较典型的“订单退款状态机增加人工干预节点”需求为例，讲讲我从准备到验收的完整操作流程。这个例子里的 AI 角色是「结对编程的辅助者」，不是无人驾驶的代码生成器，这一点必须先明确。context-mode 不是让你撒手不管，而是让你能在更受控的情况下指挥 AI。
3.1 开工前先做三个动作
第一个动作，写任务描述。不是一句话需求，而是包含背景、改动边界、验收标准三个小段。我的习惯是直接新建ai-context/tasks/2025-refund-manual-intervention.md，里面开篇第一段写明：这次任务只改退款状态机，不涉及支付回调逻辑；第二段写当前状态机有哪些状态，哪些需要并入新的“人工审核中”状态；第三段写验收标准，比如“同一笔订单不能同时存在两个待人工审核记录”这类可执行检查。任务描述是 context-mode 里最核心的文件，因为它承载了“状态”变量。
第二个动作，引用必要 spec 和关键接口。如果我需要看refund.py，我不会简单说“你看一下 refund.py”，而是在上下文里写清楚：核心数据模型在src/order/models.py，退款状态机实现在src/refund/state_machine.py，涉及的外部回调接口在src/payment/client.py。在支持@引用工具中，我会直接把这三个文件 pin 到会话上下文里。如果工具不支持 pin，我也一定会给出完整路径，并且说明每个文件在这个任务里的作用，比如“models.py 主要看 RefundOrder 这个类的状态字段”。
第三个动作，把约束写进任务的规则块。例如“不允许修改数据库迁移文件”“不允许改动现有退款成功后的回调逻辑”“如果某个操作会引入新的依赖，要先停下来询问”。这些约束放在任务文件里，不放进全局规则文件，因为它们只对本任务有效。实测下来，跑完这三个动作再让 AI 写代码，它第一版输出就已经比较接近最终结构，后续修修补补的时间大幅减少。这像是给 AI 一份“项目手册”加上一张“本次设计图纸”，它不需要靠猜。
3.2 开发过程中保持上下文“干净”的维护姿势
很多人在会话进行到中段时开始翻车，原因不是初始上下文不够，而是随着对话轮次增加，旧讨论、临时报错、被否定的方案，全都混进了上下文。context-mode 在这里体现为“主动维护”而非“只建一次”。我每解决一个子问题，就会在任务文件里追加一行“已完成：状态机拆分顺序已确认，不需要再次讨论”，然后在新提问里给 AI 明确指令：“基于当前状态，不需要重新评估已确认方案，只看新问题”。
还有一个小技巧，是善用新会话。AI 会话的上下文窗口再怎么大，也不可能无限藏信息，而且超过一定长度后，模型对早期内容的引用精度会下降。我的经验是：一个任务如果超过大概 50 轮对话，要么把中间结论整理成一份“进展备忘”，开新会话继续；要么接受近几轮信息的权重会高于早期信息这个事实。所谓“进展备忘”，就是精简地写清楚已完成事项、未完成事项、当前阻塞点、下一步计划，然后在新会话里让 AI 先读这份备忘。这一步几乎是我实测下来最稳定的“防失忆”手段。
精确引用比模糊描述可靠。我尽量避免说“你看一下上次我们讨论的那个问题”，而是说“请读取 ai-context/archives/2025-refund-reopen-note.md 中的‘不可用状态’小节，再回答当前问题”。如果工具支持直接引用文件片段，我还会在引用时括注范围，比如只引用某个文件的某几个 class。这样既节省 token，也让 AI 明确知道它该抓取的信息点。很多“AI 好像听不懂人话”的情况，其实就是因为在模糊描述下，AI 根据上下文猜测了一个最可能的文件，而那个文件并不是你心里想的那份。
3.3 需要 AI 跨多个模块时怎么扩大上下文
不可能每个任务都是单文件改动，遇到真正跨模块的需求时，盲目扩大范围是常见的错误。比如一次“接入新支付渠道”的任务，涉及订单模块、渠道配置模块、账务对账模块、前端回调展示。我第一次做时，把十几个文件全部塞进会话，结果 AI 在只改某一个渠道接口时，居然擅自改了另一个渠道的配置，因为它的上下文里同时出现了两份相似配置，产生了混淆。
后来我用“地图文件”的方式解决了这个问题。我先写一个payment-channel-map.md，里面只描述各模块的职责边界、关键文件路径、以及这些模块之间的调用链路，并注明“细节请按需读取对应文件”。在 context-mode 下，AI 先读地图，再根据我的提问决定展开哪些具体文件。这个模式非常像人在大项目里先看整体架构图，再钻到具体实现里的行为，既保留全局视野，又不会被过多细节冲昏头脑。
当然，跨模块场景里，我还要求自己至少有三个了解：第一，数据是从哪个入口进入的；第二，改动会不会影响异步任务；第三，有没有下游系统依赖这个模块的旧行为。这三个了解不一定全都告诉 AI，但要体现在我给它的引用列表里。如果某条链路我完全不确认，我不会让 AI 瞎猜，而是先把该读的接口代码让 AI 读一遍，再让它总结链路。这个“先总结再动手”的步骤，能把跨模块改动的意外影响降到最低。
4. 常见问题与排查技巧实录
context-mode 不是什么银弹，我自己是用了一段时间之后才逐渐把握住它的节奏。这里挑几个高频问题，把排查思路和解决办法写透，希望对正在配置或者已经配置过但效果不佳的人有帮助。
4.1 为什么我开了 context-mode 反而更笨
这是最伤情绪的问题。明明给了 AI 更明确的文件范围，它反而不会写代码了。我排查过多次，最常见的原因是“过度约束”。context-mode 如果被配置成一份巨细无遗的死板规则集合，AI 的注意力会被大量约束细节占满，反而没有余力进行正常推理，表现自然像变笨了。
排查思路是先“降级验证”：临时清掉任务级规则，只保留两个核心文件和一句话任务描述，看看 AI 是变好还是变差。如果变好，说明规则确实过载；如果变差，再看是不是核心文件引用错了。我有一次就是引用了一个已经被弃用的refund_v2.py而忘了项目里真实代码在refund/目录下，AI 基于旧文件回答，当然越答越歪。这种问题不看上下文文件内容是查不出来的，它跟模型本身能力无关。
还有一种可能，是上下文里的信息冲突而不是过剩。例如项目级规则写了“所有金额用整数类型”，但 spec 文件里给了 float 的示例代码。这种矛盾会让 AI 很纠结，输出可能是两份逻辑并存。解决办法也简单：每次新建会话，把“冲突记录自查”加入 checklist，如果 AI 在某处犹豫不决，主动让它列出上下文里的矛盾点，再按具体规则优先级裁决。
4.2 上下文长度还是爆掉了怎么办
只要 AI 工具存在上下文窗口上限，这个问题就不可能避免，哪怕模型支持很大的上下文也一样，因为越长越容易出现注意力稀释。我的处理思路不是去优化第一句话能塞多少，而是尽量让会话“短任务化”。
具体做法是：把一个大的重构拆成多个小任务，每个小任务都使用独立的上下文会话。在上一个会话结束时，我会留下一个progress-summary.md，里面记录已完成的内容、编译状态、测试命令、遗留问题，然后下个会话基于这份 summary 继续。这相当于把 AI 的“长期工作记忆”外置到文件系统中，而不是全部依赖模型内部的上下文窗口。
如果确定某个会话必须承载较大信息量，我会做一个 token 预估：先把要加载的文件字数粗略估算一下，如果明显超过可接受的上下文范围，就采用“分段阅读”策略。比如先让 AI 读配置文件，了解模块间调用关系；接着读核心业务逻辑文件；最后读测试文件。不要一次性让 AI 并行感知所有文件，而是一步步地在当前会话里建立对项目的认知。这个顺序跟人阅读大型代码库的路径几乎一致，也是实测效果最好的方式。
还有一点容易被忽略：删除无用消息。很多聊天式 AI 工具允许移除对话中的旧消息，这比简单地“忽略”更干净。如果旧讨论涉及已经废弃的方案，我会直接删掉那几轮对话，而不是用一个新指令去覆盖它，因为覆盖不代表遗忘，模型仍然可能从旧消息中提取信息，产生隐性干扰。
4.3 团队协作时 context-mode 的一致性怎么保证
个人用得好不算好，团队都能稳定复现才算好。我带团队时做过一个实验：给每个人一份相同的 context 配置，让他们各自去完成“给登录模块加一个验证码防重试”的小任务。结果最后交付的代码结构差异很大，有人把验证码策略硬编码在 service 层，有人做成独立组件。不是 AI 不行，而是每个人启动会话时的额外说明不同，任务级规则里写的东西五花八门。
所以后来我把 context-mode 的配置文件纳入版本控制，并且要求团队在每次修改ai-context/下的内容时，走 normal code review 流程。也就是说，配置文件和业务代码一样要被 review，不能被随意悄悄改掉。我们还会定期做一次“从零启动”验证：把所有上下文文件清空，只依赖版本库里的配置，让一个不太熟悉项目的人按文档走一遍，看能不能稳定启动 context-mode。这个验证非常有效，能一次性暴露“文档里写了很多但实际路径错了”“规则互相冲突”等隐形问题。
如果团队用的是支持多 profile 的工具，我建议建几个不同的 context-mode 配置：一个用于需求分析、一个用于代码生成、一个用于测试补充。不要试图用一个万能配置覆盖所有场景。需求分析场景需要更强的上下文理解能力，可以多塞一些文档；代码生成场景则要尽量减少不相干文件，避免输出风格漂移；测试场景需要明确列出测试框架和期望覆盖分支。不同任务类型的配置差异很大，能分开就用最合适的方式。
4.4 工具选型与不同 IDE 的差异
市面上的 AI 编程工具对 context-mode 的支持各有各的叫法。比如有的工具用“添加上下文”按钮让你手动指定文件；有的工具支持@workspace、@file这类特殊符号；有的工具基于 agentic 模式，会自动探索整个代码库。我自己的观点是：不要迷信任何一家工具原生提供的“自动上下文”，最终都要落到“你能控制什么”这个层面。
以我实际经验来说，自动探索模式在小型代码库或者依赖很少的项目里很好用，因为模型能自己找到相关内容。但一旦项目变大，自动探索可能既消耗时间又消耗 token，还会抓进来一些看起来相关但实际上过时的文件。这个时候，我更倾向于显式指定文件。哪怕多花一点时间维护路径，也换来更确定的输出质量。
另一个差异点是规则文件的读取方式。某些工具会自动读取项目的.cursorrules或类似文件，作为全局注入；有些工具则需要你在每次会话开头手动加载。如果工具支持自动加载，我反而会担心“全局规则污染”的问题，因为自动加载意味着任务无关的规则也会进入上下文。我一般会在项目规则里加一句“本规则只适用于涉及 X 模块的修改”，尽可能给规则限定范围，避免跨模块时产生不必要约束。
5. 关于 context-mode，我还想补充的几个实操习惯
想讲的东西很多，但落到纸面上，我觉得真正受用的是一些看似琐碎的小习惯。比如我在启动新会话前会重温一遍那份 context 清单，确认它没指向错误的分支；比如我在任务文件里不只写“做什么”，还会写“不做什么”。这些习惯单独看都很小，但叠加起来就是稳定的输出质量。
5.1 把 context-mode 当成一种“工作日志”而不是临时设置
我看到很多人在项目里并没有真正把上下文文件当一回事，只是每次开会话时临时引用一两个文件，用完就丢。一旦第二天想继续，又得让 AI 重新理解需求。后来我改变策略：把所有关键讨论，都沉淀成 context 文件，让 context-mode 具备连续性。每天收尾时，我会把当天的决策追加进tasks/对应文件，并在archives/里记录被否掉的方向。这样下一次开会话时，AI 读的不只是代码，还包括项目最近的历史判断。
这种习惯听起来很费时间，但实际每次只多花五到十分钟。对一个持续两三周的迭代来说，这些记录能避免 AI 反复提出同样的错误方案，减少大量讨论成本。我甚至觉得，context-mode 的真正价值不在于单次会话的准确率提升，而在于它能把你和 AI 的协作过程变成一份可追溯、可复盘的知识资产。
5.2 如果遇到 AI 输出不稳定，先别急着换模型
最后分享一个容易忽略的经验：当 AI 表现忽好忽坏时，多数人第一反应是“换个更厉害的模型”，但我的实操结论是，先把 context 配置干净再谈换模型。模型能力上限固然重要，但在绝大多数场景下，上下文混乱造成的负面影响比模型本身的差异更明显。我做过对比，同一个任务，在上下文配置完整、文件引用准确的情况下，旧版模型的表现甚至能超过一个配置混乱场景下的大模型。
所以如果你的 AI 编程助手开始“犯迷糊”，我的建议是先做十分钟的上下文清理：关掉多余文件、精简规则、补上任务验收标准。很多时候问题立刻就会缓解。这也是我写了这篇文章的初衷：在大家都忙着讨论大模型参数时，真正能提升日常效率的，往往是这些看起来不起眼的上下文工程细节。
