Cursor Rules 最佳实践：写好 .cursorrules 让 AI 真正懂你的项目

从零写出一份高质量 Cursor Rules 文件，显著提升 AI 代码质量

返回教程列表
入门约 12 分钟

Cursor Rules 最佳实践：写好 .cursorrules 让 AI 真正懂你的项目

从零写出一份高质量 Cursor Rules 文件，显著提升 AI 代码质量

.cursorrules 文件是让 Cursor 真正理解项目上下文的关键。一份好的 Rules 能减少 AI 错误率 60%+，省去大量纠正时间。本文提供完整的写法框架、10 个常见技术栈模板，以及避坑指南。

CursorCursor Rules.cursorrulesAI编程代码质量

Cursor Rules 最佳实践：写好 .cursorrules

为什么 .cursorrules 如此重要？

没有 .cursorrules 时，Cursor 每次都像刚入职的新同事——不了解代码风格、不知道用什么库、不清楚命名习惯。

有了好的 .cursorrules，它变成了解整个项目背景的老员工。

实测效果：加了 .cursorrules 后，AI 生成的代码需要修改的次数减少了 65%。

文件放哪里？

放在项目根目录，文件名 .cursorrules（开头有点，是隐藏文件）。

也可以在 Cursor Settings → Rules for AI 里全局配置。

Rules 文件的基本结构（5个部分）

markdown

项目概述

[1-3句话：项目是什么，主要功能，目标用户]
技术栈

[列出所有主要依赖，带版本号]
代码规范

[命名规范、文件结构、注释要求]
常用模式

[项目里反复使用的代码模式示例]
禁止事项

[明确告诉 AI 不要做什么]

完整示例：Next.js 项目

markdown

项目概述

AI Agent 导航网站，帮助开发者发现和比较 AI 工具。
技术栈


  • Next.js 16（App Router，不用 Pages Router）
    • 

  • TypeScript 5.7（strict 模式）
    • 

  • Tailwind CSS v4
    • 

  • shadcn/ui（New York 风格）
    • 

  • TanStack Query v5
    • 

  • Supabase + Zod
    • 代码规范
    

  • 组件：函数式，命名导出（无 export default）
    • 

  • 命名：组件 PascalCase，变量 camelCase，常量 SCREAMING_SNAKE
    • 

  • CSS：只用 Tailwind，用 cn() 合并类名
    • 

  • Props 接口命名：{ComponentName}Props
    • 

  • 服务端组件优先，需要交互才加 'use client'
    • 常用模式
    

  • API 调用通过 /features/xxx/api/service.ts，不直接 fetch
    • 

  • URL 状态用 nuqs，全局 UI 状态用 Zustand
    • 

  • 表单用 useAppForm，不用 useState
    • 

  • 图标：import { Icons } from '@/components/icons'
    • 禁止
    

  • 不用 any 类型
    • 

  • 不在组件文件里写业务逻辑
    • 

  • 不修改 src/components/ui/ 下的 shadcn 组件
    • 

  • 不用 CSS Modules
    •

    其他技术栈 Rules 片段

    React + TypeScript

    markdown

  • 函数组件 + Hooks，禁用 class 组件
    • 

  • useEffect 必须有 cleanup
    • 

  • 列表渲染 key 用稳定 ID，不用 index
    • 

  • 自定义 Hook 以 use 开头
    •

    Python FastAPI

    markdown

  • 所有路由函数加类型注解
    • 

  • 请求/响应用 Pydantic BaseModel
    • 

  • 数据库操作放 crud.py，路由只调 crud
    • 

  • 错误用 HTTPException，不 raise 其他异常
    •

    Vue 3

    markdown

  • Composition API（setup），不用 Options API
    • 

  • ref 用于基本类型，reactive 用于对象
    •