.cursorrules：让 Cursor 按你的规矩写代码

Cursor 最值得花时间配的东西就是 .cursorrules。在项目根目录创建这个文件，AI 每次生成代码都会遵守里面的规则——相当于给 AI 一份项目编码规范。

# .cursorrules
技术栈
Frontend: Next.js 15 + TypeScript 5.7 + Tailwind CSS 4
Backend: tRPC + Drizzle ORM
Database: PostgreSQL 17
Testing: Vitest + Playwright
编码规范
React 组件一律用函数式 + hooks，禁用 class component
状态管理用 Zustand，不用 Redux / Context
数据获取用 TanStack Query，不用 useEffect + fetch
类型定义放 types/ 目录，用 Zod schema 做运行时验证
文件命名
组件: PascalCase (UserProfile.tsx)
工具函数: camelCase (formatDate.ts)
常量: SCREAMING_SNAKE_CASE
禁止事项
不用 any 类型，实在不知道用 unknown
不在 component 里直接调数据库
不硬编码 API URL，用环境变量
不用 var，只用 const / let

新版 Rules 系统

Cursor 已经支持更灵活的 .cursor/rules/ 目录结构：

.cursor/
  rules/
    global.mdc      # 全局规则，所有对话生效
    react.mdc       # 只在 .tsx 文件生效（文件级规则）
    api.mdc         # 只在 src/api/ 下生效（目录级规则）
    testing.mdc     # 手动引用的规则（Agent 按需读取）

每个 .mdc 文件的 frontmatter 指定作用范围：

| 类型 | 说明 | |------|------| | always | 每次对话都自动加载 | | auto-attached | 匹配 glob 模式时自动加载，如 globs: ["*/.tsx"] | | agent-requested | Agent 根据任务需要自己决定是否读取 | | manual | 只有你用 @rules 手动引用时才加载 |

建议每个项目 5-8 个规则文件，每个不超过 100 行。社区资源 awesome-cursorrules 有 React、Vue、Next.js、Python、Go 等上百个模板可以直接抄。

MCP：给 Agent 连接外部工具

MCP（Model Context Protocol）让 Cursor 的 Agent 调用外部工具——数据库、设计稿、浏览器、API 平台。在 Cursor Settings > Features > MCP 里添加，或者手动编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-playwright"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

配好后，Agent Mode 会自动识别可用的 MCP 工具。对话里说"查一下数据库里有哪些表"或"用 Playwright 截个图看看首页效果"，Agent 就会调用对应的 MCP Server。

实用 MCP 推荐：

| MCP Server | 用途 | |-----------|------| | Playwright | 浏览器自动化、截图、端到端测试 | | PostgreSQL/MySQL | 查 schema、跑 SQL、验证数据 | | GitHub | 读 issue、创建 PR、查 CI 状态 | | Figma | 读设计稿生成 UI 代码 | | Filesystem | 安全地读写指定目录的文件 |

Background Agent：云端异步编程

Background Agent 是 Cursor 的杀手级功能——把任务丢给云端 Agent，它在远程环境里自主执行，你关掉电脑都能继续跑。

使用方法：Composer 里点 Background Agent 图标（或搜索 Background Agent），描述任务后提交。Agent 会在云端 fork 一个分支，完成后你能看到所有改动的 diff，确认后合并。

# 适合 Background Agent 的任务：
- 给整个项目写单元测试
- 迁移数据库 schema + 更新所有查询
- 把项目从 JavaScript 迁到 TypeScript
- 批量重命名 API 接口 + 更新前端调用
不适合的任务：
- 需要实时反馈的 UI 调试
- 依赖本地环境变量或数据库的任务
- 需要你频繁确认方向的探索性任务

Notepads：可复用的上下文片段

Notepads 在左侧边栏，用来存项目级的上下文信息。和 .cursorrules 的区别：rules 是强制规则，Notepads 是参考资料。

创建几个常用 Notepad：

• 架构说明：项目整体结构、目录规范、数据流
• API 契约：前后端接口定义、字段说明
• 设计系统：颜色、字号、间距、组件规范

在 Composer 或 Chat 里用 @notepads 引用。Agent 会自动读取相关的 Notepad 内容，不用每次重新解释项目背景。

YOLO Mode：全自动执行

Cursor Settings 里搜索 auto-run，开启后 Agent 可以自动执行终端命令不需要你逐条确认。适合你信任 AI 输出、想让它一口气跑完的场景。

可以配置白名单，只允许自动执行特定命令：

npm install, npm run build, npm test, npx prisma generate

危险命令（rm -rf、DROP TABLE）即使开了 YOLO 也会弹确认。但还是建议只在个人项目里开——团队项目用默认的逐步确认更安全。