你知道吗？在Cursor中轻松应对大型代码库的秘诀就在这里！(附我的亲身实践分享)

如何轻松驾驭大型代码库？来看看这些实用技巧！

最近我注意到，Cursor 的官方文档新增了一个指南分类，其中有篇关于“如何在 Cursor 中处理大型代码库”的文章，读完之后我觉得挺有意思，想跟大家分享一下。

链接在这里：https://docs.cursor.com/guides/advanced/large-codebases

接下来，我会把这篇指南的内容翻译成中文，并加上我自己的理解（理解部分用斜体标出）：

---

处理大型代码库可比小项目复杂得多，真的会遇到不少挑战。根据我们在 Cursor 代码库的扩展经验和客户在管理大型代码库时的观察，我们总结出了一些行之有效的处理方法。

接下来，我会分享一些我们认为对大型代码库管理特别有效的技巧。

一、用 Chat 快速了解不熟悉的代码

如果你第一次接触一个大型代码库，可能会觉得有点棘手。

与其用 grep 搜索、点击来找指定的代码，不如直接用 Chat 来提问，这样你可以更快找到所需内容，并且还能收到关于它如何运作的详细解释。

注意：这里的 Chat 并不是指 v0.45 之前的 Chat 模式，而是泛指与 Cursor 的对话，包括当前的 Ask、Agent、Manual；

2、grep 是一个经典的命令行工具，用于在文本中搜索特定字符串或模式。

在下面这段视频中，我们正在利用 Cursor 来查找代码库索引的实现细节，同时请求一些示例帮助我们更好地理解。

除了用 Chat 来快速理解代码库的特定内容，我们还可以借助它来了解项目的整体结构，比如：

请分析项目代码库，用mermaid图表展示项目结构，以及各种文件的依赖关系等

不过，这种方法最好结合 mermaid.live、http://draw.io 等工具来进行可视化展示。

如果你需要熟悉的项目恰好在 GitHub 上，可以试试 Devin 推出的 DeepWiki（www.deepwiki.com）来帮助你。之前在知识星球上也提到过：

DeepWiki 可以看作是 GitHub 代码库的维基百科。原本的 GitHub 代码库只是简单的展示 README.md 文件，而 DeepWiki 会深入分析代码结构、文件和配置，生成以下内容：

• 结构化的项目文档：像维基百科那样，清楚列出项目概况、核心模块和关键概念等；
• 可交互的可视化 mermaid 图表：展示各种文件之间的依赖关系和模块的调用关系；
• 智能问答：支持用自然语言直接询问代码库的具体问题。

使用 DeepWiki 也很简单：

1、直接在官网上搜索任意 GitHub 仓库，就能看到一个类似维基百科的介绍页面；

2、或者在打开的 GitHub 仓库中，直接修改 URL，比如 https://github.com/microsoft/playwright-mcp，只需把 GitHub 替换成 deepwiki，即 https://deepwiki.com/microsoft/playwright-mcp，同样可以获得对应 GitHub 仓库的维基百科介绍页面。

如果你想在 Cursor 中使用 DeepWiki 的功能，可以考虑 DeepWiki MCP，这是一个非官方的 MCP 服务器，它能通过 MCP 接收 DeepWiki 的 URL，抓取相关页面，并将它们转化为 Markdown 格式，返回一个文档或页面列表。

链接在这里：https://github.com/regenrek/deepwiki-mcp

为了让 Cursor 更深入地理解代码库的结构，建议你在【Cursor 设置-特性】中启用【包含项目结构】选项，这样性能会更好。

二、编写特定领域知识的规则（Rules）

如果要你给新来的同事介绍代码库，你会说些什么来帮助他们快速上手呢？

每个组织或项目都有一些隐性知识，可能没完全记录在文档里。而有效利用规则，可以帮 Cursor 全面理解代码库（包括这些隐性知识）。

比如，你可以编写一条简单的规则，告诉 Cursor 如何实现新的功能或服务：

---
描述：添加一个新的 VSCode 前端服务
---
1. **接口定义：**
- 使用 `createDecorator` 定义一个新的服务接口，并确保包含 `_serviceBrand` 以避免错误。
2. **服务实现：**
- 在一个新的 TypeScript 文件中实现该服务，扩展 `Disposable`，并使用 `registerSingleton` 将其注册为单例。
3. **服务贡献：**
- 创建一个贡献文件来导入和加载该服务，并在主入口点注册它。
4. **上下文集成：**
- 更新上下文以包含新服务，从而允许在整个应用程序中访问。
---

再比如，如果你希望 Cursor 根据文件格式遵循相应的规则，就可以用 Auto Attached 模式来实现。

---
globs: *.ts
---
- 使用 bun 作为包管理器。相关脚本请参考 [package.json](mdc:backend/reddit-eval-tool/package.json)
- 文件命名统一使用 kebab-case（短横线连接的小写命名）
- 函数名与变量名统一使用 camelCase（驼峰命名法）
- 所有硬编码的常量使用 UPPERCASE_SNAKE_CASE（全大写+下划线分隔）
- 优先使用 `function foo()` 的函数定义方式，而非 `const foo = () =>`
- 使用 `Array` 的形式，而不是 `T[]`
- 推荐使用具名导出（named exports），例如 `export const variable ...` 或 `export function ...`，避免使用默认导出（default export）

关于 Cursor 的规则，我之前也写过一些文章，涵盖了最早的 .cursorrules 和最新的 Project Rules：

cursor教程 | 如何根据不同项目写好一份合格的 cursorrules?

Cursor Rules 在实际开发中的三种层级与应用（附 20 个常用 Rules）

早期我对 Cursor Rules 的理解更多是为了给 AI 制定规范。

由于 Cursor 中的各种大型模型有不同的编码特点，加之模型本身的随机性，使得我们与模型的每次对话，实际上就像在和一个新同事合作一样，需要不断给对方介绍项目要求，这种反复沟通肯定会让人感到疲惫。因此，Cursor Rules 就显得尤为重要。

我的这种理解，最初主要集中在个体与 Cursor 的合作上。但随着对企业使用场景的深入了解，我发现 Cursor Rules 并不仅仅是为 AI 制定的规范，它们也是确保团队成员在大型项目中使用统一的 AI 辅助标准的重要工具。

值得一提的是，编程只是 Cursor 应用的一个方面，很多人也在利用它作为 AI IDE，发挥它在文本编辑上的优势，比如写论文、创作小说、整理知识库等，Cursor Rules 在这些场景中同样能起到统一上下文的作用。

三、紧跟“计划制定”的过程

对于大型项目的变动，提前投入时间制定一个精确、合理的计划，可以大大提升 Cursor 的输出质量。

从头开始，制定一个清晰的计划

当你发现自己不断调整提示词，结果却依旧不尽如人意时，不妨停下来，重新规划一个详细的策略。这就像是给同事写产品需求文档（PRD）一样。通常，确定需要哪些改动是最具挑战性的部分，这更适合我们人类来完成。有了清晰的指令后，执行的工作就可以交给Cursor来处理了。

当然，AI同样可以帮助你制定计划。

在Cursor中，你可以开启Ask模式，把你从项目管理工具、内部文档或者零散想法中获得的上下文信息都输入进去。想象一下，你在代码库中需要用到的文件和依赖项。可能是包含你想集成的代码片段的文件，也可能是整个项目的文件。

以下是一个“让AI协助制定计划”的示例提示：

制定一个关于如何创建新功能的计划（类似于 @existingfeature.ts）
如有任何问题，请向我提问（最多 3 个）
请务必搜索代码库
@Past Chats（我之前的探索提示）
以下是来自 [项目管理工具] 的更多背景信息：
[粘贴的工单描述]

我们可以通过“向人类提问”的方式让模型制定计划并收集上下文，参考之前的探索提示和工单描述。推荐使用Claude-3.7-Sonnet、Gemini-2.5-Pro或o3这类推理模型，它们能够理解项目改动的意图，从而更好地制定计划。

在Cursor开发大型项目时，大家普遍使用的模式是Plan&Act：

• Plan模式：负责制定计划
• Act模式：负责执行计划

我之前分享过的文章 Cursor解决bug总在绕圈？可以尝试引入 Memory Bank，介绍了如何在Cursor中应用Plan&Act模式以实现更高效的开发。

---
描述：
全局设置：
始终应用：true
------
## 模式规则
你有两种操作模式：
1、Plan 模式：你将与用户共同制定计划，收集所有必要信息以进行更改，但不会实际执行任何更改
2、Act 模式：你将根据计划对代码库进行实际修改
- 你默认以Plan模式开始，只有在用户批准计划后才会切换到Act模式
- 每次响应开头需标明当前模式，计划模式显示'# 模式：Plan'，执行模式'显示# 模式：执行'
- 除非用户明确输入指令要求切换至Act模式，否则你将始终保持Plan模式
- 每次响应后自动返回Plan模式，用户输入计划指令时也会切换回Plan模式
- 在Plan模式下若用户要求执行操作，你需要提醒当前处于Plan模式，需要先批准计划
- 在Plan模式下，每次响应都必须输出完整的更新后计划

当然，这种方法也可以通过Cursor的自定义模式（Manual模式）实现：

在【Cursor Settings-Features】中开启【Custom modes】后，你就可以在对话框中配置Plan模式和Act模式，之后可以根据自己的开发流程自由切换工作模式。

就像官方提到的，对于大型项目的变动，前期花时间思考并制定一个清晰合理的计划是非常值得的。所以在Plan阶段，其实可以进一步拆分为Research模式和Plan模式：

• Research模式：主要进行前期调研，包括需求收集、功能理解和模拟实现
• Plan模式：将前期调研的内容转化为具体的可执行计划，PRD就是一种计划的展现形式

简单介绍一下这三种模式的配置，大家可以根据实际情况进行调整：

Research模式：可以选择Claude-3.7-Sonnet、Gemini-2.5-Pro等推理模型；tools可按照截图所示选择，其中MCP并非必选；Advanced option的custom instructions可使用以下指令：

在提出解决方案之前，从工作空间和代码库的多个来源中收集全面信息。
分析代码和近期变更，但不得自动修复问题。
不得修改任何代码。 如需使用代码展示解决方案，直接在回复中以纯Markdown文本格式提供。
在提供解决方案时，保留相关上下文信息（如文件路径、函数名或模块），以便用户理解。
避免基于不明确的假设进行分析或建议，必要时向用户请求澄清。
以一致的格式（如代码块、列表或标题）呈现分析结果和解决方案，便于用户快速阅读。

Plan模式：与Search模式的配置基本一致，主要区别在于Advanced option的custom instructions：

**充分研究和审查**：
在开始制定计划前，需全面研究和审查所有相关细节，包括我们讨论过的内容、文档、代码库和外部资源。

**制定详细实施计划**：基于研究结果，创建详细的实施计划，但不直接修改代码，计划需要包含以下内容：
- 代码级别的变更指南，需完全基于代码库审查。
- 潜在风险分析及应对措施（如兼容性问题、性能影响）。
- 测试策略（如单元测试、集成测试）以验证变更效果。


**使用Mermaid图表**：对于复杂流程，使用Mermaid图表（流程图/时序图/状态图）进行说明：
- 使用清晰的标签和节点连接。
- 不同操作类型使用颜色编码（如输入为蓝色，处理为绿色，输出为橙色）。

**计划文件存储**：
- 所有计划文件必须存储在 .plans/ 目录下。
- 文件命名格式为 PLAN-{id}-{summary}.md：
  - {id} 为 .plans/ 目录及其子目录中的唯一编号。
  - {summary} 为任务的简短描述。
  - 文件采用 Markdown 格式，包含任务完成状态（如 [ ] 未完成，[x] 已完成）等。

Act模式：通常可以直接选择Agent模式。

四、选对工具，事半功倍

在高效使用Cursor的过程中，挑选合适的工具非常重要。要考虑你的目标，并选择能够让你保持顺畅工作的方法。

每种工具都有其独特的优势：

• 使用Tab进行快速编辑，让你成为工作的主导者
• 当需要对代码的特定部分进行精细修改时，Cmd + K会非常有用
• 对于需要Cursor理解更广泛上下文的大规模修改，Chat模式是最佳选择

在使用Chat模式时，虽然可能感觉有点慢，但它非常强大。你可以通过提供良好的上下文来帮助它。例如，使用@files指向你想参考的代码，或使用@folder来更好地理解项目结构。而且，不要害怕将大改动拆分为小部分——从头开始聊天能帮助保持专注和高效。

这部分内容乍一看似乎和处理大型代码库没有太大关系，但如果把它放到大型项目的代码重构中去理解，你会发现它非常实用。

对于大型项目的代码重构，通常无法一次性完成，拆分（如模块化）是常见做法。拆分后，大家可以根据每个阶段、模块、步骤的特点来选择合适的工具，例如：

初期规划阶段：使用 Chat模式分析项目结构，识别需要重构的模块或文件。结合@folder理解全局上下文，制定重构计划。

局部优化阶段： 使用 Cmd + K 进行特定代码块的优化，比如重构函数、提取公共逻辑或替换过时的API。

快速调整阶段： 使用 Tab 来补全重复性代码或修复小问题，保持编码流畅。

验证与收尾： 再次使用 Chat模式检查跨文件的一致性，或用 Cmd + K 微调，确保重构后的代码符合预期。

根据任务的规模和复杂性灵活切换工具，并结合上下文管理与任务分解，你就能在Cursor中高效完成大型项目的重构，最大化工具的价值。

总结：

1. 缩小变更范围，不要一次性尝试太多；

2. 如果条件允许，尽量在对话中包含相关上下文；

3. 利用Chat、Cmd + K和Tab在它们擅长的领域发挥作用；

4. 经常创建新的对话（之前在知识星球分享过，每次完成一个新功能，最好新开对话，以免之前的上下文影响后续功能开发）；

5. 使用Ask模式制定计划，使用Agent模式执行计划。

以上就是Cursor官方处理大型代码库的指南和我的实践经验，希望对你有所启发。

可以搭配Cursor首席设计师Ryo Lu分享的Cursor正确用法一起阅读 >>>Cursor官方谈Cursor的正确用法，以及我的实践解读