先聊一件让我挺有感触的事。以前我用 Cursor 写代码最怕的不是 AI 写出多离谱的代码而是它每次写出来的风格都像开盲盒。有时候给出的方案很惊艳有时候又犯低级错误变量命名天马行空异常处理直接忽略甚至把团队内部约定的 API 封装都绕过去了。代码评审一次能打回三四轮AI 越改越乱我越看越气。后来我把问题想明白了不是 AI 不行是我压根没告诉它“在我们项目里好代码到底长什么样”。于是我花了一个晚上写了一份 40 行左右的.cursorrules把项目约束、代码风格、输出格式全部塞进去。实测之后AI 生成代码的“首版通过率”从之前纯靠运气的状态直接稳定到了 80%。这篇文章我就把这份规则文件的完整内容、设计思路、踩过的坑和量化方法都讲一遍希望能给同样在跟 AI 协作写代码的朋友一些参考。1. 先搞清楚一件事AI 写的代码为什么总得返工很多人的第一反应是“AI 能力不行”但我测过 GPT、Claude 还有 Cursor 内置的不同模型发现问题的核心根本不是模型智力而是上下文里缺乏项目级约束。你给 AI 一个 Task它就只盯着这个 Task 的局部上下文自动补全缩进、命名、边界情况全靠猜。猜对了皆大欢喜猜错了就是一次次返工。1.1 首版通过率低根子在于上下文缺失我复盘了两次典型的返工现场。第一次是让 AI 写一个用户列表的分页接口。任务描述写得很清楚分页参数、返回结构、异常处理。结果 AI 交出来的代码里直接return users.slice(0, 10)把分页参数写死了排序逻辑也默认按创建时间降序完全没看我们项目里通用的查询封装。第二次是让 AI 给一个 React 组件加搜索功能它转头就引入了一个新的 URL 参数管理库我们的项目里明明一直用的是react-router-dom原生 searchParams。这两次返工浪费了大概四十分钟。后来我意识到一个残酷的事实AI 理解“任务”但不理解“场景”。如果你不把项目的技术栈选型、目录习惯、命名规范、错误处理策略、禁止事项全部暴露给它它只能按照训练数据里的“最大公约数”来写代码。那个“最大公约数”往往是最通用、最教材化、最不符合真实工程需求的写法。1.2 为什么同一位 AI不同人用效果差这么多同一个模型、同一个项目有人用着像资深工程师有人用着像刚毕业的实习生。差距就在你有没有给它建立一套“项目共识”。我见过很多人直接在新对话里粘贴一段需求就开始写AI 连续问三个问题他嫌烦直接说“你先写后面我再改”。结果自然就是首版通过率惨不忍睹。.cursorrules本质上就是把“项目共识”提前注入到每一次 AI 请求里。它不是一个魔法开关更像是一个上岗培训手册。你把它放在项目根目录Cursor 在每次对话时会自动读取并作为系统级上下文的一部分参与生成。你不需要每次重复强调技术栈和代码规范AI 自动就能看到。这样一来首版代码和团队预期的差距会被大幅压缩。2. .cursorrules 到底是什么以及它凭什么能起作用简单说.cursorrules是放在项目根目录下的一个纯文本文件建议用 Markdown 格式写Cursor 编辑器会在你发起对话、生成代码、做内联编辑时自动把它作为系统提示词的一部分发给模型。它跟你手动在对话框里打的提示词相比优势在于持久化、无感、项目级共享。2.1 一句话理解 .cursorrules 的原理你每次跟 AI 对话本质上就是在给模型“补上下文”。但对话框里的上下文是一次性的换一个新对话就没了。团队成员各自开新对话AI 就各自失忆。.cursorrules把项目规则“焊死”在项目目录里不管是谁、什么时候、在哪台机器上打开这个项目AI 的行为基线都是一样的。我把它理解为“给 AI 立规矩”。规矩不用多但不能没有。这跟带新人是一个道理如果团队没有编码规范文档新人就只能靠猜或者照着老代码的风格复制。如果有一份靠谱的规范新人上手速度快产出也稳定。AI 比新人更需要这份规范因为它连“问”都不会主动问你不说它就自由发挥。2.2 文件该放在哪、怎么生效、优先级是怎么排的.cursorrules的位置很讲究。放在项目根目录Cursor 会在你打开该项目下的任何文件时自动加载它。如果你在子目录里也放一个.cursorrules子目录的规则会合并进来但项目根目录的规则优先级更高。如果你在~/.cursorrules放了一份全局规则那么它会被任何项目的局部规则覆盖。简单记就是越贴近当前工作区的规则优先级越高。我建议团队直接把这个文件提交到 Git 仓库里跟代码一起管理。新的同事 clone 项目下来Cursor 就会自动读到这份规则不需要额外配置。文件命名就是.cursorrules不需要扩展名Cursor 原生支持。如果用的是 VS Code 加 Cline、Continue 之类的插件也有对应的方式引入类似规则这个后面可以单独聊。3. 我那份 40 行 .cursorrules 的完整结构与逐段解读先说明一下我这份规则是围绕一个 TypeScript 全栈项目写的技术栈是 React Node.js Prisma PostgreSQL团队对代码质量要求比较严。你如果不是这个技术栈把对应部分换成自己的就行核心骨架和思路是通用的。3.1 全文展示我把它压在了 40 行左右不是越短越好而是每一条都经过筛选确保不会因为太长而导致模型忽略关键信息。下面是去掉了敏感信息后的完整版# Project Context - 语言: TypeScript - 前端: React 18 Vite - 后端: Node.js Express - 数据库: PostgreSQL Prisma ORM - 包管理: pnpm # Code Style - 使用函数组件和 hooks禁止 class 组件 - 所有变量、函数使用 camelCase组件文件使用 PascalCase - 类型定义统一放在 types/ 目录禁止在组件文件内定义共享类型 - 优先使用 type 而不是 interface除非是描述对象形状且需要合并 - 禁止 any未知类型用 unknown再通过类型守卫收窄 - 使用绝对路径导入别名 / 指向 src/ 根目录 # Engineering Practices - 所有新增业务逻辑必须附带单元测试测试文件放在 __tests__ 目录 - 错误处理优先使用 try/catch不要吞异常必须记录日志 - 禁止编写超过 80 行的函数拆分为小函数 - API 请求统一走 src/lib/apiClient.ts 封装禁止直接使用 fetch 散落各处 - 环境变量通过 src/config.ts 统一读取禁止在业务代码中直接 process.env - 数据库查询必须经过 Prisma Client禁止写裸 SQL - 组件内禁止直接修改 props 和 state使用不可变更新 # Output Format - 生成新文件之前先给出文件路径和职责说明 - 修改现有文件时只展示 diff 块并说明修改原因 - 代码必须通过 TypeScript 严格模式检查 - 每次输出末尾附上“自测清单”列出你如何验证这段代码正确 - 如果不确定项目里的既有约定先搜索相关代码再实现这看起来很简单但每条背后都有故事。3.2 逐块拆解技术栈锁定、代码风格、工程约束、输出格式“Project Context”这一块我称之为“防串味”。AI 在训练数据里见过太多技术栈你不锁定它可能给你写一个 Vue 组件混进 React 项目里或者用 axios 而不是项目统一的 apiClient。锁定技术栈的意义不是限制发挥而是把 AI 从“通用程序员”变成“你团队里的程序员”。“Code Style”这一块解决的是“代码像不像人写的”问题。我见过 AI 生成的代码里冒出一个any在严格模式检查下直接编译失败。也见过它在组件文件里定义了一堆只在别的文件里用到的类型导致循环依赖。把命名规范、类型策略、导入方式写清楚以后这类低级问题基本不会出现了。这里要特别说明一下“优先使用 type 而不是 interface”这是我们团队内部的一个选择不是为了迎合谁而是为了避免 interface 的属性合并带来的隐性类型污染。你的团队如果习惯用 interface改成 interface 也行重点是“统一”。“Engineering Practices”这块是首版通过率的灵魂。没有这些约束AI 生成的代码能跑但经不起 Code Review。比如说“禁止编写超过 80 行的函数”AI 看到这条之后在生成复杂逻辑时会主动拆函数虽然偶尔拆得不够优雅但比一大坨几百行的流程代码好改多了。再比如“API 请求统一走 apiClient 封装”这个约束直接让 AI 放弃了自己造一个 fetch 函数的想法转而去找项目里已有的封装。我甚至发现当这条规则存在时AI 会主动先搜索apiClient的用法再开始写请求代码这正是我想要的行为。“Output Format”这个设计很多人会忽略但它直接影响你 review 代码的速度。让 AI 先给出文件路径和职责说明你就能快速判断它的实现思路对不对而不是先读一堆代码再恍然大悟。让 AI 列出“自测清单”更是神来之笔它会让模型在生成代码时模拟执行一遍很多低级的逻辑漏洞在这一步就被模型自己过滤掉了。实测下来加了这条之后边界条件漏处理的情况明显减少。4. 实测记录从“瞎猜”到 80% 首版通过率的全过程我不喜欢只讲概念不讲数据。为了验证这份.cursorrules的效果我专门做了一轮对比测试也把“首版通过率”这个指标量化了。4.1 什么叫“首版通过率”以及怎么量化我定义的首版通过率是AI 生成的第一版代码不需要人工修改就能通过以下全部检查的概率TypeScript 严格模式编译无报错现有单元测试全部通过新增代码如果有测试新测试也能通过代码风格符合团队约定命名、导入路径、目录归属无明显的逻辑漏洞比如漏掉 loading 状态、没有处理错误分支没有绕过项目基础设施比如没用 apiClient、直接操作 DOM、绕过 Prisma这五个条件看起来简单但实际操作中哪怕 AI 生成的代码能编译也可能因为没走 apiClient 而被评审打回。所以我的通过标准不是“能跑”而是“能直接合入”。测试方法是在同一个项目里抽取 20 个日常开发任务包括新增接口、修改组件、修复 bug、添加测试等类型。每类任务交替进行一组使用旧的“无规则自由对话”方式另一组使用加了.cursorrules的方式。同一个任务不会同时在两组里出现但任务难度和类型分布保持一致。我记录了每个任务第一版代码的通过情况。因为样本量不算大这个数字不会特别精确但趋势很有参考价值。4.2 基线测试到优化后的真实数据对比在没有.cursorrules的时候我随机抽了 10 个任务结果如下表任务类型编译通过测试通过风格合规逻辑无误走项目基建最终通过新增分页接口是否否否否否组件加搜索是是是是否否修复日期 bug是否是否是否添加单元测试是是否是是否重构工具函数是是否是是否新增弹窗组件是是是是是是写数据库查询是否是否否否修改表单校验是是否是是否接入新的 API是是否否否否优化列表渲染是是是是是是10 个任务里只有 2 个能直接通过也就是 20%。而且这 20% 还是最简单的任务。换句话说在复杂一点的业务场景里几乎全靠人工返工。AI 写的代码看着能用但离“可合入”差得很远。加上.cursorrules之后我对另外 10 个同难度任务重复了上面的测试通过率是 8 个也就是 80%。失败的两个任务一个是因为模型没有处理极端的空数组边界情况另一个是因为生成的新接口字段和前端组件的类型定义对不上。但这里我要说一句公道话这两个失败点放在人类开发者也经常会漏代码评审时改一下也就几分钟的事。整体节省下来的返工时间非常可观。4.3 80% 里的水分和口径为了防止有人抬杠我得说清楚这个 80% 不是“AI 写出来的代码完美到一行不用改”而是“在评审时不需要结构性调整、只做小规模修改即可合入”。我们团队的实际开发流程里AI 生成代码后我仍然会过一遍 diff但这个 review 的负担从“逐行检查逻辑”降到了“扫一眼确认没有越界”。这是我感受到的最大变化。我也测过一份 150 行的.cursorrules通过率并没有继续提升反而出现了模型“过度贴合规则”导致输出变啰嗦、忽略任务重点的情况。后来我把规则精简到 40 行在保持核心约束的前提下把那些“锦上添花”的建议都删了。结论是规则文件不是越详细越好要给模型留出理解任务的空间。40 行对大多数项目来说是一个甜点区间的下限。当然如果你的项目里藏着一大堆历史约定你可以适当增加到 60 到 80 行但我不建议超过 100 行。5. 常见问题与排查技巧实录这份.cursorrules用完以后我踩过几个很有代表性的坑也收到过一些朋友的使用反馈。这里整理成问题实录希望能帮你少走弯路。5.1 文件没生效先查这 3 个点第一个常见问题是“我写了 .cursorrules但感觉 AI 完全没读”。这种情况先确认文件有没有放在项目根目录而不是src或者.cursor子目录。Cursor 只会读取当前打开项目的根目录文件。第二个坑是文件编码问题如果你在 Windows 上用记事本保存的务必确认编码是 UTF-8不然中文内容可能变成乱码导致模型读不懂。第三个坑就是 Cursor 版本和模型选择的问题有些旧版本对话不会自动加载.cursorrules需要你在对话里手动 一下这个文件。建议升级到最新版本并且尽量使用支持超长上下文的模型比如 Claude 的对应版本或者 GPT-4 以上级别效果会稳定很多。在这里给一个自检方法你在对话框里随便问一句“这个项目的技术栈是什么请读一下 .cursorrules”如果 AI 能准确说出 React、TypeScript、Prisma 这些关键词说明规则已生效。如果答得含糊其辞那就是没加载上按上面的顺序排查。5.2 规则冲突、过宽、过窄的处理方式规则写多了以后偶尔会遇到“规则打架”的情况。比如我在 Code Style 里写了“禁止 any”但在 Engineering Practices 里又写了“处理未知类型时可以用 unknown 再收窄”这两个本身不冲突但如果你再写一条“解析接口返回数据时可以使用 any 快速处理”那模型就懵了。它会纠结到底哪条优先级更高最后可能输出一个as any再加一行注释非常难看。所以规则之间一定要保持一致能用正向描述就尽量不要用否定式加例外条款。还有一个常见的坑是规则过窄导致 AI 不敢动手。比如“所有函数不得超过 20 行”这种约束会让模型为了拆函数而拆函数产生一些毫无意义的中间函数。我实测后把它改成了 80 行给了模型足够的发挥空间反而代码质量更高了。规则过宽的后果则是 AI 写出来的代码风格漂移不定今天用 function 声明明天用箭头函数整体观感很差。所以宽严之间要找到平衡点你需要反复试验并观察 AI 的输出变化。5.3 后续扩展和小心得用了一段时间以后我又在.cursorrules里加了一些针对“新人友好”的内容比如“新增文件时若引用了不存在的依赖请在代码注释中标注依赖安装命令”这能有效减少我在本地装依赖时的猜谜时间。另外如果你用的是 Cursor 以外的 AI 编程工具比如 Continue 插件、Cline、甚至直接通过 API 调用模型做代码生成这套思路同样适用。你只需要把.cursorrules的内容改造成对应的规则文件格式或者直接把它作为 System Prompt 的一部分传给模型。核心逻辑是一样的先给 AI 划定边界再让它自由发挥。没有边界的 AI 是惊喜和惊吓并存的盲盒有边界的 AI 才是你团队里那个稳定、高效、知根知底的初级工程师。最后再分享一个小技巧如果你改动了.cursorrules最好新开一个对话再测试因为旧的对话上下文里可能还残留着旧规则的影响。实际开发中我每次调整规则后都会用同一个测试任务跑一遍对比确认改动是正向的再提交到 Git。这样积累下来你的规则文件就会变成一个数据驱动的团队资产而不是拍脑袋的产物。