Cursor Rules 深度实战：让 AI 编程助手真正读懂你的项目
什么是 Cursor Rules？
Cursor Rules 是 Cursor 编辑器提供的一项强大配置机制，允许开发者通过 .cursorrules 文件（或 .cursor/rules/ 目录）向 AI 模型注入项目级别的上下文信息和行为约束。简单来说，它就是你写给 AI 的"项目说明书"。
在没有 Rules 的情况下，每次对话 AI 都是"从零开始"理解你的项目，容易产生风格不一致、忽略项目约定、反复犯同类错误等问题。有了 Rules，AI 能持续遵循你的技术选型、编码规范和架构决策。
全局 Rules：在 Cursor 设置的 "Rules for AI" 中填写，对所有项目生效
项目 Rules（.cursorrules）：放在项目根目录，仅对当前项目生效
目录级 Rules（.cursor/rules/*.mdc）：Cursor 0.43+ 支持，可针对不同子目录设置不同规则
Rules 文件的核心语法结构
一份好的 .cursorrules 文件通常包含以下几个核心板块，用自然语言写成（Markdown 格式最佳）：
# 项目概览 这是一个基于 Next.js 14 + TypeScript + Tailwind CSS 构建的 SaaS 应用。 使用 Prisma 作为 ORM，PostgreSQL 作为数据库。 # 技术栈约定 - 组件库：shadcn/ui，禁止引入 antd 或 MUI - 状态管理：Zustand，禁止使用 Redux - 数据请求：React Query v5，禁止直接用 useEffect 请求数据 - 样式：Tailwind CSS，禁止写内联 style 和独立 CSS 文件 # 代码规范 - 所有函数组件使用箭头函数写法 - Props 类型必须用 interface 定义，禁止用 type - 文件命名：组件用 PascalCase，工具函数用 camelCase - 每个文件只导出一个主要内容 # 目录结构 src/ app/ # Next.js App Router 页面 components/ # 通用组件 features/ # 按功能划分的模块 lib/ # 工具函数和配置 hooks/ # 自定义 Hooks
关键原则：越具体越好。"写好代码"这种空话对 AI 毫无帮助，而"所有 API 路由必须用 zod 做参数校验"则是明确可执行的约束。
不同技术栈的实战 Rules 写法
下面提供几个主流技术栈的 Rules 模板，可直接复制到项目中按需调整。
Go 后端项目
# Go 项目规范
- Go 版本：1.22，使用泛型特性
- Web 框架：Gin，路由统一在 router/ 目录注册
- 错误处理：所有错误必须用 fmt.Errorf("xxx: %w", err) 包装
- 日志：使用 zap，禁止使用 fmt.Println 打日志
- 接口返回格式：统一用 pkg/response 包的 Success/Fail 函数
- 数据库：GORM，模型定义在 model/ 目录，禁止在 handler 层直接操作 DB
- 测试：所有 service 层函数必须有对应单元测试
# 命名约定
- 包名：小写单词，禁止下划线
- 接口名：以 -er 结尾（如 UserStore, MessageSender）
- 私有函数：camelCase，公开函数：PascalCasePython FastAPI 项目
# Python/FastAPI 项目规范 - Python 版本：3.11+，使用 match-case、TypeAlias 等新特性 - 异步：所有 IO 操作必须用 async/await，禁止阻塞调用 - 类型标注：所有函数参数和返回值必须有类型标注 - 数据验证：用 Pydantic v2 的 model_validator，禁止手动 if 校验 - 依赖注入：通过 FastAPI Depends 管理，禁止使用全局变量 - 测试：pytest + httpx，覆盖率要求 80% 以上 # 项目结构 app/ api/ # 路由层，只做参数解析和响应组装 services/ # 业务逻辑层 repositories/ # 数据访问层 models/ # Pydantic 模型和 ORM 模型
目录级 Rules：.cursor/rules/ 的高级用法
Cursor 0.43 版本引入了 .cursor/rules/ 目录，支持更细粒度的规则管理。每个 .mdc 文件可以设置 globs 属性，让规则只在匹配的文件中生效：
--- description: React 组件开发规范 globs: ["src/components/**/*.tsx", "src/features/**/*.tsx"] alwaysApply: false --- # React 组件规范 - 使用 React.FC 类型声明，不写 return type - Props 解构放在函数参数里，不要在函数体内解构 - 副作用必须清理：useEffect 返回 cleanup 函数 - 禁止在组件内定义非 Hook 的函数，抽到组件外
常见的目录级 Rules 划分方式：
frontend.mdc：匹配src/**/*.tsx，约束前端组件写法api.mdc：匹配src/app/api/**，约束 API 路由规范tests.mdc：匹配**/*.test.ts，约束测试写法和断言风格scripts.mdc：匹配scripts/**，放宽规则（允许快速脚本写法）
让 Rules 真正生效的实践建议
写了 Rules 不等于 AI 就会遵守，以下几个经验能让效果最大化：
用否定句强调禁区：AI 对"禁止"、"不要"、"永远不"的响应比正面描述更可靠。"使用 Zustand" 不如 "使用 Zustand，禁止引入 Redux 或 Context API"
给出示例胜过说明：Rules 里放一段符合规范的代码示例，比描述规范更有效
定期迭代 Rules：每当 AI 犯了某类错误，就把对应约束补进 Rules，Rules 应该随项目演进
控制长度：Rules 不是越长越好，超过 500 行后注意力会下降，精炼比堆砌更重要
版本化管理：把
.cursorrules提交到 Git，让团队共享同一套 AI 上下文
掌握 Cursor Rules 的本质是：把你对项目的隐性理解，显式化地传递给 AI。这是目前让 AI 编程助手产出质量最稳定的方式之一，值得每个重度用户深入投入。
发布评论
热门评论区：