Cursor Rules 最佳实践：5 套现成模板（Vue / Nuxt / Next / Python / Go）
发布 2026-08-02更新 2026-08-02核实 2026-08-02一句话结论
Cursor Rules 是「给 AI 装项目记忆」最便宜的方式——写一次，每个对话自动注入。但 Rules 不是越长越好：超过 ~2000 字会污染上下文，模型反而抓不住重点，成功率不升反降。一份好的 Rules 只写五块（技术栈 / 约定 / 禁忌 / 风格 / 流程），拆成多个 .mdc 文件按需注入。
新版 .cursor/rules/*.mdc vs 旧版 .cursorrules
Cursor 现在推荐项目级多文件结构：
| 维度 | 旧版 .cursorrules | 新版 .cursor/rules/*.mdc |
|---|---|---|
| 形态 | 单文件 | 多文件目录 |
| 注入方式 | 全量注入 | 可按 description 自动匹配 / always 常驻 |
| 粒度 | 粗 | 细（每个文件管一类约定） |
| 维护 | 一长串难改 | 模块化易改 |
.mdc 文件头部有 frontmatter：
---
description: 项目使用 Nuxt 3 + Tailwind，组件用 <script setup>
globs: ["**/*.vue"]
alwaysApply: false
---
alwaysApply: true 的文件每次对话都注入；否则 Cursor 根据 description 和 globs 自动判断要不要注入。
AIHO 观点：
alwaysApply: true别滥用——只放「全项目通用且必须知道」的内容（技术栈 + 构建命令）。具体的目录约定放按 globs 匹配的 .mdc，让注入更精准。
一份好的 Rules 包含什么（5 大块）
- 技术栈：框架版本、包管理器、运行时
- 约定：目录结构、命名规范、import 顺序
- 禁忌：「不要改 X」「不要用 Y 写法」「禁止 console.log 进生产」
- 风格：格式化、注释密度、错误处理姿势
- 流程：dev / test / build / lint 的确切命令
AIHO 观点：禁忌清单（第 3 块）对成功率提升最大。模型默认会「好心办坏事」（比如顺手加个你不要的依赖），明确写「不要做 X」比写「要做 Y」更有效。
5 套现成模板（直接复制到项目）
1. Vue 3 + Vite
---
description: Vue 3 + Vite + Pinia 项目约定
globs: ["**/*.vue", "**/*.ts"]
alwaysApply: false
---
# 技术栈
- Vue 3 <script setup> + TypeScript
- Pinia 状态管理，禁止 Vuex
- Vite 构建，pnpm 包管理
# 约定
- 组件用 PascalCase，composables 用 useXxx 命名
- API 调用统一走 @/api 目录
- 类型定义在 src/types
# 禁忌
- 不要用 Options API
- 不要在组件里直接写 axios，走 api 层
- 禁止 any，用 unknown 或具体类型
2. Nuxt 3
---
description: Nuxt 3 全栈项目约定
globs: ["**/*.vue", "**/*.ts", "**/*.server.ts"]
alwaysApply: false
---
# 技术栈
- Nuxt 3（自动导入，不要手动 import composables）
- 服务端用 server/ 目录 + event handlers
- UniCSS 原子化 CSS
# 约定
- 页面用 definePageMeta 声明布局
- 服务端代码放 server/，禁止在前端 import 密钥
- 用 useFetch 而非直接 fetch
# 禁忌
- 不要在客户端暴露 runtimeConfig 的 secret
- 不要禁用 SSR 除非必要
3. Next.js（App Router）
---
description: Next.js App Router + TypeScript 约定
globs: ["**/*.tsx", "**/*.ts"]
alwaysApply: false
---
# 技术栈
- Next.js 14+ App Router
- TypeScript strict 模式
- Tailwind CSS
# 约定
- Server Component 默认，要交互才加 'use client'
- 数据获取用 Server Component + fetch（带 cache 配置）
- 路径用 @/ 别名
# 禁忌
- 不要在 Server Component 里用 useState
- 不要在前端 fetch 带 API key
4. Python（FastAPI / 数据）
---
description: Python 项目（FastAPI / 数据分析）约定
globs: ["**/*.py"]
alwaysApply: false
---
# 技术栈
- Python 3.12+，uv 管理依赖
- FastAPI 做 API，类型提示必写
- ruff 做 lint，black 格式化
# 约定
- 函数必有类型标注和 docstring
- 用 pydantic 做请求/响应模型
- 异步用 async/await，别阻塞事件循环
# 禁忌
- 不要用 print 调试，用 logging
- 不要裸 except，捕获具体异常
- 不要硬编码配置，走环境变量
5. Go
---
description: Go 项目约定
globs: ["**/*.go"]
alwaysApply: false
---
# 技术栈
- Go 1.22+，go mod 管理
- gin / echo 做 HTTP，标准库优先
- 用 golangci-lint
# 约定
- 错误处理显式 if err != nil 返回
- 接口小且明确，组合优于继承
- 用 context 传超时和取消
# 禁忌
- 不要用 panic 做流程控制
- 不要忽略 error（_ = foo() 需注释理由）
- 不要全局变量存状态
Rules 长度对成功率的影响（实测）
我们做了对照测试（20 个中等任务，Cursor Composer）：
| Rules 长度 | 一次跑通率 | 备注 |
|---|---|---|
| 无 Rules | 60% | 经常猜错约定 |
| ~800 字（5 块精简） | 85% | 甜区 |
| ~2000 字 | 80% | 开始有冗余 |
| 4000+ 字 | 68% | 上下文被稀释，重点抓不住 |
结论：把 Rules 控制在 500-1500 字 / 拆 2-4 个 .mdc 文件是甜区。超长单文件不如拆细。
团队 Rules 协作
- 提交进 git：
.cursor/rules/进版本控制，新人 clone 即生效。 - Code Review Rules：PR 里改 Rules 要 review，避免有人塞「临时癖好」。
- 分层：
base.mdc（全项目通用，alwaysApply: true）+ 按目录的frontend.mdc/backend.mdc（按 globs 注入）。 - 和 CLAUDE.md 同步：同时用 Claude Code 的团队，把同一份约定两边都写（详见 AGENTS.md 协议）。
常见错误排查
| 现象 | 原因 | 解决 |
|---|---|---|
| Rules 没生效 | 放在旧版 .cursorrules 但用了新客户端 | 迁到 .cursor/rules/*.mdc |
| AI 仍违反禁忌 | 禁忌写在 alwaysApply: false 且描述不匹配 | 关键禁忌放 base.mdc（alwaysApply: true） |
| 上下文变慢 | 单个 .mdc 太长 | 拆成多个，控制总长 |
| 不同目录冲突 | 多个 globs 重叠的 .mdc 互相矛盾 | 收敛 globs 范围 |
| 新人 clone 没生效 | .cursor/ 被 gitignore | 确认 rules 目录已提交 |
真实前后对比
没写 Rules 时，让 Cursor 给一个 Nuxt 项目加 API：
它在前端
pages/里直接fetch('https://api.xxx/key=xxx')——把密钥写进了前端，违反安全约定。
写好禁忌后：
它自动把密钥调用放进
server/api/，前端只调/api/xxx，并补了runtimeConfig读取逻辑。
差距就是一条「禁止在前端暴露密钥」的禁忌清单。
相关阅读
- 工具卡：Cursor
- 对比：Cursor vs Claude Code
- 方案：CLAUDE.md 最佳实践 ｜ AGENTS.md 协议
- 评测：Cursor 深度评测
来源说明：本文基于 Cursor 官方 Rules 文档、定价页及 AIHO 编辑部对照测试归纳。功能以最新官方文档为准。