代码库一大就不好用？先看各家 AI 编程工具怎么读你的代码

「500 行的项目里它像专家，50 万行的仓库里它像新手」——这句抱怨在几乎所有 AI 编程工具上都成立。最常见的解释是「上下文窗口不够大」，但翻完官方文档会发现，这个解释只说对了一半：窗口是上限，而决定体验的是代码怎么被找到、找到之后又能塞进去多少。

这两件事在官方文档里被拆成了不同的机制。Aider 说的是「为整个代码库建一张地图」，Cursor 说的是「索引建在你的机器上」，Claude Code 说的是「当 Claude 读取子目录里的文件时，那些文件才被载入」。三种说法背后是三种架构，它们的成本结构与隐私含义都不一样。

这篇把 Claude Code、Cursor、Aider、Cline 的官方文档对齐，把「代码进入模型上下文」的过程拆成三条官方路线，再把每条路线的成本与隐私声明摆到同一张表上。数据于 2026 年 9 月 24 日重新核对官方文档。站内此前分别拉平过订阅价格与上下文窗口，这一篇拉平的是「索引」。

本文方法：官方公开数据交叉核对，未做本地实测。所有数字均标注来源，核对日期见文末。

一、代码进入模型的三条官方路线

先把术语说清楚：所谓「读你的代码」，在工具内部其实分成两步——找到相关文件，以及把内容送进模型上下文。各家官方文档对第一步的处理方式差别最大，而这一步决定了工具在大仓库里的下限。

三者的官方原文可以对照着读。Aider 的 README 写的是「Aider makes a map of your entire codebase, which helps it work well in larger projects.」——这是一句很诚实的表述：地图是为「更大的项目」准备的，代价是这张地图本身要占地方。

Cursor 的文档把索引位置说得更死：「Instant Grep builds and queries its index on your machine.」官方还补了一句关键声明：Cursor does not upload file paths or code to build a search index, and it does not store embeddings of your codebase for search.也就是说，在这条路线上，建索引这一步不产生任何出网流量。

Claude Code 走的是第三条。官方对子目录里的 CLAUDE.md 给了一条明确规则：「Instead of loading them at launch, they are included when Claude reads files in those subdirectories.」这条规则可以推广到它对代码的整体态度——不预先载入，等读到了再进上下文。官方在成本文档里还专门建议优先用 CLI 工具，理由是它们「don’t add any per-tool listing」，即不产生常驻开销。

开源客户端的描述方式也指向同一个设计目标。Cline 的官方 README 写「Cline reads your project structure, understands the relationships between files, and makes coordinated changes across your codebase」，同时把按需加载写成了一个独立机制：「Use skills to let the model load specific rules when needed.」这说明「按需」在开源方案里同样是被当成设计目标，而不是省钱的副产品。

还有一处需要单独说明，因为它和「索引」直接相关。Cursor 官方明确，Cloud Agents 是唯一需要 Cursor 存储代码的功能，原文是「Cloud Agents are the only feature that requires Cursor to store code.」官方对存储方式的描述是：加密的仓库副本、在 agent 运行期间临时存放、agent 完成后删除。同一页还给了一句很实用的建议——如果安全策略不允许存储代码，就不要开启 Cloud Agents，官方注明「You can still use all other Cursor features.」

把这段话和前面的索引声明放在一起，可以得到一个清晰的界线：「检索你的代码」和「存储你的代码」在 Cursor 上是两条独立的产品线。索引与即时检索不要求代码被存储，要求存储的是云端 agent。选购时如果只看到「不上传索引」这一句就放心了，可能会漏掉另一半。

二、分母固定：官方写死的注入预算

这一节是本文的核心。一个很自然的猜测是「仓库越大，工具自动就会带更多东西进上下文」。Claude Code 的官方文档给出了相反的事实：能常驻在上下文里的东西，官方给的是固定上限，不随你的仓库变大而变大。

把这张表连起来看，会得到一个官方页面不会主动强调的结论：启动时进入上下文的内容是有明确预算的。官方在上下文窗口的可视化页面里写得很直接：「A lot loads before you type anything. CLAUDE.md, memory, skills, and MCP tools are all in context before your first prompt.」先占掉一块固定的地，剩下的才轮到你的代码。

更能说明问题的是压缩之后的规则。官方原文：「Right after compaction, Claude Code re-reads up to five of the files Claude has read or edited in the session, choosing the ones modified most recently. A file over 5,000 tokens comes back as a path reference without its content, shown as Referenced file instead of Read.」按一行代码约 10 token 估算，5,000 token 大约是 500 行——一个 2,000 行的核心模块，在长会话压缩之后，模型只知道它存在，不知道它里面写了什么。这一步换算是本文的估算，官方只给了 token 数，没有给行数。

这就是「500 行好用、50 万行不好用」的真实机制：仓库变大了，需要读的文件变多了，但每次压缩后能带回来的上限还是 5 个文件、每个 5,000 token。分子在涨，分母没动。再加上启动时那批固定开销，留给代码的空间只会更小。

把上面这些机制按时间分成两类会更清楚。启动预算——CLAUDE.md、auto memory 索引、MCP 工具名、技能描述——在你输入第一个字之前就已经占掉了，而且每开一个新会话都要重新占一次；运行时预算——读进来的文件、技能体、压缩后的重读——随着任务推进消耗，并在压缩时被重新裁剪。两类预算的官方上限都是写死的：前者按行数与 KB 计，后者按文件个数与 token 计。

这也解释了官方为什么反复建议把指令从 CLAUDE.md 挪到 skills。成本文档的原话是「Skills load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller.」挪走的内容没有变少，只是从「每次都占」变成了「用到才占」。在大仓库场景里，这个动作的收益比换一个窗口更大的模型要直接得多。

这张图要连着看最后一行的对比。两条路线在 500 行的项目里几乎都零成本，但在 50 万行的仓库里，路线 A 的问题是「地图本身变得太大」，路线 B 的问题是「每次查找要在更大的候选集里挑，同时能带回来的量还是那些」。这也解释了为什么开源方案和商业方案都会同时引入「子代理」这种机制：Cursor 官方的 Explore subagent 描述是「It executes many parallel searches without bloating the main conversation, returning only the relevant findings」，Claude Code 则用 subagent 把大量文件读取隔离在另一个上下文窗口里。两者解决的是同一个问题——把「找」的中间产物挡在主对话之外。

三、索引与隐私：三个容易被说错的点

下面三条全部来自官方文档，而且都属于「文档里写得很清楚、但很容易被营销话术盖过去」的那一类。它们的共同点是：不改变工具好不好用，但改变你对「代码到底去了哪里」的判断。

四、按场景怎么选

• 仓库在几千行以内：三条路线的差别可以忽略。这个规模下不需要为更大的窗口付费，也不需要额外配置排除规则。
• 仓库在十万行以上、需要跨模块提问：优先看工具的检索层质量，而不是窗口大小。Cursor 官方称 Instant Grep「outperforms ripgrep on large codebases」，Aider 则靠 repo map 覆盖全仓。两者的取舍不同：前者每次现查，后者先建地图。
• 用 Claude Code 跑长任务：记住四个数字——CLAUDE.md 200 行、auto memory 前 200 行或 25KB、压缩后最多重读 5 个文件、单个文件超过 5,000 token 只剩路径。第四个最容易被忽略：如果你的关键模块超过 500 行，压缩之后模型就看不到它的内容了。
• 上下文经常被撑爆：先把常驻项做减法。官方给了明确顺序——把专门指令从 CLAUDE.md 移到 skills（「Skills load on-demand only when invoked」）、关掉不用的 MCP 服务器、优先用 CLI 工具替代 MCP。
• 担心密钥进模型：.cursorignore 加全局忽略列表是第一步，但必须同时限制 Agent 的终端与 MCP 权限，因为官方明确这两条路径不受排除规则约束。更彻底的做法是看各家数据政策与数据保留规则。
• 需要让代码完全留在本机：只有开源客户端加本机模型这条路线。Cline 官方支持的提供商列表里包含 Ollama 与 LM Studio，Aider 官方称它「can connect to almost any LLM, including local models」。这条路线的问题不在隐私，在模型能力与运维成本，详见我们另一篇关于数据边界的整理。
• 团队统一管理排除规则：Cursor 的 Teams 档提供「team-wide privacy mode enforcement」，但隐私模式管的是「是否用于训练」，不改变排除规则的边界。要区分这两件事。

回到开头那个问题：为什么同一个工具在 500 行的项目里好用、在 50 万行的仓库里不好用。官方文档给出的答案是两层——检索层要在大仓库里挑出正确的文件，注入层要把挑出来的内容压进一个固定预算里。窗口变大只影响第二层的上限，不影响第一层的准确率，也不改变那些写死的截断规则。理解这一点之后，「换个窗口更大的模型」就不再是一个理所当然的解法了。