我最早用 Cursor 的时候以为只要把需求描述清楚它就能自动把活干完。结果用了两周就发现同一个功能今天生成的代码和昨天生成的代码风格能差出两个项目组偶尔还会把项目里早就废弃的工具类翻出来用。后来我才明白问题不在模型在于我没有给它一套固定的“工作约定”。这套约定就是 Cursor 里的规则配置。把规则配好之后我的重复性描述少了返工少了脚手架代码也少了整体书写量肉眼可见地降下来。这篇文章就围绕我的配置思路展开从规则机制讲到具体模板再讲怎么排查规则不生效的问题。1. 为什么默认配置会“答非所问”规则机制的原理解读1.1 规则在提示词链条中的位置先讲一个容易忽略的事实Cursor 并不是直接把你的对话框内容丢给模型。它会把项目里的相关文件、编辑器当前打开的文件、选中代码、最近改动内容以及你配置的规则一起拼装成一个上下文。这个上下文才是模型真正看到的东西。换句话说规则是你在每一次对话开始之前就能预先塞进模型脑子的那部分指令。这个位置很关键。它意味着规则不是普通提示词而是比你在对话框里临时输入的内容更稳定、优先级更高的存在。模型在生成代码时会优先遵循规则里的约束再去响应你这一次的具体要求。所以规则写得好不好直接决定了模型是“一个熟悉你项目风格的协作者”还是一个“每次都要重新认识的临时工”。我见过很多人把规则写得像个人简介比如“你是一个有用的编程助手”。这句话不是没有用而是信息量太低。规则真正要承担的任务是把你的技术栈、代码风格、边界约束、交付格式全部前置让模型在开跑之前就进入状态。1.2 全局规则、项目规则与会话说明的三层关系Cursor 的规则大致分成三层理解这三层的关系才知道每条内容该放在哪里。第一层是全局规则也就是账号级别的配置对所有项目生效。我一般只放那些跨项目都不变的底线要求比如“不要伪造测试结果”“不要删除用户没有明确要求删除的代码”“不要使用不存在的依赖包版本”。这类规则不涉及具体业务属于通用行为约束。第二层是项目规则通常放在项目的.cursorrules文件里或者通过项目设置单独维护。这一层才是我真正花精力写的地方。它包含当前项目的技术栈、目录结构、命名习惯、后端接口风格、组件写法等只对这个仓库生效。第三层是会话内临时指令也就是每次对话时你随手写在对话框里的说明。这一层的优点是灵活缺点是每次都要重复写。我的习惯是同一句话如果我说了三次以上就把它沉淀到项目规则里。反复手打指令本质上就是在浪费每一分钟的对话时间。这三层的优先级大致是会话内指令 项目规则 全局规则。临时指令可以覆盖规则中的部分约束这也是调试规则时常用的手段。1.3 写规则前必须想清楚的一个问题在动笔写规则之前要先回答一个问题你希望规则帮你节省的是哪一类重复劳动不同的人答案完全不同。我主要做业务系统最痛的点是“每次都要跟模型解释项目里的技术约定”比如接口封装方式、状态管理规范、组件目录划分。所以我的规则重点放在描述项目约定上。如果你主要做开源库或算法工程你的规则重点应该放在代码风格、性能约束和测试覆盖上。规则不是越多越好。写得过细模型反而会在无关紧要的地方反复纠结。写得过粗等于没写。我自己的经验是先列出过去两周你在对话里重复说过的话再从中挑出跟代码规范、项目约定、交付格式相关的内容这些才是规则应该收纳的东西。2. 基础配置清单花十分钟把编辑器和模型调到合适状态2.1 模型选择快模型和慢模型要分工规则写得再好模型选不对也一样白搭。Cursor 里通常会有多个模型可选我把它们简单分成两类快模型和慢模型。快模型适合做小步修改比如重命名一个变量、调整一段函数的参数、补一条注释。这类任务上下文需求少响应速度更重要用普通模型就够。慢模型适合做需要综合判断的任务比如“重构整个表单的校验逻辑”“从零实现一个带权限的页面”。这类任务需要充分理解项目结构所以我通常会把规则开启并把完整上下文交给慢模型来处理。我见过不少人从头到尾只用一个模型结果小修改也等半天大任务又经常浅尝辄止。模型选择本身也是配置的一部分。它不直接减少代码量但能减少你等待和重写的时间间接就是在省代码。2.2 上下文设置与索引管理Cursor 的代码索引是个容易被忽略但影响巨大的配置项。简单来说索引决定了模型在生成代码时能“看到”哪些项目文件。如果你没有做任何排除模型会把node_modules、构建产物、锁文件等一堆无关文件也纳入上下文范围既浪费上下文窗口又可能让模型被无关代码带偏。我会在项目里维护一份类似.cursorignore的文件把依赖目录、构建输出目录、日志目录都排除掉。这样做的直接收益是模型给出的代码更聚焦当前业务模块而不是偶尔参考一些第三方包的内部实现生成出风格怪异的东西。另外建议把当前工作区的根目录设置清楚。很多人的项目是 monorepo 结构如果根目录切错了规则相对路径、文件搜索范围都会出问题。我最早吃过这个亏规则明明写了“前端代码在apps/web”但模型经常去改packages底下的公共模块后来才发现是工作区根目录选错了。2.3 我建议打开和关闭的选项2.3 我建议打开和关闭的选项Cursor 里有些选项默认状态不一定适合所有人。我按自己的使用习惯列了一份开关清单仅供参考。首先我会尽量开启“自动补全接受前预览”。这个选项能让你在按 Tab 之前看清模型将要插入的代码避免误接受一段不符合预期的内容。关闭状态下补全体验很流畅但容易在毫无察觉的情况下把坏代码灌进文件里。其次是“代码评审自动附加上下文”。我建议关闭默认状态改成按需触发。原因很简单不是每一次重构都需要全库级别的上下文关闭这个开关可以避免小改动也被塞入大量无关文件。还有“保存时自动修复”这类选项。我通常不开启自动修复而是让 AI 在对话里给出修复建议由我确认之后再改动。自动执行看起来很省事但一旦规则里写了“未经确认不得修改关键模块”自动修复就很可能和这条约束打架。3. 一套可以直接抄走的基础规则模板3.1 规则文件的基础结构我的项目规则一般长这样# 角色 你是一名资深前端工程师负责本项目业务功能开发。 # 技术栈 - 框架React TypeScript - 状态管理Zustand - 样式CSS Modules - 请求基于 axios 的封装统一走 src/api 下的模块 # 通用约束 1. 所有类型必须显式声明禁止出现隐式 any。 2. 新代码必须保持现有目录结构不要新建无意义的顶层目录。 3. 错误处理必须以统一错误对象返回不得直接 console.error 后继续执行。 4. 不要修改 src/api 层之外的代码除非用户明确要求。 # 输出格式 1. 先列出需要改动或新增的文件清单。 2. 再给出关键代码块并简要说明改动原因。 3. 最后给出本地验证方式或单测命令。这套结构看起来简单但它是经过几轮迭代才定下来的。最早我把技术栈和约束混在一起写结果模型经常只看开头就开跑把后面的约束漏掉。后来我改成“角色—技术栈—约束—输出格式”四段式效果稳定很多。原因也好理解模型在长文本里更擅长按标题块取内容分块越清晰命中率越高。3.2 前端项目规则示例前端项目的规则比通用模板更容易踩坑因为前端技术选型太杂。同样一个 Vue 项目有人用组合式 API有人用选项式 API有人还混着用。你不写清楚模型就会随机发挥。我的前端规则会补充这些内容# 组件规范 - 组件文件统一放在 src/components 下按业务域建子目录。 - 函数组件必须使用 hooks 实现状态逻辑禁止使用 class 组件。 - 样式类名采用 BEM 风格禁止内联 style。 - 状态提升规则兄弟组件共享状态时统一提升到最近的父级容器组件。 # 接口调用 - 所有接口调用必须通过 src/api 下的函数导出禁止在组件里直接写 axios 请求地址。 - 接口返回值需要先定义类型再在业务代码中使用。 - 新增接口需要在 src/api/interface.ts 中补充对应类型声明。这些条目看起来啰嗦但它们解决的是真实痛点。我之前遇到最典型的情况是让模型加一个列表页它直接在当前组件里写了fetch(/api/list)还顺手把 loading 状态写死。加了接口调用规范之后模型会主动去src/api下找现成的请求函数代码风格立刻贴合项目现状。3.3 后端项目规则示例后端项目的规则重点不太一样我更关注分层边界、数据校验和事务处理。下面是我在一个服务端项目里用过的规则片段# 分层约束 - Controller 只做参数接收和响应包装不写业务逻辑。 - Service 层负责业务规则必须显式声明事务边界。 - Repository 层只做数据访问禁止在业务方法里直接拼 SQL。 # 数据校验 - 入参校验统一在 DTO 层完成使用注解式校验禁止在 Controller 里手写 if 判断。 - 数据库写入前必须校验必填字段和字段长度。 - 金额字段一律使用整数类型禁止使用浮点数。 # 异常处理 - 业务异常必须抛出自定义异常类型由全局异常处理器统一转换。 - 禁止在 Service 里捕获异常后返回 null 来代表失败。后端代码涉及的隐含约定比前端还多如果不写在规则里模型很容易“看起来对、跑起来错”。比如事务边界要不要加、异常要不要抛出、能不能越过 Service 直接调 Repository这都是在审查代码时反复出现的问题。3.4 按语言维度还是按任务维度拆分规则我还试过按任务类型来组织规则比如“写测试时”“重构时”“写接口文档时”分别给不同指令。后来发现任务维度的规则很难在同一个.cursorrules里优雅共存因为模型没法自动识别“当前任务是重构所以优先遵守重构章节忽略其他章节”。所以我现在的做法是项目规则只写“世界观”也就是这个项目的技术共识任务维度的特殊要求留给对话里的临时指令。简单任务不需要额外规则复杂需求再追加几句话比维护一堆互相冲突的规则文件更省心。4. 规则真正发挥作用的三个场景实测对比4.1 场景一从零实现一个页面拿到一个列表页需求没有规则的情况下我的描述通常要写很细用什么组件、接口在哪、字段怎么映射、空态怎么显示、加载态怎么做。写到最后几乎等于自己把代码口述了一遍。配置规则之后同样的需求我只需要说“在用户管理模块新增一个角色列表页数据来自src/api/role.ts里的fetchRoles参考现有客户列表页的结构”。模型会自动匹配规则里的组件规范、接口调用规范生成出来的页面结构和我手写的高度一致。省下来的描述性文字就是“少写一半代码”的来源。4.2 场景二修改既有接口调用有一次需要把订单详情接口从分页结构改成列表结构。修改点涉及类型定义、请求函数、页面消费逻辑三处。没有规则时模型只改了页面里的数据处理函数漏掉了类型定义导致后续其他模块引用的字段全部报错。规则里如果写了“新增或修改接口时必须同时更新接口类型定义”模型就会在修改消费逻辑时主动检查类型文件。这一点对大型项目特别重要。类型系统的连锁错误往往是 AI 编程里最消耗时间的部分。规则天然就是防止这种返工的。4.3 场景三代码评审与重构我用 Cursor 做代码评审时规则的价值不在生成新代码而在约束输出格式。我的规则里有这么一句评审意见必须按“问题—影响—修改建议—示例代码”四段式输出。没有这句的时候模型经常把评审写成散文邹邹巴巴一大段我看半天不知道要先改哪里。加了格式约束之后模型给出的评审意见结构稳定我甚至能把它直接转发到项目群里讨论。重构场景同理规则里的“先给方案再落地”会强制模型先列出重构步骤而不是一次性把代码换完这对我确认风险边界很有用。4.4 依赖变更时规则如何自动生效还有一种容易忽略的收益当项目升级依赖之后规则里的约束会自动影响新代码的生成方式。比如项目从 webpack 切成 Vite如果规则里写了“统一使用 Vite 的环境变量方式禁止process.env前缀”那之后让模型改造构建相关代码时它就不会再生成旧写法。这一点在人员流动频繁的团队里尤其划算。新同学接手的项目往往带着一堆历史约定规则把这些约定固化下来AI 生成新代码时天然符合项目演进方向而不是复制网上那些过时示例。5. 让规则“活”起来变量、动态指令和团队协作5.1 在规则里使用变量Cursor 规则支持一些内置变量最常用的有三个当前文件路径、当前项目语言、当前操作系统。我一般会在规则里写一条# 上下文定位 - 当前编辑文件路径{{file_path}} - 当前项目主语言{{project_language}} - 当前选中代码范围{{selection}}这样做的意义在于规则不是死板的全局文案它能根据你正在编辑的文件自动调整关注点。比如规则里写“如果当前文件是测试文件优先补充测试描述”模型就能在被调用时读取变量判断自己是否处于测试上下文。我第一次看到这些变量时觉得没什么但实际用起来才知道它解决的是“一条规则管所有场景”的问题。否则你只能在全局规则里写一堆“如果……那么……”的条件句规则越长模型越容易跑偏。5.2 多项目并存时如何避免规则互相污染同时维护几个项目时最怕的是项目 A 的规则跑到项目 B 里生效。我的解决办法很朴素项目规则一律放在项目根目录的.cursorrules文件里全局规则只写与技术栈无关的内容。另外如果同一台机器上同时打开多个工作区要注意 Cursor 的上下文来源。有些情况下模型会把另一个工作区的文件带进当前对话尤其是使用“全部代码库”上下文时。我后来习惯了在每次大任务开始前先把不相关的工作区关掉或者在对话里手动指定只看当前目录。这件事不需要写进规则但属于配好规则之后的必备操作习惯。5.3 团队里统一规则的最佳做法团队协作时规则文件应该像代码一样进入版本管理而不是留在某一个人的本地配置里。我会把.cursorrules放在仓库根目录在文档里加一段说明要求团队成员更新规则时走正常的分支评审流程。但有一点要提醒团队规则最好收敛到共识层面不要写成某一个人的个人偏好。比如“函数名用动词开头”这类大家都能接受的规范可以写“我习惯把变量名缩写”这种主观风格就不适合写。规则一旦让成员觉得碍手碍脚很快就会被无视然后规则文件就变成摆设。我在实际操作中的节奏是团队里每个成员都可以提规则修订建议但合并之前要过一遍评审重点看会不会和现有代码风格冲突。这样规则才能持续迭代而不是一次性写完就沉睡在仓库里。6. 规则不生效或效果变差时的排查链路6.1 先确认规则到底有没有被加载规则不生效第一步不是改内容而是确认它是否被加载。我通常会在对话框里直接问一句“当前项目的规则要点是什么”。如果模型能准确复述规则里的技术栈和约束说明规则已经生效如果它开始胡编大概率是规则文件路径错了。一般容易出错的地方有三个一是文件名大小写部分平台对文件大小写敏感CursorRules和.cursorrules是不同的二是文件放错目录放到了外层而不是项目根目录三是改完规则后没有重开对话。需要说明的是规则是在对话开始时读取的已经打开的会话不会自动重新加载改完规则记得新建一个对话再测试。6.2 规则太长导致输出变差的调试方法规则不是越长越好。我之前把一套规则写到两百多行结果模型生成代码时频繁在无关约束上打转写一段简单的工具函数也要套一堆大帽子。后来我的调试方法是做减法把规则里每一条都标上使用频率低频约束先从项目规则里移除临时需要时再通过对话补充。等某条高频约束出现了三五次再加回规则文件。经过两轮减法我的规则稳定在六十到八十行左右覆盖了绝大部分重复场景又不至于把模型压得小心翼翼。如果规则长度无法缩减还有一个技巧把最关键的约束放到规则文件前三分之一处。模型对上下文不同位置的注意力有差异核心约束放太靠后有时会被后面的内容稀释。6.3 通过会话内指令快速验证规则的边界当模型生成结果不符合预期我会用会话内指令做一次 A/B 测试。比如加一句“这次忽略项目规则里的组件命名约束只关注功能实现”如果生成代码明显不同就说明规则确实在起作用问题可能出在规则内容和我的真实意图不匹配。反过来如果加完这句之后结果没变化那说明模型压根没在读规则或者上下文冲突导致规则被覆盖了。这时我会把上下文缩小到当前文件重新发起对话最大程度排除其他文件的干扰。这种验证方式花不了几分钟但能明确问题方向避免反复改规则却不知道为何无效。我配置 Cursor 的整个过程里最珍贵的心得就一句话规则是给未来的自己省话用的。你写下的每一条约定都是在减少以后每一轮对话里重复交代背景的时间。它真正值得投入精力的地方不是把规则写得华丽而是把它维护得贴合这个项目的真实土壤。项目在变技术在变规则也需要跟着变。每隔一段时间回头删掉一些过时的约束比一开始就憋大招要实用得多。
