1. Cursor Rules 是什么不是配置项而是 AI 编程的“操作手册”很多人第一次看到 “Cursor Rules” 这个词下意识会把它当成类似.editorconfig或tsconfig.json那样的静态配置文件——改几个字段、加几行开关AI 就能“听话”。这是最普遍、也最危险的误解。我带过 7 个用 Cursor 做主力开发的团队90% 的人最初都卡在这一步规则写了但 AI 生成的代码依然不按预期走甚至越写越乱。后来才发现问题根本不在语法而在于对 Rules 的定位错了。Cursor Rules 的本质是给 AI 编写的“岗位说明书”和“工作 SOP”。它不控制 Cursor 的底层模型参数那是模型厂商的事也不决定代码格式那是 Prettier 的活而是明确告诉 AI“你在这个项目里具体要做什么角色面对一个.py文件你是 Python 工程师还是 Django 全栈当用户说‘优化这个函数’你该优先考虑性能、可读性还是与现有日志规范对齐如果上下文没提数据库你能不能擅自加session.commit()”——这些决策边界全靠 Rules 来划清。这解释了为什么 GitHub 上那个 star 近 2k 的 flyeric0212/cursor-rules 仓库目录结构如此强调分层base/是公司级红线比如“所有 API 响应必须带X-Request-ID”languages/是语言级契约比如“Python 函数必须有 type hint且Optional[str]不得写作str | None”frameworks/是框架级默契比如“Vue 组件必须用script setup语法ref和reactive不得混用”。每一层都不是孤立的配置而是一套层层嵌套的“行为契约”。举个真实案例我们有个 FastAPI 项目Rules 里明确写了fastapi.mdc中一条“所有路由函数返回值必须为 Pydantic 模型实例禁止直接返回 dict 或 list”。结果某次 AI 根据注释“返回用户列表”生成了return [{id: 1, name: Alice}]。我们没去骂模型“不智能”而是立刻检查 Rules 文件——发现漏写了list[UserSchema]的类型声明规范。补上后AI 再次生成时自动用了return [UserSchema.model_validate(u) for u in users]。你看问题从来不在 AI “懂不懂”而在 Rules “有没有把边界说透”。提示Rules 文件名后缀.mdcMarkdown Cursor不是随意定的。它强制要求用自然语言描述规则而非 JSON/YAML 的布尔开关。因为 AI 理解“禁止在循环内发起 HTTP 请求”比理解no-http-in-loop: true可靠十倍。这也是为什么所有高质量 Rules 仓库.mdc文件里几乎看不到代码块全是带编号的条款、场景化示例和例外说明。2. Rules 的四层架构从“公司宪法”到“临时工协议”Cursor Rules 的威力不在于单个文件写得多漂亮而在于四层结构形成的“决策树”。AI 在生成代码前会像律师查法条一样按顺序匹配这四层规则。理解这个顺序是写出有效 Rules 的前提。我见过太多人把所有规则堆进project-rules.mdc结果 AI 只认了最顶层的通用条款框架特定规则完全失效。2.1 基础层base/项目的“宪法性文件”这一层规则位于项目根目录的.cursor/rules/base/下对所有文件全局生效是项目不可动摇的底线。它的核心任务不是教 AI 怎么写代码而是定义“谁来写”和“写给谁看”。以我们团队的core.mdc为例开篇第一条就写1. 你的身份是本项目首席 Python 工程师拥有 8 年 Django FastAPI 架构经验熟悉公司内部中间件 SDK。 2. 你的服务对象是后端开发同事非前端、运维同学需看日志、安全审计员关注注入风险。 3. 你的输出必须让上述三类人在不查文档的情况下5 秒内理解代码意图、10 秒内定位关键逻辑、30 秒内确认无安全漏洞。这条看似空泛实则锁死了 AI 的表达风格。当 AI 生成数据库查询时它不会写users User.objects.filter(name__icontainsq)这种 Django ORM 黑话而是自动展开为# ✅ 符合 core.mdc 要求显式说明意图、暴露关键参数 users User.objects.filter( name__icontainsq # 模糊搜索用户名区分大小写 ).select_related(profile) # 预加载关联数据避免 N1因为“让同事 5 秒理解意图”这条宪法迫使 AI 把隐含逻辑显性化。再看tech-stack.mdc它不罗列技术栈名称而是提供“可执行链接”- 数据库PostgreSQL 14.x官方文档 https://www.postgresql.org/docs/14/ - 关键约束所有表必须有 created_at 和 updated_at 时间戳字段触发器自动生成 - 禁止使用SERIAL 类型统一用 BIGSERIAL - 缓存Redis 7.0SDK 文档 https://github.com/our-team/redis-sdk - 必须调用cache.get_with_fallback(key, fallback_func, ttl300) - 禁止调用redis_client.set() 原生方法注意这里没有“应该用 Redis”而是精确到“调用哪个封装方法”“参数 TTL 是多少”。因为 AI 不需要知道“为什么选 Redis”它只需要知道“此刻该敲哪行代码”。2.2 语言层languages/每种语言的“方言词典”当 Cursor 打开一个main.py文件时它会自动加载languages/python.mdc打开index.tsx时则加载languages/typescript.mdc。这一层解决的是“同一件事不同语言怎么说”的问题。以 Python 的缩进规范为例很多团队写indent: 4但 AI 仍可能生成 2 空格或 Tab。我们的python.mdc是这样写的1. 缩进必须使用 4 个空格NOT TAB这是 PEP 8 强制要求。 2. 例外情况当一行代码超过 88 字符需换行时续行缩进必须是 8 个空格即 2 个标准缩进例如 python # ✅ 正确续行缩进 8 空格 result some_very_long_function_name( param1value1, param2value2, ) # ❌ 错误续行缩进 4 空格易与函数体混淆 result some_very_long_function_name( param1value1, param2value2, )所有if/for/while的 body 必须用 4 空格缩进即使只有一行。关键在第 2 条——用正反例对比把抽象规则变成视觉锚点。AI 对“8 空格”这种数字指令的理解远超“保持一致”。 再看 TypeScript 的类型声明规则接口interface用于描述对象形状类型别名type用于联合类型或字面量。所有 API 响应数据必须用接口定义命名格式I模块名实体名Response例如IUserLoginResponse。所有函数参数类型必须显式声明禁止使用any或unknown若不确定则用Recordstring, unknown。✨ 特别注意当接口继承另一个接口时必须用extends关键字且父接口名必须出现在子接口名中例如interface IUserBase { id: number; name: string; } interface IUserProfile extends IUserBase { avatar: string; }这里第 4 条的命名约定直接解决了团队长期存在的“接口复用混乱”问题。AI 生成新接口时会自动检查是否符合 Ixxx extends Iyyy 模式否则拒绝生成。 ### 2.3 框架层frameworks/框架的“潜规则翻译器” 这是最容易被忽视、却最影响生产力的一层。框架文档写的是“能做什么”Rules 写的是“在这个项目里必须怎么做”。比如 react.mdc 和 vuejs.mdc表面都是前端框架但 Rules 完全不同 react.mdc 的核心条款所有组件必须使用函数组件 Hooks禁止 class 组件。状态管理简单状态用useState复杂状态用zustand见 zustand.mdc禁止Redux。数据获取必须用react-query的useQuery禁止fetch原生调用。✨ 关键约束每个组件文件必须导出且仅导出一个默认组件文件名与组件名严格一致PascalCase例如UserProfileCard.tsx导出UserProfileCard。vuejs.mdc 则完全不同所有组件必须使用script setup语法糖禁止 Options API。状态响应式必须用ref和computed禁止reactive因团队历史项目存在reactive嵌套深度问题。数据获取必须用useAsyncDataNuxt 3 内置禁止axios直接调用。✨ 关键约束所有props必须用defineProps显式声明类型且类型必须是接口interface禁止type Props { name: string }。看到区别了吗React 规则强调“禁止什么”class、ReduxVue 规则强调“必须用什么”script setup、defineProps。这是因为 React 生态太自由需要划红线Vue 生态相对收敛需要指明路径。Rules 的价值正在于把框架的“可能性”翻译成项目的“确定性”。 ### 2.4 工具层other/按需启用的“临时工协议” other/ 目录下的规则如 git.mdc, document.mdc不会自动加载必须在 Cursor 输入框中显式调用格式为 git 或 document。这层设计极其精妙——它把“非编码任务”变成了可插拔的技能模块。 比如 git.mdc 的内容当你被请求生成 Git 提交信息时请遵循标题行subject≤ 50 字符用动词开头add/update/fix/remove例如 ✅ fix: prevent null pointer in user profile loading ❌ Fix a bug in user profile正文body分段说明What changed? 修改了什么Why is it necessary? 为什么必要How does it address the issue? 如何解决关联 Issue必须包含Closes #123或Refs #456Issue 编号来自当前分支名如feat/user-auth关联#user-auth。当开发者输入 git 生成本次提交信息AI 就会严格按此格式输出无需人工二次编辑。这比任何 Git hook 都可靠因为它是“生成即合规”。 document.mdc 更实用当你被请求编写文档时用中文面向初中级开发者避免术语堆砌。结构必须为【场景】→【操作步骤】→【预期结果】→【常见问题】。所有命令行必须标注执行目录例如# 在项目根目录执行 $ npm run build:staging截图必须标注箭头和文字说明禁止纯图片。我们曾用这套规则让 AI 在 3 小时内补齐了 12 个微服务的部署文档质量超过 80% 的人工撰写。 ## 3. 从零搭建 Rules一个 Vue 3 项目的实战推演 光讲理论不够我带你完整走一遍如何为一个全新的 Vue 3 Pinia Vite 项目从零开始构建一套可用的 Rules。这不是模板复制而是基于真实项目痛点的决策链。 ### 3.1 第一步诊断项目 DNA比写规则更重要 在动键盘前我花了 2 小时做三件事 - **翻历史代码**看最近 10 个 PR统计高频问题73% 的 Bug 来自 ref 和 reactive 混用42% 的样式错位源于 Tailwind class 顺序错误 - **问团队成员**收集 3 个最常被问的“为什么”“为什么登录页不用 useAuthStore”、“为什么按钮禁用态要加 opacity-50 cursor-not-allowed” - **查基建文档**确认 CI 流水线要求所有组件必须有 component JSDoc所有 API 调用必须通过 apiClient 封装。 这步产出一份《项目痛点清单》成为 Rules 的需求来源。没有它Rules 就是空中楼阁。 ### 3.2 第二步构建基础层base/——先立规矩 在项目根目录创建 .cursor/rules/base/写入三个核心文件 core.mdc身份与原则你的身份本项目 Vue 3 首席前端工程师精通 Composition API 和 Pinia熟悉公司 UI 组件库our-ui/core。你的输出必须满足可维护性新同事 1 天内能独立修改组件逻辑可测试性所有业务逻辑必须可单元测试无副作用、无 DOM 操作可审计性所有 API 调用必须有 traceId 日志所有权限判断必须有can()函数封装。当规则冲突时以core.mdcvuejs.mdcpinia.mdc为优先级。tech-stack.mdc技术栈契约Vue 版本3.4.x文档 https://vuejs.org/api/必须用script setup、defineProps、defineEmits禁止用this、data()、methods: {}Pinia 版本2.1.x文档 https://pinia.vuejs.org/必须用defineStore、storeToRefs、useStore()禁止用mapState、mapActionsOptions API 遗留UI 库our-ui/core^2.0.0组件文档 https://ui.our-company.com所有按钮必须用UButton禁止原生button所有表单必须用UForm禁止formproject-structure.mdc文件组织法项目结构强制为 src/ ├── assets/ # 静态资源图片、字体 ├── components/ # 通用组件无业务逻辑如 UButton、ULoader │ └── ui/ # UI 组件与 our-ui/core 一一对应 ├── composables/ # 组合式函数useApi、useAuth ├── layouts/ # 布局组件DefaultLayout、AuthLayout ├── pages/ # 页面组件HomePage.vue、LoginPage.vue ├── stores/ # Pinia storeauth.ts、user.ts ├── utils/ # 工具函数date-format.ts、string-utils.ts └── main.ts # 入口文件 ✅ 正确pages/UserProfilePage.vue导出UserProfilePage❌ 错误views/UserProfile.vue或components/UserProfile.vue 注意project-structure.mdc 里所有路径都用 ✅/❌ 对比因为 AI 对视觉符号的识别率远高于文字描述。我实测过用图标后AI 生成文件路径的准确率从 68% 提升到 94%。 ### 3.3 第三步填充语言与框架层languages/ frameworks/ 创建 languages/typescript.mdc聚焦 Vue 项目特需的 TS 规则所有defineProps必须用接口interface声明禁止类型别名type ✅ interface Props { title: string; count?: number; } const props defineProps () ❌ const props defineProps{ title: string }()所有defineEmits必须用类型字面量禁止字符串数组 ✅ const emit defineEmits{ (e: update, value: string): void }() ❌ const emit defineEmits([update])所有组件 Props 必须有 JSDoc格式 /**param {string} title - 页面标题必填param {number} [count] - 用户数量可选默认 0 */创建 frameworks/vuejs.mdc解决 Vue 特有陷阱响应式数据简单值string/number/boolean用ref对象/数组用reactive但禁止嵌套reactive即reactive({ user: reactive({...}) })❌✨ 新增规则所有reactive对象必须用toRefs解构禁止直接访问obj.prop生命周期onMounted中禁止直接操作 DOM必须用nextTick()包裹onUnmounted中必须清理定时器、事件监听器用onBeforeUnmount注册清理函数样式所有 Tailwind class 必须按官方排序规则layout → typography → color → misc✨ 新增规则禁用!important所有覆盖样式必须用更高优先级 class如hover:underlineunderline创建 frameworks/pinia.mdc规范状态管理Store 命名use模块名实体名Store例如useAuthUserStore、useProductListStoreState 定义必须用ref或computed禁止直接state.xxx valueActions 定义同步操作用普通函数异步操作必须用async/await且必须try/catch错误必须throw new Error(xxx)✨ 新增规则所有异步 Action 必须返回 Promise且必须有loading状态用defineStore的state管理### 3.4 第四步验证与迭代——用真实 PR 测试 Rules Rules 写完不是终点而是起点。我们用一个真实 PR实现“用户头像上传”功能来验证 - **PR 描述**“添加用户头像上传功能支持 JPG/PNG最大 2MB上传后自动裁剪为 100x100px” - **AI 生成代码**开启 Rules 后 vue !-- pages/UserProfilePage.vue -- template UForm submithandleSubmit UInput label头像 typefile acceptimage/jpeg,image/png changehandleFileChange / UButton typesubmit保存/UButton /UForm /template script setup langts import { ref, reactive } from vue import { useAuthUserStore } from /stores/auth-user import { apiClient } from /utils/api-client const authStore useAuthUserStore() const file refFile | null(null) const handleSubmit async () { if (!file.value) return try { // ✅ 自动调用 apiClient自动加 traceId const result await apiClient.uploadAvatar(file.value) authStore.updateAvatar(result.avatarUrl) // ✅ 自动触发 loading 状态由 pinia.mdc 规则保证 authStore.setLoading(false) } catch (error) { // ✅ 自动格式化错误core.mdc 要求 console.error([UserProfilePage] uploadAvatar failed:, error) throw error } } /script验证结果✅ Props 声明符合typescripts.mdc接口 JSDoc✅reactive未滥用file用ref正确✅ API 调用走apiClienttech-stack.mdc红线❌ 发现新问题UInput的accept属性未校验文件类型应在composables/useFileUpload.ts中补充校验逻辑于是我们新增composables/useFileUpload.mdc到other/目录并在vuejs.mdc中追加4. 文件上传 - 必须用 useFileUpload 组合式函数见 other/useFileUpload.mdc - 禁止在组件中直接处理 File 对象这就是 Rules 的进化过程不是一次性写完而是在真实开发流水中不断用问题反哺规则。4. Rules 的避坑指南90% 的失败源于这 5 个认知偏差我整理了过去两年踩过的所有坑总结出 5 个最高频、最致命的认知偏差。它们不涉及技术细节而是思维模式问题。避开它们Rules 成功率提升 3 倍。4.1 偏差一“Rules 越多越好”——导致 AI 决策瘫痪新手最爱干的事把网上搜到的所有 Rules 全塞进项目。结果 AI 生成代码时卡顿、报错甚至拒绝响应。原因很简单Rules 是 AI 的“决策树”节点越多路径越长计算成本越高。Cursor 的本地推理引擎有内存和时间限制当 Rules 文件总行数超过 2000 行响应延迟会指数级上升。解决方案做减法不是加法每条规则必须回答“如果删掉它AI 会犯什么具体错误”删除所有“应该”“建议”类软性规则只保留“必须”“禁止”类硬性规则合并同类项把 5 条关于缩进的规则压缩成 1 条带正反例的条款我们团队的 Rules 总行数控制在 800 行内其中base/占 300 行languages/占 200 行frameworks/占 300 行。实测下来平均响应时间稳定在 1.2 秒内。4.2 偏差二“Rules 要覆盖所有场景”——陷入完美主义陷阱有人坚持要写“所有 Vue 指令的用法规范”“所有 CSS 伪类的兼容性列表”。这完全违背 Rules 的设计哲学。Rules 的目标不是替代文档而是解决“80% 场景下AI 最容易犯的 20% 错误”。解决方案聚焦“高频高危”场景统计团队近 3 个月 Bug Report找出 Top 5 高频错误类型针对每种错误写 1 条精准规则例如“禁止在v-for中用index作为key必须用唯一 ID”其他低频场景留给开发者人工判断我们曾为v-model写了 12 条规则效果平平后来聚焦到 1 条“v-model绑定的变量必须在setup中声明为ref或computed禁止绑定props的属性”Bug 率下降 65%。4.3 偏差三“Rules 写完就扔”——失去持续进化能力很多团队 Rules 写完就归档半年不更新。结果随着项目演进Rules 越来越脱离实际。最典型的是新引入了Zod做表单验证但zod.mdc规则没跟上AI 仍用yup生成代码。解决方案建立 Rules 的 CI/CD 流程在 Git Hook 中加入 Rules 校验pre-commit时运行cursor rules validate需自研脚本每次 PR 合并自动检查新增代码是否符合 Rules用 AST 解析器扫描每月召开 Rules Review 会由资深工程师主讲“本月 Rules 修复了哪些 Bug”我们用 GitHub Actions 实现了自动化校验每次 PR 都会生成 Rules 合规报告。数据显示Rules 更新频率与项目 Bug 率呈强负相关r -0.89。4.4 偏差四“Rules 是给 AI 看的”——忽略人的可读性有些 Rules 写得像机器码enforce: true, scope: [vue], action: reject_if_contains: this.$refs。AI 可能懂但开发者看不懂无法参与维护。解决方案Rules 必须是“双语文档”每条规则前加 场景说明这条规则解决什么实际问题每条规则后加 为什么解释背后的技术原理或业务原因所有代码示例必须有✅ 正确/❌ 错误标签例如vuejs.mdc中一条规则 场景防止 v-if 和 v-for 同时使用导致渲染异常Vue 官方警告 为什么v-for 优先级高于 v-if会导致不必要的 DOM 创建/销毁 ✅ 正确用 computed 过滤列表再 v-for div v-foritem in filteredList :keyitem.id{{ item.name }}/div ❌ 错误直接 v-if v-for div v-foritem in list v-ifitem.active :keyitem.id{{ item.name }}/div4.5 偏差五“Rules 能替代 Code Review”——混淆工具与流程最危险的认知认为有了 RulesCode Review 就可以取消。Rules 解决的是“怎么写”Code Review 解决的是“该不该写”。Rules 再完善也无法判断“这个功能是否符合产品需求”“这个算法是否最优”。解决方案明确 Rules 与 Review 的边界Rules 负责语法合规、风格统一、安全红线如 SQL 注入Code Review 负责业务逻辑正确性、架构合理性、性能影响评估在 PR 模板中强制要求[ ] Rules 合规自动检查通过[ ] 业务逻辑已确认人工 Review我们团队的 PR 检查清单里Rules 合规是第一项但它只是准入门槛不是最终判决。5. Rules 的进阶技巧让 AI 从“执行者”变成“协作者”当 Rules 基础稳固后可以解锁更高阶的玩法。这些不是必需但能极大提升开发体验。我分享 3 个已在生产环境验证的技巧。5.1 技巧一用 Rules 实现“上下文感知”的智能补全Cursor 默认的补全是基于当前文件的局部上下文。但 Rules 可以注入“项目级上下文”。例如在frameworks/fastapi.mdc中加入✨ 智能补全增强 - 当你在 router/ 目录下创建新文件时AI 必须 1. 自动生成 from fastapi import APIRouter 和 router APIRouter() 2. 自动生成 router.get(/xxx) 装饰器路径必须符合 /{module}/{entity} 格式如 /user/profile 3. 自动生成 response_model 参数类型必须为 I模块名实体名Response - 当你在 schemas/ 目录下创建新文件时AI 必须 1. 自动生成 from pydantic import BaseModel 2. 自动生成 class I模块名实体名Response(BaseModel): 接口 3. 自动生成 id: int 和 created_at: datetime 字段所有响应模型标配效果是开发者新建router/user.py输入router.AI 就自动补全router.get(/user/profile)新建schemas/user.py输入classAI 就自动补全class IUserProfileResponse(BaseModel):。这不再是补全而是“项目知识的主动推送”。5.2 技巧二Rules 驱动的“渐进式重构”重构旧代码是痛苦的但 Rules 可以让它自动化。我们有个遗留的 Django 项目想迁移到 FastAPI。传统做法是手动重写耗时耗力。我们用 Rules 实现了半自动迁移创建legacy/django-to-fastapi.mdc 任务将 Django 视图函数转换为 FastAPI 路由 步骤 1. 分析 def view(request): 函数提取 URL path、HTTP method、request data、response format 2. 生成等效 FastAPI 路由用 router.get/post 替代 path() 配置 3. 将 request.POST.get(xxx) 转为 Body 或 Query 参数 4. 将 render(template.html, context) 转为 HTMLResponse 或 JSON 响应 5. ✨ 关键所有数据库操作必须替换为 sqlmodel 查询禁止 django.db.models在 Cursor 中输入django-to-fastapi 将以下 Django 视图转为 FastAPI粘贴旧代码AI 自动输出转换结果。我们用这套方法在 2 周内完成了 83 个视图的迁移准确率 92%剩余 8% 是复杂逻辑需人工审核。Rules 把“重构”变成了“格式转换”。5.3 技巧三Rules 作为“新人入职加速器”新员工入职最耗时的是熟悉项目规范。我们把 Rules 直接做成交互式学习系统创建onboarding/first-day.mdc 任务指导新人完成第一个 PR 步骤 1. 在 pages/ 下新建 WelcomePage.vue 2. 使用 UButton 组件点击跳转到 /dashboard 3. 添加 JSDoc 说明组件用途 4. 运行 pnpm test:unit 确保通过 5. 提交 PR标题格式feat(welcome): add welcome page ✅ 示例代码 script setup langts /** * component WelcomePage * description 首页欢迎组件展示公司标语和快速入口 */ import { useRouter } from vue-router const router useRouter() const goToDashboard () router.push(/dashboard) /script新人打开 Cursor输入first-dayAI 就一步步引导他完成所有操作每步都给出代码示例和解释。我们统计过用 Rules 做入职培训新人首周产出有效代码的时间从平均 3.2 天缩短到 0.7 天。最后分享一个个人体会Rules 的终极价值不是让 AI 写得更多而是让开发者思考得更深。当我花 3 小时写一条精准的vuejs.mdc规则时我其实是在梳理整个团队的 Vue 开发哲学。那些曾经模糊的“感觉不对”变成了白纸黑字的“必须如此”。Cursor Rules本质上是一面镜子照见我们对代码质量的真实认知。写 Rules 的过程就是一次集体技术反思。