第一次注意到 context-mode（上下文模式）这个说法，是在一次改代码改到差点想砸电脑的时候。我让 AI 助手帮我重构一个函数，它做得确实不错，但它完全没有意识到这个函数被另外三个模块调着用，结果一改，整个服务的异常率直接上去了。后来我才意识到：问题根本不在于 AI 模型的能力，而在于我压根没给它提供正确的上下文。context-mode 就是用来解决“AI 到底该看哪些代码、以什么粒度理解你的需求”这件事。这篇文章我想把我在 VS Code、Cursor、Claude Code 这些工具里反复试错后总结的经验拿出来讲讲，包括 context-mode 是什么、怎么用、怎么避坑，以及整理出一套可以直接照着做的操作流程。如果你也在用 AI 编程助手，并且觉得它有时候聪明得离谱、有时候蠢得离谱，这篇文章应该能帮你找到症结。
1. context-mode 到底在解决什么问题
1.1 上下文窗口：AI 编程的第一瓶颈
AI 模型不是人，它没有“长期记忆”。每一次对话，它能看到的内容就是一个有限长度的上下文窗口。这个窗口里要装下你的问题、你贴的代码、工具返回的结果、历史聊天记录，还有模型自己生成的回复。窗口一满，最早的信息就被挤出去，这就是所谓的“上下文衰减”。我最早用 AI 编程的时候，习惯把整个文件几百行代码复制粘贴进去，然后问“帮我加个参数”。结果它经常改错地方，或者改完之后的代码风格和原文件完全不一致。原因很简单：它只看到了那几百行代码，却没有看到这个文件里 import 了哪些东西、变量在哪些地方被引用、同事原来写的注释里有什么约定。这些信息，统统属于“上下文”。
上下文模式的核心，就是以某种机制把这种“上下文”组织起来，让 AI 在合适的范围内理解代码。可以说，没有上下文模式的 AI 编程工具，就像是一个记忆力只有五分钟的实习生；而有了好的上下文模式，它至少像是能翻着笔记本干活的实习生。很多人觉得“给 AI 看代码越多它就越聪明”，其实不完全对。上下文窗口是有限的，你塞进去的无用信息越多，模型能用来思考的空间就越小。context-mode 真正要解决的就是这个问题：在有限的窗口里，尽可能只装“应该装”的东西。
1.2 从“手动粘贴代码”到“上下文模式”的演进
在 context-mode 这个词流行之前，我们怎么给 AI “喂上下文”？基本靠手动。要么复制粘贴文件内容，要么在提问时用很长的自然语言描述：“文件 A 中的 xxx 函数接收一个 userId 参数，它会调用文件 B 中的方法……”这种方式有两个很大的问题：一是麻烦，二是容易遗漏。你描述得再详细，也很难把整个项目里所有相关的依赖关系、业务规则、隐含约定都塞进一段话里。我当时最崩溃的一次，是给 AI 描述了整整一屏的话，结果它还是把一个接口名字写错了，因为那个接口名在项目里已经改过三次，只有看代码才知道现状。
后来工具开始提供“上下文模式”这个开关。你告诉工具“我要基于整个代码库”或“只读当前文件”，工具就会自动去读取相关文件、搜索符号引用、分析调用关系，然后把结果拼装进上下文窗口，再交给模型。这个过程背后有很多工程细节：索引、embedding、局部检索、RAG（检索增强生成），但你在使用层面只需要理解一点——它帮你把“该让 AI 看什么”这件事自动化了。而怎么选合适的模式，就是接下来要讲的核心。
为了更直观，我把这两种方式做了个对比：
| 对比维度 | 传统手动贴代码 | context-mode |
|---|---|---|
| 信息覆盖 | 取决于你复制了什么，常有遗漏 | 工具自动检索，覆盖面更完整 |
| 操作成本 | 频繁切换文件、复制粘贴 | 一键切换粒度，问答即可 |
| 上下文噪声 | 容易把无关代码整段塞进去 | 检索排序会把噪声降到一定范围内 |
| 对提问者的要求 | 需要自己精通项目结构 | 可以边问边让工具帮你梳理结构 |
| 稳定性 | 对话越长越容易丢信息 | 有上下文模式辅助，信息维护更可靠 |
从对比里能看出来，context-mode 不是简单的“自动化”，它实际上改变了人和 AI 协作的方式。以前是你先得弄明白项目再告诉 AI，现在是你可以把“理解项目”这件事的一部分交给工具。
2. 主流 AI 工具里的 context-mode 到底怎么用
2.1 VS Code Copilot Chat：把“整个代码库”变成可检索上下文
VS Code 里装好 GitHub Copilot 之后，打开侧边栏的 Chat 面板，通常会有几个上下文选项：比如 “editor”（当前文件）、“selection”（选中的代码）、“workspace”（当前工作区）、“codebase”（代码库）。这个设计其实就是 context-mode 的具体体现。我用得最多的组合是：先选中一段代码，再选“codebase”模式，然后提一个具体问题。比如选中一个函数，说“这个函数最近被标记为 deprecated，帮我找出所有调用方，并改造成新接口”。如果不选 codebase 模式，Copilot 只会在当前文件里找答案，往往会漏掉其他模块。选了之后，它会去搜索整个代码库里的引用。注意，这个模式不一定把全部源码都塞进上下文，更常见的是先做检索，挑出 top 相关文件，然后只把这部分内容送给模型。
这里有个细节：VS Code 的 codebase 模式在大型 monorepo 里默认索引可能不全。我第一次用的时候，它找不到某个子包里的符号，后来才发现需要把那个子包的目录也纳入搜索范围。而且在提问时尽量带上具体的函数名、类名、文件路径，不要只给模糊的“那个模块”。检索系统靠关键词匹配，你给的信息越精确，它带回来的上下文越准。
2.2 Cursor 的“上下文模式”：按文件、按目录、按代码库三层控制
Cursor 的 context 控制更精细一些。你可以在提问时用 @ 符号引用具体文件，也可以引用整个文件夹，或者用一个叫 @Codebase 的标识来覆盖整个代码库。这三个粒度对应三种不同的 context-mode 需求。我的习惯是：
- 改一个小 bug，就用 @文件名，上下文最少，token 损耗最低；
- 跨模块重构，用 @folder 把相关目录拽进来；
- 排查一个“跑了很久突然报错”的问题，直接 @Codebase，让 Cursor 自己去找线索。
用 @Codebase 有一个明显代价：慢。我第一次用的时候，它扫描整个项目花了十几秒，而且因为项目里 node_modules 太大，一度卡死。后来我学了 Cursor 的配置，把 node_modules、dist 这类目录加进 ignore，让索引只覆盖源码，速度才上来。这一步值得单独记下来：无论哪个工具，全局索引的排除规则直接影响 context-mode 的可用性。你不可能也不应该让 AI “看到”所有依赖包，那里面充斥着生成的代码和第三方库，对解决问题往往没有任何帮助。
2.3 Claude Code 的上下文管理：会话记忆与自动摘要在实战中的取舍
Claude Code 是 Anthroic 出的一个命令行 AI 编程工具，它的 context-mode 逻辑不太一样：它没有那么多显式的开关，而是通过对话历史 + 自动检索来维护上下文。你可以把/context理解成查看当前会话已经为模型准备了哪些信息。我在实践中的感受是：它更吃“会话纪律”。因为命令行环境下没有图形界面，你必须自己在提问时把目标说清楚。Claude Code 支持在项目里放一个 CLAUDE.md 文件，里面写项目的背景、规范、常用命令，每次会话启动时它会自动把这些内容作为上下文的一部分。这其实就是把“项目级上下文”沉淀成文件，非常值得借鉴。
相比之下，在 VS Code 里，你如果想让 AI 每次都记得项目约定，最好的做法也是写一个类似 AGENTS.md 或者 PROJECT_RULES.md 的说明文件，并在提问时 @ 一下这个文件。上下文模式不是玄学，它需要你主动给工具提供“稳定上下文”。我见过很多人抱怨“换了工具之后 AI 变笨了”，其实不是工具变笨了，是它们没有给新工具提供足够的项目背景。
2.4 其他编辑器与终端工具的上下文模式
JetBrains 系的 AI Assistant 也有类似功能，一般叫“Project”上下文；Neovim 的插件生态里则有通过 LSP 把符号信息、引用信息拼进 prompt 的方案。另外，终端里的ghCLI 配合 AI 插件，同样支持 context 参数。这里不面面俱到，你可以记住一个通用规律：凡是带上下文模式的地方，一定有“当前范围”和“整个项目范围”的区分；没有区分的地方，你可以通过 @文件 或手动贴代码来模拟。理解了这个规律，换工具也不会慌。
我在实际使用中还发现一个有意思的现象：终端类的 AI 工具往往比 IDE 里的助手更依赖“命令输出”作为上下文。比如你用grep找到了某个符号出现在哪些文件里，它会把这次grep的结果自动作为上下文；你运行测试得到失败信息，它也会把失败日志带进去。这种“工具结果即上下文”的方式，其实比 IDE 里静态的代码检索更贴近真实排错场景。所以不要只盯着图形界面里的 context-mode 开关，命令行工具里的自动上下文收集同样值得花时间研究。
3. 把 context-mode 用好的核心原则：什么该喂，什么不该喂
3.1 上下文粒度的三档选择：行级/文件级/代码库级
我把上下文粒度分三档：
第一档是行级。也就是只选中某几行代码，问“这段代码在做什么”“这个正则匹配什么”。这种模式适合做代码解释、找 bug 的局部逻辑，token 消耗最小，回答最精准。缺点是 AI 看不见全貌，容易忽略外部依赖。
第二档是文件级。把当前文件甚至相关文件作为上下文。适合做单文件内的重构、补全、格式调整。绝大多数日常小改动，用这一档就够了。别一上来就推倒整个代码库，不仅慢，还容易把无关代码的噪声带进来。
第三档是代码库级。适合跨文件的分析、排查全局问题、规划架构改动。这是 context-mode 的终极形态，但也是双刃剑。代码库越大，检索带来的噪声越大，AI 反而可能被不相关的内容带偏。我见过最典型的例子：问“用户登录失败为什么报 401”，AI 却把某个不相干的支付模块源码当作重点，因为那个文件里有 “platform” 这个词。这就是检索召回不精准导致的上下文污染。
那么怎么选？我的判断标准很简单：如果这个问题只需要看一个文件内部的数据流，就选文件级；如果这个问题需要理清“谁调用了谁”，就选代码库级。你要是拿不准，先从文件级开始，让 AI 给个初步结论，不够再加上下文。上下文模式的精髓在于“逐步扩大”，而不是“一次性全给”。
3.2 关键词与意图先行：让 AI 在正确的上下文里执行
很多人用 context-mode 时，提问依然很含糊。比如：“帮我优化这个代码。”优化什么？性能、可读性、还是兼容性？AI 无法从这么宽的指令里知道该关注什么，于是只能全面撒网，把大量不重要的上下文都带进来。我自己的做法是：在提问时先给一个“意图定位句”。例如：“这个小工具的 deviceId 参数目前是在多个文件里硬编码的，我想把它统一收敛到一个配置类里，你基于整个代码库找出所有使用位置，只给出改动清单，不要直接改代码。”这样 AI 就有了明确的搜索目标和输出格式，context-mode 的检索质量会明显上升。
另外，措辞里的“关键词密度”也很重要。你希望检索系统找到哪些文件，就把哪些关键词放进问题里。如果你提到 “export”“CSV”“download”，它自然会优先找相关的文件；如果你只说“帮我加个功能”，它只能靠猜。这里不是让大家写一堆晦涩的术语，而是要让意图可检索。
3.3 多轮对话中的上下文衰减处理
上下文模式不是一锤子买卖。一个会话里连续改了多个文件之后，模型记住的信息会逐渐崩坏：你说“把刚才那个函数改一下”，它可能已经不记得“刚才那个函数”在哪了。我的处理办法有两种：
一种是干脆开新会话，把关键信息重新总结一遍，让 context-mode 重新加载。虽然麻烦，但保住了正确率。我通常会在改完一个独立功能之后立刻开新会话，避免交叉污染。
另一种是使用“上下文复核”技巧：在修改完代码后，主动要求 AI 列出它认为相关的文件清单和它对改动的理解，再针对性地补充遗漏。相当于让 AI 把它的“上下文快照”展示出来。这个技巧在代码库级模式里尤其管用，能提前暴露检索遗漏。有一次我说“请列出你刚才修改过的所有文件以及每一步的改动理由”，结果 AI 列出来五个文件，其中两个我根本没让它改——它自己在检索过程中“过于主动”地改掉了。这要是没复核，又是一次大事故。
4. 一次完整的 context-mode 实战：从需求到落地
4.1 场景设定：给一个老项目增加一个新功能
为了让你看到全流程，我假设一个具体场景：有一个电商后台管理项目，Python + Flask，目录结构大概是 app/models、app/views、app/services。现在需要加一个“导出订单 CSV”的功能。这个功能涉及订单模型、用户权限校验、导出文件生成、前端下载按钮。如果我们没有 context-mode，就只能在几个文件之间来回手动复制，很容易顾此失彼。而且这个项目是别人维护过的，代码里有不少“看着眼熟但不能动的逻辑”，比如订单金额是 Decimal 类型，直接转字符串会丢精度。
这种老项目加新功能，最怕的就是 AI 自己发挥。所以我的流程分五步，每一步都用 context-mode 的某一种粒度来控制。
4.2 分步骤演示：如何配置上下文、如何提问、如何验证
第一步，先把当前项目在编辑器里打开，并排除无关目录。我会在设置里加 ignore，保证 context-mode 索引不会扫到 venv、node_modules、logs。这一步不做，后面不管你是文件级还是代码库级，都可能被无关文件干扰。
第二步，写一个项目说明文件 PROJECT_RULES.md，里面写清楚：订单模型在哪、权限装饰器叫什么、导出功能希望放在哪个模块、代码风格要求（比如所有视图函数都要加事务装饰器）。这个文件本身就是要喂给 AI 的“稳定上下文”。
第三步，打开 AI 面板，选择代码库级 context-mode，提问示例：
我要新增订单 CSV 导出功能。项目规则请看 PROJECT_RULES.md。请先定位订单模型和订单查询的 service 方法，然后给出后端导出接口的实现方案，包含权限校验、CSV 生成、响应头设置；最后给出前端按钮怎么调用这个接口。在动手前，先列出你计划修改的文件清单。
第四步，AI 给出清单后，我对照项目实际情况核对。比如 AI 可能会列出app/services/order_service.py和app/views/admin/order.py，但漏掉了负责记录操作日志的app/services/audit_service.py，我就手动把这个文件 @ 进上下文，并告诉它：“导出动作也要走审计，具体方式参照audit_service.py里的log_operation函数。”
第五步，改完代码后立刻跑测试和 lint，重点检查“导出文件里字段名是否和模型属性对得上”“只有管理员才能调用接口”这两个点。这一步不依赖 AI，纯粹靠人的经验和测试用例。
4.3 实测数据：不同上下文模式下的结果对比
在我自己的机器上做过一个小测试：同样的需求，分别用文件级和代码库级 context-mode 提问。结果很有意思：
| 对比项 | 文件级 context-mode | 代码库级 context-mode |
|---|---|---|
| 定位 service 方法 | 失败，AI 自己写了一个错误 SQL | 成功，找到现有 service 方法 |
| 字段名准确性 | 错误，臆造了order_number | 正确，沿用模型里的order_no |
| 代码风格一致性 | 差，风格和项目完全不一致 | 基本一致，复用现有事务封装 |
| 是否发现前后端调用关系 | 没发现，只改了后端 | 列出前端按钮位置，并给出接口路径 |
| 遗漏审计逻辑 | 遗漏 | 在提示后可以补齐 |
差异的核心不在于模型变聪明了，而是 context-mode 让模型看到了正确信息。这个测试让我彻底不再相信“直接粘贴一个文件给 AI 就能万事大吉”的做法。同样的提问，上下文不同，输出质量天差地别。
5. 踩过的坑和排查链路
5.1 症状一：AI 答非所问、胡编乱造——检查上下文是否被污染
这是我遇到最多的坑。一个大型项目里，如果代码库级检索把错误文件带进来，AI 就可能引用一个压根不存在的函数名。排查方式：先用最小化上下文复现问题。怎么复现？把 context-mode 从代码库级降到文件级，只给 AI 贴一个相关文件的部分代码，看它是否还犯同样的错。如果降级后表现正常，基本可以断定是检索阶段引入了噪声。我通常会在提问时加一句“只基于你检索到的最相关文件回答，不要推测我没有展示的内容”，能减少一半胡编乱造。
还要注意：AI 在对话过程中会把自己生成的代码也当成上下文。如果你在一个会话里让它生成过一段有错误的代码，后续提问它可能基于这段错误代码继续展开，导致错误被放大。所以发现幻觉的苗头，就应该立刻开新会话。
5.2 症状二：Token 消耗暴涨——上下文范围过大
AI 编程工具的计费通常跟 token 挂钩。有一次我连续用代码库级模式改了半小时，账单比平时翻了三倍。后来打开上方分析面板一看，几乎所有提问都携带了 5~8 个文件的内容，其中有一半跟问题无关。解决思路：在提问前先想清楚“这个问题真的需要全库吗？”如果是，就用代码库模式，但尽量把提问写得窄一点；如果不是，就切换到文件级，主动 @ 具体文件。还有一个经验：开启工具的“仅用检索结果作为上下文”或“关闭自动增加上下文”等选项，现代工具一般都有，但很多人没注意到。
如果你用 API 调模型，对 token 的计算会更敏感。这时候 context-mode 就成了成本控制的关键。我自己的常态是：能用 2 个文件说清楚的事，绝不开代码库模式；一个需求拆成多个小提问，而不是一个超长的大提问。这既省钱，也更容易追踪每一步的修改。
5.3 症状三：修改后代码崩了——上下文遗漏了关键约束
这个坑比胡编乱造更隐蔽。AI 确实找到了正确文件，但它不知道项目的隐性约束。比如项目里规定所有写操作必须走 Redis 锁，AI 在新增导出功能时没贴这个约束，就直接改了。排查这类问题，最重要的是把“项目规范”写进上下文文件。我在 4.2 里提到的 PROJECT_RULES.md 就是干这个的。如果项目很敏感，甚至可以明确写“导出接口在晚上 10 点到第二天早上 6 点之间禁止调用”。把这些约束写下来，context-mode 才会把它们当成上下文的一部分。
另外还有一类隐性约束是“历史遗留代码”。AI 可能想把一段看起来冗余的代码精简掉，但它不知道那段代码是为了兼容某个老接口才存在的。要避免这种问题，最简单的方法是告诉 AI：“不要重构任何与当前需求无关的代码。”一条简单的指令，往往能挡住 90% 的“顺手改动”。
5.4 排查步骤清单
整理一个通用排查清单：
- 先确认问题是不是“上下文范围错误”：改用文件级 + 当前文件复现。
- 检查是否有无关大文件被自动带入上下文：看 token 统计或上下文字段。
- 检查项目规范文件是否被包含：如果没有 @ 它，AI 大概率不知道。
- 在提问里明确说明“不要修改任何未列出的文件”。
- 让 AI 输出修改文件清单，再人工复核。
- 修改后立即跑测试、构建、静态扫描。
这套清单我现在基本形成肌肉记忆了。只要 AI 给的结果不对，我先按顺序过一遍，大部分问题都能定位。不要一上来就换工具或者换模型，先想想自己给了它什么上下文。
6. 个人使用体会与扩展建议
6.1 我的默认配置参考
现在我一般这样配置 context-mode：
- 常规小改动：文件级上下文，选中改动区域 + @项目规范文件。
- 跨模块分析：代码库级上下文，但先列出计划修改文件清单，确认后再动手。
- 复杂重构：开一个新会话，第一步只做上下文摸底（让 AI 描述它认为的现状），第二步做具体修改。
- 每个项目根目录放 PROJECT_RULES.md，这个文件本身定期更新，每次需求变更同步维护规范内容。
这套配置用下来，最大的变化是我很少再被 AI 的“自作聪明”坑到。并不是它变聪明了，而是我把它的活动范围控制住了。给它正确的地图，它才能带路；给它模糊的方向，它只会带你绕远。
6.2 下一步可以尝试的方向
context-mode 这个思路可以继续延伸：把检索词从自然语言换成代码符号，让 AI 直接基于 LSP 的符号索引去定位；把上下文文件分层，比如全局规范、模块规范、临时注意事项；甚至写一个自动化脚本，在提交前自动把 context-mode 的配置和当前 diff 一起打包给 AI 做代码评审。这些方向我自己也在试验，目前收获不小。
最后再分享一个小技巧：当你发现 AI 给出的代码总是“差点意思”的时候，不要怀疑模型，先怀疑上下文。你喂给它的信息质量，直接决定了它输出的质量。把 context-mode 当成一个可以主动调控的变量，而不是工具里的默认选项，你会发现自己对 AI 编程的掌控力完全不一样了。
