掌握Cursor：高效管理大型代码库的实用指南与个人经验分享

共计 6214 个字符，预计需要花费 16 分钟才能阅读完成。

掌握大型代码库的技巧：Cursor 使用指南

最近，我注意到 Cursor 的官方文档新增了一个名为“如何在 Cursor 中处理大型代码库”的指南。这篇文章内容丰富，值得分享给大家。

链接地址：https://docs.cursor.com/guides/advanced/large-codebases

以下是这篇指南的中文翻译以及我的实践理解（解读部分将采用斜体展示）：

与小型项目相比，处理大型代码库往往会面临更多复杂的挑战。通过借鉴 Cursor 自身在代码库扩展中的经验以及我们在客户管理大型代码库时的见解，我们总结出了一些有效的处理模式。

在本指南中，我们将分享一些我们认为在处理大型代码库时非常有效的方法。

初次接触大型代码库时，挑战可能会相对较大。

与其通过 grep、搜索或手动点击去寻找特定的代码部分，不如直接利用 Chat 功能。你可以向 Cursor 提问，以便快速找到目标内容，并获得更详细的工作原理解释。

注：1、这里的 Chat 并不是指 v0.45 及更早版本的 Chat 模式，而是包括与 Cursor 的对话，如当前的 Ask、Agent、Manual 等；

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

在下面的视频中，我们请求 Cursor 帮助，以获得代码库索引的实现细节，并请求示例以便更好地理解。

视频警告：播放链接不能为空

除了利用 Chat 进行快速索引和理解特定内容，我们还可以借助 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，只需将 URL 中的 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 Settings-Features】中启用【Include project structure】选项，以提升性能。

如果让你为新加入的协作者介绍代码库，你会提供哪些背景信息以帮助他们快速上手呢？

在每个组织或项目中，可能存在一些未被完全记录的隐性知识。而 有效应用规则，能够让 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 Rules，我之前分享过一系列文章，涵盖最早的.cursorrules 以及最新的 Project Rules：

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

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

早期，我对 Cursor Rules 的理解主要是为 AI 设定规范。

由于 Cursor 中的各种大型模型具有不同的编码特性，加之模型的随机性，使得我们与模型的每次对话实际上就像是与一个新同事进行结对编程。这就好比团队每天都将有新的成员加入，而你需要反复向他们介绍项目要求，这种情况一定会让人感到“疲惫”。因此，Cursor Rules 便是为了给 AI 设定规范。

之前的理解主要集中在个体与 Cursor 的互动上。随着对企业中 Cursor 使用场景的深入了解，我意识到 Cursor Rules 不仅是为 AI 设定的规范，也是确保团队成员在大型项目中能够使用统一的 AI 辅助标准。

值得注意的是，编程只是 Cursor 的应用场景之一。许多人还灵活运用它作为 AI IDE，在文本编辑、论文写作、小说创作、知识库整理等方面，Cursor Rules 在这些场景中也能发挥统一上下文的作用。

对于大型项目的改动，前期投入足够的时间思考并制定精准合理的计划，将显著提升 Cursor 的输出质量。

如果你发现反复调整提示词却始终无法获得理想结果，不妨停下脚步，从头开始制定一个更细致的计划。这就像为同事撰写产品需求文档（PRD）一样。在这个过程中，最具挑战性的部分往往是确定需要做出的具体改动，这正是我们人类的强项。一旦我们明确了指令，就能够将实际执行的任务交给 Cursor 来处理。

当然，人工智能同样可以协助我们进行计划的制定。

在 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 模式：与 Research 模式的配置相似，区别在于 Advanced option 中的 custom instructions：

** 充分研究和审查 **：在开始制定计划前，需全面研究和审查所有相关细节，包括我们讨论过的内容、文档、代码库和外部资源。** 制定详细实施计划 **：基于研究结果，创建详细的实施计划，但不直接修改代码，计划需要包含以下内容：- 代码级别的变更指南，需完全基于代码库审查。- 潜在风险分析及应对措施（如兼容性问题、性能影响）。- 测试策略（如单元测试、集成测试）以验证变更效果。** 使用 Mermaid 图表 **：对于复杂流程，使用 Mermaid 图表（流程图 / 时序图 / 状态图）进行说明：- 使用清晰的标签和节点连接。- 不同操作类型使用颜色编码（如输入为蓝色，处理为绿色，输出为橙色）。** 计划文件存储 **：- 所有计划文件必须存储在 .plans/ 目录下。- 文件命名格式为 PLAN-{id}-{summary}.md：- {id} 为 .plans/ 目录及其子目录中的唯一编号。- {summary} 为任务的简短描述。- 文件采用 Markdown 格式，包含任务完成状态（如 [] 未完成，[x] 已完成）等。

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

在高效使用 Cursor 的过程中，选择合适的工具至关重要。考虑你希望达成的目标，并选择能够帮助你保持工作流畅的方法。

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