★ FEATURED ARTICLE 很多人在 Cursor 里写完.cursorrules之后发现 AI 助手还是我行我素目录结构搞错、命名风格混乱、改 A 文件时不看 B 文件的约定。明明写了规则怎么就跟没写一样这个问题的根源往往不是 Cursor 不行而是规则文件本身没写到点子上。我花了不少时间把.cursorrules从“摆设”调成真正能约束 AI 行为的配置最后沉淀出一套模板核心思路就八个字不写废话只给指令和上下文。这篇文章把这套模板完整拆开包含设计思路、可直接复制的规则文件、以及我踩过坑之后总结的排查清单。如果你正在被“AI 写得不合心意”折磨这篇内容大概能省下你不少调参时间。1. 先搞清楚.cursorrules到底怎么生效为什么你写了没用1.1.cursorrules的生效逻辑说到.cursorrules得先说它的工作原理。Cursor 本质上是一个把大模型能力嵌进编辑器的 IDE它每次生成代码、修改文件、回答问题时都会把一部分“上下文”放进提示词。.cursorrules这个文件就放在你的项目根目录里作用是让 Cursor 在启动对话、执行代码任务时自动读取文件内容把它当作系统级提示词的一部分。也就是说你在这个文件里写的每一条约定都会直接影响 AI 理解项目的方式。它不像普通的README.md那样只是给人看的文档也不是装饰性的配置文件而是真正参与每一次 AI 调用的“潜在上下文”。但这里有个容易忽略的关键点.cursorrules不是越大越好也不是写得越多越有效。每次调用时模型的上下文窗口是有限的这个文件占用的篇幅越多你的项目代码和其他有效信息能塞进去的空间就越少。不少人写出来的.cursorrules动辄几百行AI 真正能“消化”的其实只有开头一小部分后面那些细则反而被当成噪音忽略掉了。这个现象我给它起了个名字叫“规则稀释”——规则写得太多太杂真正重要的那几条就被淹没在文字里了。这也是为什么很多人抱怨“写了等于没写”。1.2 “写了等于没写”的四个典型原因结合我自己和身边朋友的实际经历.cursorrules失效基本逃不出下面四个原因。第一规则写得太泛。比如“请写出高质量的代码”“请遵循最佳实践”“注意代码的可维护性”——这种话等于没说。AI 对“高质量”的理解跟你对“高质量”的理解可能完全不是一回事。你要的是“错误处理完整、日志清晰、不嵌套超过三层”AI 理解的高质量可能只是“注释写得多一点”。第二只有“不要”没有“要”。比如你写“不要使用any”“不要用var”“不要复制粘贴重复代码”这些负面清单确实能挡住一部分行为但 AI 不知道你希望它用什么替代方案。光写“不要用var”不如后面补一句“统一使用const和let优先选const”。负面规则必须配上正面指令否则 AI 会陷入“我不知道该怎么写更好”的窘境最后给你一个四不像的妥协方案。第三缺少架构地图。.cursorrules里没有告诉 AI 项目有哪些模块、每个模块负责什么、文件如何组织。结果就是 AI 想找配置文件的存放位置直接在新路径上新建了一个想把工具函数放进utils目录结果放到了helpers目录。它不是在偷懒是真的不知道你们项目的组织方式。第四规则从不更新。项目从开始到上线目录会调整、命名规范会变化、依赖会升级。.cursorrules如果从一开始就没再改过那它描述的项目状态和实际项目状态就脱节了。AI 依照一份过期的“地图”做事自然处处踩坑。注意.cursorrules是旧版 Cursor 使用的文件格式新版 Cursor 推荐使用.cursor/rules/*.mdc。但.cursorrules仍然会被兼容读取而且它的结构简单、适合作为单一模板使用所以我下面的方案以它为基础同时也会介绍如何迁移到新版规则目录。2. 模板设计的核心思路让 Cursor 像资深同事那样理解项目2.1 两条腿走路约束型规则与信息型规则我把有效的规则内容分成两大类约束型规则Constrain Rules和信息型规则Context Rules。约束型规则指的是“AI 必须做什么、禁止做什么、优先选择什么方案”。它直接限制模型的输出行为。比如“所有函数必须写返回类型”“禁止使用any”“错误处理统一走handleError函数”——这一类规则的特点是命令式、可检验、不能模棱两可。信息型规则指的是“这个项目是什么、用了什么、目录怎么分层、业务术语是什么”。它不直接命令 AI而是给 AI 提供判断依据。比如“本项目是一个面向门店商家的订单管理系统”“前端使用 Vue 3 Composition API”“customerId和userId是两个不同的概念前者是客户资料主键后者是登录账号主键”——这类规则帮助 AI 理解项目的“潜台词”。好的.cursorrules必须同时包含这两类。只有约束没有信息AI 会机械地执行命令但在不理解项目背景时做出错误假设只有信息没有约束AI 会发挥想象力给你写出结构漂亮但不符合项目实际约定的代码。我习惯用一张简单的公式来提醒自己让 AI 表现好不是靠“管制”而是靠“理解 限制”。理解和限制缺一不可。2.2 好规则的三条检验标准你写完一条规则后先别急着继续写下一条拿三个问题检验一遍。第一条这条规则能不能直接改变 AI 的输出如果一条规则无论存不存在AI 生成的结果都差不多那它就是无效规则。举个例子“请注意代码的可读性”——有它没它AI 的表现几乎没有区别。但“函数内不超过 3 层 if 嵌套超出的请拆分为独立函数”——这条就能直接改变 AI 的输出结构。判断标准很简单把你写的规则遮住想象不告诉你这条信息时 AI 会怎么做。如果两个结果差异明显说明它有效如果毫无差别赶紧删掉。第二条这条规则有没有给出“为什么”很多人写规则只写“应该怎么做”不写背景。但模型理解规则时如果知道背后的原因执行起来会灵活得多。比如“不要直接修改共享组件因为会被多个页面复用”——AI 在遇到具体情境时就能自己权衡这个组件是不是共享的如果是就绕开。第三条这条规则好不好更新项目演进后规则文件要能轻松跟着改。所以模板里我特意加了一个“更新日志”区块每次调整规则时记录一下改了什么、为什么改。这样几个月后回看时能快速理解某个规则为什么存在不会误删关键约束。2.3 模板的 8 个区块设计经过反复折腾我把.cursorrules的结构固定成了 8 个区块每个区块定位清晰互不干扰。项目总览用三到五句话说明项目是什么、服务谁、核心业务目标是什么。技术栈与版本约束列出后端语言、前端框架、依赖管理工具、关键库版本。目录结构与架构地图写明已有哪些目录各自放什么类型的文件不允许新建什么目录。代码风格与命名约定变量、函数、组件、文件、常量、枚举、类型的命名规则。核心业务术语与概念项目里特有的术语以及容易混淆的概念辨析。工作流偏好AI 执行任务时的行为偏好比如先分析再动手、不要修改未提及的文件。禁止事项与硬约束强负面清单每条最好附带替代方案。变更记录记录本文件的更新历史方便追踪。这 8 个区块不是越多越好而是恰好覆盖了 AI 在项目协作中最容易犯错的几个面。你可以根据项目类型增删但至少前四个区块建议保留。3. 一套可直接抄的.cursorrules模板3.1 基础版模板通用型下面这套模板是基于我自己项目的实际配置脱敏后的通用版覆盖了最常见的 Web 全栈项目场景。直接复制以后把中括号里的内容替换成你项目的真实信息就行。# 项目Web 端订单管理后台 ## 1. 项目总览 - 本系统面向门店商家提供订单查看、商品管理、数据报表功能。 - 前端使用 Vue 3 TypeScript Vite后端使用 Node.jsNestJS PostgreSQL。 - 核心业务目标是让商家在移动端快速处理日常订单操作后台不涉及 C 端用户操作。 ## 2. 技术栈与版本约束 - 前端框架Vue 3.4使用 script setup 语法禁止 Options API。 - 状态管理Pinia禁止引入 Vuex。 - 后端NestJS 10数据库访问使用 Prisma ORM。 - 样式方案Tailwind CSS CSS Modules禁止使用其他 UI 组件库。 - 包管理器pnpm禁止在提交代码中出现 package-lock.json 或 yarn.lock。 ## 3. 目录结构与架构地图 - src/api/所有后端接口请求方法禁止直接在前端页面写 fetch/axios 调用。 - src/components/公共组件必须支持多场景复用禁止写死业务数据。 - src/features/业务模块代码按订单、商品、报表等业务域划分。 - src/utils/纯函数工具库禁止包含任何业务逻辑和状态依赖。 - src/types/全局类型定义接口请求参数和响应类型统一维护在此。 - 后端 prisma/schema.prisma所有数据模型定义修改表结构必须同步更新此文件。 - services/NestJS 业务逻辑层禁止在 controller 中写复杂业务逻辑。 ## 4. 代码风格与命名约定 - 变量名使用 camelCase组件名使用 PascalCase文件名使用 kebab-case。 - 常量使用 UPPER_SNAKE_CASE枚举使用 PascalCase 且成员使用 UPPER_SNAKE_CASE。 - 所有 TypeScript 函数必须显式标注返回类型禁止依赖类型推导。 - 接口类型命名以 Response 结尾表示响应类型以 Params 结尾表示请求参数类型。 - 布尔变量统一使用 is/has/can 前缀例如 isVisible、hasPermission。 ## 5. 核心业务术语与概念 - customerId 与 userId 是不同概念customerId 是商家门店下的客户主键userId 是系统登录账号主键。 - orderStatus 涉及的状态流pending - paid - shipped - completed - cancelled。 - 报表模块中的“日销售额”按支付时间统计不是按下单时间统计。 - 商品 SKU 与 SPU 概念区分SPU 是商品抽象SKU 是具体可售规格。 ## 6. 工作流偏好 - 在修改代码之前先阅读相关文件现有实现再开始编码。 - 如果发现现有实现存在缺陷不要擅自修改先在回复中说明问题由我确认后再改。 - 一次只完成一个任务不要在一个回合中主动重构无关代码。 - 生成新文件时优先复用现有目录下的同类文件作为模板。 ## 7. 禁止事项与硬约束 - ALWAYS使用 TypeScript 严格模式禁止使用 any。如果确实无法推断类型使用 unknown 并配合类型收窄。 - NEVER直接修改 src/api/ 之外的代码去绕过接口层所有请求必须经过 api 模块。 - NEVER在组件内直接操作 Pinia store 中的数组做 filter/sort应使用 store getter。 - NEVER把函数定义写在 .vue 文件的长文件末尾超过 200 行的组件要拆分子组件。 - ALWAYS日志输出必须使用项目封装的 logger禁止 console.log 残留。 ## 8. 变更记录 - 2024-01-10新增报表统计口径说明避免 AI 混淆下单时间和支付时间。 - 2024-01-15明确禁止直接操作 store 数组过滤统一走 getter。这里每一块的措辞我都反复调过看起来简短但每句话都有它的“埋伏”——都是为了纠正 AI 在真实操作中反复出现的错误行为。3.2 模板中的“硬约束”写法很多人写规则时喜欢用“请”“建议”“尽量”这类词。这些词在写给人看的文档里没问题但写给 AI 的配置里它们的约束力会大打折扣。我给规则里加了一套“强弱标记体系”用明确的词汇区分优先级ALWAYS必须遵循没有例外。例如“ALWAYS 使用const声明变量”。NEVER绝对禁止没有例外。例如“NEVER 在组件中直接发起 HTTP 请求”。PREFER优先选择除非有明确理由才能打破。例如“PREFER 使用组合式函数复用逻辑”。AVOID尽量避免如果出现需要说明原因。例如“AVOID 在模板中写超过一行的复杂表达式”。这套标记之所以有效是因为它降低了模型的“自由裁量权”。AI 在面对模糊指令时倾向于发挥创造力但当你用ALWAYS/NEVER这种近乎命令式的表达时它更倾向于严格遵循而不是自作主张。但要注意一个细节不要每一条都用ALWAYS或NEVER。如果整份文件全是最高优先级约束模型会把它当成一种“压力提示”来处理——你也不希望 AI 因为规则太硬而变得畏手畏脚连正常的重构都不敢做。我的经验是一份 30 条左右的规则里ALWAYS/NEVER占三分之一PREFER占三分之一剩下的留给上下文描述型规则。3.3 针对不同技术栈的快速变体这套模板不是写死只能用在 Web 项目上。换项目类型时只需要调整第 2 和第 3 区块剩下的架构可以复用。我实际用下来下面几个变体效果不错。Python 后端项目的调整点把目录结构改成src/、tests/、app/api/、app/services/这类布局命名约定改成 snake_case增加“禁止类型标注使用Any用Optional或Union表达可空类型”这类约束。移动端项目的调整点强调 UI 组件的复用边界、页面路由的组织方式、状态管理选型增加“所有图片资源必须放在assets/images/并按模块建子目录”“禁止硬编码颜色或尺寸值必须引用设计 token”。Monorepo 项目的调整点目录结构部分要写清楚每个包package的职责明确“跨包引用必须走包的对外导出入口禁止直接引用其他包的内部文件路径”。换项目时最忌讳的就是直接复制一份旧的.cursorrules只改个项目名。技术栈变了、目录结构变了但第 2、3 区块还写着旧项目的内容AI 就会拿着旧地图找新路结果比不写规则还糟——至少不写规则时它走了错路你敢怀疑写了错规则你还以为它是对的。4. 模板用起来才能久测试、迭代与配合其他配置4.1 如何验证.cursorrules是否生效写完之后怎么知道这套规则真的被 AI “吸收”了直接问它一次就知道了。我建议的验证方式新开一个对话不要带任何代码选中直接问 Cursor 几个问题。第一个问题“介绍一下这个项目的目录结构以及每个目录应该放什么内容”如果规则生效AI 会按照你写在第 3 区块的内容准确复述甚至能说出“src/features/按业务域划分”这种细节。如果它回答得含含糊糊或者提到了你项目里根本不存在的目录说明规则文件的读取或解析有问题。第二个问题“给这个项目新增一个导出订单报表的功能你会先看哪些文件”如果规则生效AI 的回答应该涉及src/api/下的请求方法、services/的业务逻辑、可能的 schema 修改。如果它只是泛泛地说“我会找到相关代码然后修改”说明你的规则没有成功注入。第三个问题“列出修改代码时你一定会遵守的三个规则。”这个提问几乎就是“考试题”AI 答不上来或者答偏了说明.cursorrules里的硬约束没有起到应有的作用。这三个问题测完基本就能判断规则文件是否正常工作了。如果回答不理想优先检查文件编码、文件位置、有没有被其他配置文件覆盖。注意.cursorrules修改后必须新开对话才能生效。Cursor 在会话中不会动态重新读取规则文件你改了文件后继续在旧对话里测试大概率会得到“没变”的错误结论。4.2 与.cursor/rules/多文件规则的分工Cursor 新版引入了.cursor/rules/目录支持按文件组织规则还能给每个规则文件单独配置适用场景例如仅对代码自动补全生效或仅对 Chat 生效。这就产生了一个分工问题到底是坚持用.cursorrules单文件还是迁移到多文件我的实践经验是两者可以并用前提是分工清晰。.cursorrules适合放“项目级全局约束”和“架构级上下文”也就是这个项目无论聊什么、写什么代码都必须遵循的背景信息。比如技术栈约束、目录结构、核心术语这些内容适用于所有场景放进全局文件最省事。.cursor/rules/*.mdc适合放“场景专用规则”。比如你给代码审查单独写一份规则要求 AI 每次评审变更时从错误处理、性能、可读性三个维度打分——这份规则就不需要每次写代码时都加载只在审查场景激活就行。用 mdc 文件还可以在前面加 frontmatter 配置 glob 匹配范围做到“这个规则只对src/features/order/**下的文件生效”。从.cursorrules迁移到.cursor/rules/时我建议这样拆分全局配置项技术栈、命名、禁止事项保留在.cursorrules或建立一个global.mdc。弹窗会话相关的行为偏好放到chat.mdc。代码自动补全相关的缩进、换行、注释风格放到autocomplete.mdc。某个业务模块特有的约束放到该模块对应的rule文件里。这个组合方式的好处是AI 加载上下文时更有针对性不会把用不上的规则也一块塞进来占空间。代价就是需要花点时间维护多份文件对于团队项目来说这个成本是值得的。4.3 更新策略把规则当成活文档而不是一次性配置我发现一个很有意思的现象大部分人的.cursorrules写完之后就再也不改了。项目重构、目录调整、技术栈升级规则文件却停留在三个月前。这种“一次性配置”心态是规则失效的隐形杀手。AI 会忠实地按照规则描述去理解项目但它不会自己去核对“项目现在是否还长这样”。所以你需要像维护 README 一样维护.cursorrules甚至更勤快——因为它直接影响生成质量。我的更新策略是“随改随记”每次 AI 在某个方面系统性出错比如连续三次把报表计算口径搞错就检查规则文件里对应位置是否缺失或表述不清。凡是项目结构调整第一时间同步更新第 3 区块目录地图。第 8 区块的变更记录每次只加一行注明日期和改动原因。别小看这一行它能帮你在几周后快速定位“这条规则是当时为了解决什么场景加的”。这套策略看着费事实际操作起来十分钟都用不到但可以避免“规则与项目脱节”这个最隐蔽的问题。5. 常见问题与排查技巧实录5.1 常见问题速查表下面的表格来自我自己以及身边同事踩坑的记录按出现频率排序。现象可能原因排查方法解决方案修改.cursorrules后没变化在旧会话中继续测试新开对话再测试记住改规则后必须新开会话AI 回复时说“我没有找到这个文件”文件位置不对或文件名有误检查项目根目录是否存在隐藏文件确认文件名为.cursorrules位于项目根目录规则偶尔生效、偶尔无视规则行数太长上下文被截断查看文件总行数精简内容拆到.cursor/rules/AI 把目录结构说错第 3 区块描述太笼统让 AI 复述目录结构补充各目录职责和禁止内容AI 忽略NEVER类硬约束写的是“最好不要”这种弱表达检查规则用词统一用NEVER/ALWAYS强标记生成代码不遵守命名规则混杂在项目总览里AI 没注意到让 AI 说出命名规则将命名单独成块并放在文件前部规则和现有代码风格冲突规则内容照搬了其他项目对比现有代码用现有代码风格反向修正规则团队协作时规则被覆盖每个人有各自的全局规则检查 Cursor 全局设置统一团队规则项目规则不放在用户目录遇到问题先按表格里“排查方法”列的操作做一遍大部分情况都能快速定位。如果还是不行删掉一半规则再测试——每次只保留 10 条核心规则往往反而比 30 条全量规则效果更好。这是个反直觉的结论但我实测过很多次规则精简后 AI 的遵循率明显上升。5.2 避坑心得写规则文件时的三个“不要”不要堆砌技术名词清单。比如“本项目使用 Vue 3、TypeScript、Pinia、Vite、Tailwind”这种写法太浅了。AI 知道这些技术栈都有什么基础能力但它不知道你的项目是怎么用这些技术栈的。关键是写出“使用方式约束”比如“Pinia 只用来管理全局用户状态组件内部状态用 ref”这句话就比“使用 Pinia”有用十倍。不要复制大段代码进规则文件。有人喜欢把一段“规范示例”直接贴进.cursorrules希望 AI 照着写。结果就是上下文被这段代码占掉大量空间而且 AI 复制回来时还会因为缩进、命名细节问题产生偏差。代码示例可以放但只放“迷你片段”一两行即可目的是说明规范不是给 AI 当模板库。不要用你团队内部才懂的缩写。见过一个项目在规则里写“所有请求必须走 GLP 层”AI 反复犯错后来发现 GLP 是“Global Logic Process”的缩写团队文档里写了但 AI 从没读过那份文档。规则文件的第一个原则就是自我包含你想要的约定都应该在文件里说清楚不能让 AI 去猜你的内部黑话。5.3 终极技巧给你的.cursorrules写一份“配套说明书”最后分享一个我自己用着特别顺手的技巧在项目里再写一份简短的README.cursor.md面向 AI 或者新加入项目的开发者解释.cursorrules里每条规则背后的“为什么”。这样做有两个好处。第一个好处是当你半年后回来看这份规则不会因为当时没记录原因而删掉一条其实很重要的约束。人都有这个毛病——看不懂的老规则就先删了再说删完才发现 AI 在某个场景又开始犯错了。第二个好处更实际新团队成员加入时如果他想调整.cursorrules先读一遍说明书就能理解设计意图不至于乱改。尤其是团队项目规则文件不能只有你一个人看得懂。这份配套说明书不用太长格式也很自由。我会按区块记录“这个规则的来源”比如“2024-01-10 加报表日销售额按支付时间统计因为财务结算用的是支付时间误用下单时间会导致月末对账差异”。就这么一句话就把规则的背景和理由讲清楚了。做完这一步你的.cursorrules才算真正从“写了没写”变成了一件团队资产。说回到最开始的痛点——很多人抱怨 Cursor 不够聪明、生成的代码总是不合心意其实问题往往出在沟通协议上。.cursorrules就是你跟 AI 之间的沟通协议协议写得好不好直接决定了 AI 对你的项目有没有正确的“脑内模型”。我调试这套模板这么长时间最大的体会是AI 协作不需要你讨好它也不需要你防备它只需要你把话说清楚、把约束亮明白、把上下文交代完整。做到这三点Cursor 就能从一个“啥都会一点的实习生”变成一个“懂你项目规矩的老同事”——而这一切的起点不过是一个写得用心的.cursorrules文件而已。
阅读完成 · 觉得有帮助？
