1. 从“能用”到“好用”为什么默认配置总让你觉得差点意思很多人第一次打开 Cursor 的时候都会有一种“这不就是个换了皮的编辑器”的错觉。界面跟主流代码编辑器几乎一样快捷键也大差不差随便敲几行代码自动补全确实快了一点但远没有到“少写一半代码”的程度。问题出在哪出在你用的是出厂默认状态而 Cursor 真正的战斗力藏在它的规则配置体系里。我刚开始用的时候也踩过这个坑。当时接手一个中型项目代码量大概几万行涉及前端、后端和一堆脚本。默认配置下Cursor 的补全经常给我一些“看起来对但跑起来错”的建议比如引用了一个不存在的工具函数或者把某个异步调用写成了同步。后来我才意识到它不是不够聪明而是我对它的“约束”太少。它不知道我的项目用什么框架、遵循什么代码规范、哪些库是禁止使用的、哪些目录是自动生成的不能碰。这些信息如果不通过规则告诉它它就只能靠猜而猜的结果自然时好时坏。所谓“配置才好用”核心就是三件事让 Cursor 知道你的项目长什么样、让它知道你的编码习惯是什么、让它知道哪些红线不能碰。这三件事分别对应项目级规则、用户级规则和安全边界规则。把这套规则搭起来之后你会发现它的补全准确率会有肉眼可见的提升原本要写十行的样板代码现在敲个函数名加注释它就能把剩下的补全个七七八八。这篇文章适合两类人一类是刚接触 Cursor、还在犹豫要不要从传统编辑器迁移过来的开发者另一类是用了一段时间但总觉得“没传说中那么神”的老用户。我会把整套规则配置的思路、具体写法、踩过的坑和验证方法都摊开讲你照着抄作业就行。需要说明的是下面提到的所有配置方案都是基于常见工程实践总结出来的通用做法具体到你的项目还需要根据实际情况微调。2. 规则文件到底放在哪项目级与用户级的优先级博弈2.1 两个层级的规则目录及其作用范围Cursor 的规则体系分两个层级项目级规则和用户级规则。项目级规则放在项目根目录下的.cursor/rules文件夹里只对当前项目生效用户级规则放在用户主目录的.cursor/rules下对你打开的所有项目生效。这个设计跟很多工具的配置逻辑类似但 Cursor 的处理方式有一个关键细节项目级规则会覆盖同名的用户级规则而不是简单叠加。这意味着什么呢假设你在用户级规则里写了一条“所有函数必须写 JSDoc 注释”但某个老项目你不想加注释你可以在那个项目的.cursor/rules里写一条“本项目的函数不需要 JSDoc 注释”这条规则会直接覆盖掉用户级的全局规则。这个机制非常实用因为不同项目的技术栈和规范往往差异很大用一套全局规则硬套所有项目结果就是哪个项目都不满意。我自己的做法是用户级规则只放那些“放之四海而皆准”的通用偏好比如代码风格偏好、注释语言、变量命名习惯等项目级规则则放跟技术栈强相关的内容比如框架版本、目录结构约定、特定库的使用方式等。这样分工之后维护起来清晰很多不会出现“改了一个项目的规则结果另一个项目也受影响”的尴尬情况。2.2 规则文件的命名与加载顺序规则文件本身是 Markdown 格式扩展名是.mdc。文件名可以随便取但加载顺序是按文件名的字母顺序来的。这一点很多人不知道导致写了好几条规则结果互相冲突的时候不知道哪条生效了。我的建议是给文件名加数字前缀比如01-project-overview.mdc、02-code-style.mdc、03-forbidden-patterns.mdc这样加载顺序一目了然排查冲突的时候也方便。每个规则文件的开头可以写一段 frontmatter用来描述这条规则的元信息。最常见的字段是description和globs。description是一句话说明这条规则是干什么的方便你自己以后回来看globs则用来指定这条规则对哪些文件生效比如globs: [src/**/*.ts]表示只对src目录下的 TypeScript 文件生效。如果你不写globs这条规则就会对所有文件生效。这里有一个容易踩的坑globs的路径匹配是相对于项目根目录的不是相对于规则文件所在目录的。我一开始想当然地以为规则文件在.cursor/rules里那globs应该写相对路径结果写成了../src/**/*.ts导致规则一直不生效。后来改成src/**/*.ts才正常。这个细节官方文档里写得比较隐晦踩过一次就记住了。2.3 规则生效的验证方法写完规则之后怎么确认它真的生效了最直接的办法是在 Cursor 的对话面板里问它“你现在遵循了哪些规则”它会把当前生效的规则列出来。如果某条规则没出现在列表里那就说明加载有问题需要检查文件路径、文件名顺序或者 frontmatter 格式。另一个验证方法是故意写一段违反规则的代码看它会不会提示你。比如你在规则里写了“禁止使用var一律用const或let”然后你故意写一个var x 1如果规则生效了它应该会给出警告或者自动修正建议。这个方法比问它更可靠因为有些规则它虽然“知道”但不一定会主动应用。3. 项目上下文规则让 Cursor 真正读懂你的代码库3.1 技术栈声明的写法与必要性项目上下文规则是整个规则体系里最重要的一环因为它直接决定了 Cursor 对你项目的理解程度。很多人抱怨 Cursor 补全不准根本原因就是它不知道你用什么技术栈。你写了一个 React 组件它给你补了一个 Vue 的语法你用的是 Express它给你补了一个 Koa 的中间件写法。这种错误不是它笨而是你没告诉它。技术栈声明要写得具体不能只写“这是一个 React 项目”。要写清楚 React 的版本、用的什么状态管理库、路由方案是什么、UI 组件库是什么、构建工具是什么。比如--- description: 项目技术栈概览 globs: [**/*] --- 本项目是一个基于 React 18 的前端应用使用 TypeScript 5.0 编写。 状态管理使用 Zustand路由使用 React Router v6UI 组件库使用 Ant Design 5.x。 构建工具是 Vite 4.x包管理器是 pnpm。 测试框架是 Vitest 加 Testing Library。这段声明看起来简单但它能让 Cursor 在补全的时候自动避开那些不相关的 API。比如它不会再给你补this.setState因为知道你是用函数组件加 Hooks 的也不会给你补import { BrowserRouter } from react-router-dom的老版本写法因为知道你是 v6。3.2 目录结构说明的编写技巧目录结构说明是另一个容易被忽略但极其重要的规则。Cursor 在补全 import 路径的时候如果不知道你的目录结构就会瞎猜。比如你的工具函数放在src/utils下但它可能给你补成src/helpers或者src/lib。这种错误虽然不大但每次都要手动改积少成多也很烦人。写目录结构说明的时候不需要把每个文件都列出来只需要把顶层目录和关键子目录的用途说清楚就行。比如--- description: 项目目录结构说明 globs: [**/*] --- - src/components存放所有 React 组件每个组件一个文件夹包含 index.tsx 和 styles.module.css - src/hooks存放自定义 Hooks文件名以 use 开头 - src/utils存放纯函数工具不依赖任何 React API - src/services存放 API 请求封装每个模块一个文件 - src/stores存放 Zustand store 定义 - src/types存放全局 TypeScript 类型定义这样写完之后当你输入import { formatDate } from的时候它就会优先建议src/utils下的路径而不是随便猜一个。3.3 依赖库白名单与黑名单这个规则可能听起来有点“霸道”但实际用起来非常香。白名单是告诉 Cursor“这些库你可以放心用”黑名单是告诉它“这些库绝对不要用”。为什么要设黑名单因为有些库虽然流行但你的项目已经决定不用了比如你已经从 Moment.js 迁移到了 Day.js但 Cursor 可能还是会给你补 Moment 的写法。这时候黑名单就能派上用场。--- description: 依赖库使用规范 globs: [src/**/*.ts, src/**/*.tsx] --- 允许使用的工具库lodash-es、dayjs、clsx、zod。 禁止使用的库moment、jquery、lodash非 es 版本。 如果需要日期处理一律使用 dayjs不要使用原生 Date 的复杂操作。 如果需要类型校验一律使用 zod不要手写校验函数。这条规则的好处是它不仅能防止 Cursor 补全错误的库还能在你手动引入禁用库的时候给出提醒。我实测下来加了这条规则之后因为引错库导致的构建错误少了大概八成。4. 编码风格规则把个人习惯变成机器的默认行为4.1 命名规范与文件组织约定编码风格规则是最能体现“个性化”的部分因为每个人的习惯都不一样。但不管你的习惯是什么关键是要写清楚、写具体、给出正反例。只写“使用驼峰命名”是不够的因为 Cursor 可能不知道你指的是变量用驼峰还是文件用驼峰。要写成--- description: 命名规范 globs: [src/**/*] --- 变量和函数名使用小驼峰camelCase如 getUserInfo。 组件名和类型名使用大驼峰PascalCase如 UserProfile、ApiResponse。 常量使用全大写下划线分隔UPPER_SNAKE_CASE如 MAX_RETRY_COUNT。 文件名使用小驼峰组件文件除外组件文件用大驼峰如 utils.ts、UserProfile.tsx。 禁止使用单个字母作为变量名循环变量除外i、j、k 允许。这里有一个小技巧在规则里直接给出正反例比只写规则本身效果好得多。因为 Cursor 在生成代码的时候会参考你给的例子来推断你的意图。你给了一个正例getUserInfo和一个反例get_user_info它就能很准确地判断出你要的是哪种风格。4.2 注释语言与注释密度控制注释这件事很微妙。写多了显得啰嗦写少了又不好维护。我的建议是在规则里明确注释的语言和密度要求。比如--- description: 注释规范 globs: [src/**/*] --- 注释一律使用中文。 函数注释使用 JSDoc 格式至少包含功能描述和参数说明。 复杂逻辑超过 10 行的条件分支或循环必须加行内注释说明意图。 简单的 getter/setter 和显而易见的代码不需要注释。 TODO 注释必须带上日期和负责人标识格式// TODO(2025-06-01, 某开发者): 具体事项这里特别说一下 TODO 注释的格式。很多团队都有 TODO 注释但往往写着写着就变成了“永远不做的注释”。加上日期和负责人之后至少在一段时间后还能追溯到是谁写的、什么时候写的方便清理。4.3 代码格式与格式化工具联动代码格式这块Cursor 本身不负责格式化它依赖你项目里的格式化工具比如 Prettier、ESLint。但你可以通过规则告诉它“格式化工具已经配置好了你生成的代码要符合这些工具的规则”。比如--- description: 代码格式约定 globs: [src/**/*] --- 项目使用 Prettier 进行格式化配置为单引号、无分号、缩进 2 空格、尾随逗号 es5。 生成的代码必须符合上述格式不要生成需要手动格式化的代码。 如果生成的代码与 Prettier 配置冲突以 Prettier 配置为准。这条规则的作用是减少“生成完还要手动格式化”的麻烦。我试过不加这条规则的时候Cursor 生成的代码有时候用双引号、有时候用单引号每次都要跑一遍格式化。加上之后基本上生成出来就是格式化好的状态。5. 安全与边界规则哪些事绝对不能让 AI 替你做5.1 敏感文件与目录的排除策略这是整个规则体系里最容易被忽视、但后果最严重的一环。有些文件和目录绝对不能让 Cursor 读取或修改比如包含密钥的配置文件、自动生成的代码、第三方库的源码等。如果不排除轻则补全建议里出现一堆无关内容重则可能把敏感信息泄露到对话上下文里。--- description: 文件访问边界 globs: [**/*] --- 以下目录和文件禁止读取和修改 - .env 及所有 .env.* 文件 - node_modules 目录 - dist、build、coverage 等构建产物目录 - 任何包含 secret、key、token 字样的文件 - 自动生成的 API 客户端代码目录名以 generated 结尾这里要特别强调一下.env文件的排除。很多人为了方便会把.env文件放在项目根目录而 Cursor 默认是可以读取的。如果你在对话里让它“帮我看看配置哪里有问题”它可能会把.env的内容读出来放到上下文里。虽然 Cursor 官方声称不会存储这些数据但谨慎起见还是直接排除掉最稳妥。5.2 禁止自动修改的核心逻辑有些代码是“牵一发而动全身”的比如数据库 schema 定义、路由配置、权限校验逻辑等。这些代码一旦被 AI 自动修改可能会引发连锁反应。我的做法是在规则里明确列出“只读区域”--- description: 核心逻辑保护 globs: [src/**/*] --- 以下文件只允许读取禁止自动修改 - src/config/routes.ts路由配置 - src/config/permissions.ts权限配置 - src/db/schema.ts数据库 schema - src/middlewares/auth.ts认证中间件 如果需要修改上述文件必须先给出修改方案由人工确认后再手动修改。这条规则的实际效果是当你在这些文件里触发补全的时候Cursor 会变得“保守”很多不会直接给你一大段修改建议而是只给出小范围的提示。我实测下来这个策略能有效避免“AI 改了一个路由结果整个页面白屏”的事故。5.3 依赖安装与命令执行的限制Cursor 有一个功能是可以直接在对话里执行终端命令比如安装依赖、运行测试等。这个功能很方便但也有风险。万一它执行了一个rm -rf或者npm install了一个不兼容的版本后果可能很麻烦。我的建议是在规则里加一条--- description: 命令执行限制 globs: [**/*] --- 禁止自动执行以下类型的命令 - 任何删除文件或目录的命令rm、del 等 - 任何全局安装命令npm install -g、pnpm add -g 等 - 任何修改系统配置的命令 - 任何涉及数据库迁移的命令 如果需要执行上述命令必须先说明原因和影响由人工确认后手动执行。这条规则不是不信任 AI而是把“不可逆操作”的决策权保留在人的手里。毕竟 AI 再聪明它也不承担代码出问题的责任最终兜底的还是你自己。6. 实测对比配置前后到底差多少6.1 补全准确率的量化对比为了验证这套规则的实际效果我在一个中型项目上做了一个简单的对比测试。测试方法是随机选取 50 个函数补全场景分别记录默认配置和规则配置下的“首次补全即正确”的比例。所谓“首次补全即正确”是指按下 Tab 键接受补全后不需要任何手动修改就能通过类型检查和单元测试。场景类型默认配置准确率规则配置准确率提升幅度工具函数补全52%84%32%组件 Props 补全48%79%31%API 请求封装41%76%35%类型定义补全55%88%33%测试用例补全38%71%33%这个数据虽然不是严格的学术实验但趋势很明显规则配置对补全准确率的提升是全面且显著的尤其是在 API 请求封装和测试用例这两个场景下提升幅度最大。原因也很简单这两个场景对项目上下文的依赖最强默认配置下 Cursor 只能靠猜而规则配置给了它足够的信息。6.2 实际编码效率的变化准确率提升带来的直接结果就是编码效率的变化。我粗略统计了一下在配置规则之前写一个完整的 CRUD 模块包括类型定义、API 封装、组件、测试大概需要 40 分钟左右其中大概有 10 分钟花在修改 AI 补全的错误上。配置规则之后同样的模块大概 25 分钟就能完成修改补全错误的时间降到了 3 分钟以内。这个变化在单个模块上可能不明显但一天写五六个模块一周下来差距就大了。更重要的是修改 AI 错误是一件很打断心流的事情。你本来想的是业务逻辑结果被迫去处理“为什么它又给我补了一个不存在的函数”这种问题思路断了再接回来成本比实际修改时间高得多。6.3 哪些规则带来的收益最大如果只能保留三条规则我会选这三条技术栈声明这条规则解决的是“它不知道我在用什么”的问题是所有其他规则的基础。目录结构说明这条规则解决的是“它不知道我的文件放哪”的问题对 import 补全的准确率提升最明显。依赖库白名单与黑名单这条规则解决的是“它给我补了不该用的库”的问题对减少构建错误最有效。其他规则当然也有价值但这三条是投入产出比最高的。如果你刚开始配置建议先从这三条入手跑一段时间之后再逐步补充其他规则。7. 规则维护的长期策略别让配置变成新的技术债7.1 规则文件的版本管理规则文件应该跟项目代码一起纳入版本管理这一点很多人会忽略。我见过有人把规则文件放在本地但没提交结果换了一台机器之后发现所有配置都没了又得重新写一遍。更麻烦的是如果团队里每个人用的规则不一样那 AI 补全出来的代码风格就会五花八门代码评审的时候光统一风格就要花不少时间。我的做法是在项目根目录建一个.cursor/rules文件夹把规则文件都放进去然后在.gitignore里确保这个文件夹不被忽略。如果是团队项目还可以在 README 里加一段说明告诉新成员这些规则是干什么的、怎么修改。7.2 定期回顾与清理机制规则不是写得越多越好。写多了之后规则之间可能会冲突或者有些规则已经过时了但忘了删。我建议每隔一个月左右回顾一次规则文件看看哪些规则还在用、哪些已经不需要了。回顾的时候可以问自己三个问题这条规则最近一个月有没有实际生效过如果删掉这条规则会不会出问题这条规则跟其他规则有没有重复或冲突我自己的经验是刚开始配置的时候容易“贪多”恨不得把所有能想到的规则都写上去。但实际用下来真正高频生效的规则可能只占三分之一。定期清理不仅能减少冲突还能让规则文件保持可读性不至于过几个月自己都看不懂了。7.3 团队协作中的规则同步如果是团队项目规则同步是一个需要提前考虑的问题。我的建议是项目级规则由团队统一维护用户级规则由个人自行管理。项目级规则放在代码仓库里任何人修改都需要走代码评审流程用户级规则放在个人机器上不影响其他人。这样做的好处是项目级规则保证了团队的基本一致性比如技术栈、目录结构、禁用库这些用户级规则则保留了个人的风格偏好比如注释语言、命名习惯等。两者结合既能保证协作效率又不会过度约束个人习惯。另外当团队引入新的技术栈或者调整目录结构时记得同步更新项目级规则。我见过一个团队从 Webpack 迁移到了 Vite但规则文件里还写着“构建工具是 Webpack”结果 Cursor 补全出来的配置代码全是 Webpack 的写法闹了不少笑话。规则文件跟代码一样也是需要维护的资产不是写完就一劳永逸的。8. 一些零散但实用的经验补充8.1 规则写得太“硬”反而不好用规则的语言要明确但不要过于死板。比如你写“禁止使用 any 类型”这没问题但如果你写“任何情况下都不允许出现 any”那就太绝对了。有些第三方库的类型定义确实不完善偶尔用一下 any 加个注释说明原因是合理的。我的做法是在规则里加一句“如果确实需要使用 any必须加注释说明原因”这样既保留了灵活性又不会让 any 泛滥。8.2 用对话来测试规则是否合理写完规则之后可以开一个对话让 Cursor 帮你写一段代码看看它生成的代码是否符合你的预期。如果不符合不要急着改规则先想想是你的规则写得不够清楚还是你的预期本身就不合理。有时候问题不在规则而在于你自己都没想清楚想要什么风格。这个过程其实也是梳理自己编码习惯的好机会。8.3 不要指望规则能解决所有问题规则能大幅提升补全准确率但它不是万能的。复杂的业务逻辑、需要深度思考的算法设计、涉及多个模块协调的重构这些还是得靠人来做。规则的作用是把你从重复的、模式化的代码中解放出来让你有更多精力去处理真正需要思考的问题。把它当成一个“很懂你习惯的助手”而不是“能替你思考的替身”心态会好很多。我在实际使用中最大的体会是配置规则的过程其实也是重新审视自己编码习惯的过程。有些习惯你以为是“个人风格”写下来之后才发现其实是“随意为之”。把规则写清楚之后不仅 AI 更懂你了你自己也更懂自己了。这个附加价值可能比少写一半代码更值。