Rules 配置

Rules 是写给 Cursor AI 的项目说明书。你可以把技术栈、目录约定、代码风格、禁止事项写进去，让 AI 在每次对话和改文件时都把这些规则当成默认前提。

如果你只是偶尔让 Cursor 改一段代码，不一定需要 Rules。它真正有用的场景是：同一个项目里反复出现同类约束，而你不想每次都重新解释。

比如一个 Next.js 项目已经约定：

• 组件放在 src/components/
• 请求逻辑放在 src/lib/api/
• 表单统一用 react-hook-form
• 不允许在页面组件里直接写 fetch

这些信息如果只靠对话临时说明，很容易漏。Rules 的作用就是把这类重复前提固定下来。

.cursorrules 和 .cursor/rules/*.mdc

你可能会在老项目里看到根目录下的 .cursorrules 文件。它是早期常见的写法：整个项目一份规则，Cursor 在生成代码时参考它。

现在更推荐使用 .cursor/rules/*.mdc。这种方式可以把规则拆成多个文件，也可以给不同规则配置适用范围。比如：

.cursor/
  rules/
    project-overview.mdc
    frontend-style.mdc
    api-style.mdc

这样做的好处是规则不会全都挤在一个文件里。一个中等规模的项目，通常会同时有项目说明、前端约定、接口约定、测试约定，如果全部写进一个长文件，AI 读起来会变重，你自己维护也麻烦。

如果项目还在用 .cursorrules，不需要为了“新”而立刻重构。等你发现规则越来越长、不同目录需要不同要求时，再迁移到 .cursor/rules/*.mdc 更自然。

什么时候值得写 Rules

Rules 适合放稳定、反复出现、影响代码生成结果的信息。比如：

• 项目使用的框架和语言版本
• 目录分层和文件命名习惯
• API 返回格式、错误处理方式
• 测试框架和测试文件位置
• 不希望 AI 改动的区域

不适合放临时任务。比如“今天要把登录页改成蓝色”就不该写进 Rules，这种信息放在当前对话里更合适。

一个判断方法是：如果你已经连续三次对 Cursor 说了同一句约束，它大概率适合进入 Rules。

一个最小示例

假设你在做一个 Next.js + TypeScript 项目，可以先建一个 .cursor/rules/project.mdc：

---
description: Project conventions for this Next.js app
globs:
  - "src/**/*.ts"
  - "src/**/*.tsx"
alwaysApply: true
---

# Project Conventions

This project uses Next.js, TypeScript, and Tailwind CSS.

Keep UI components in `src/components/`.
Keep reusable hooks in `src/hooks/`.
Keep API client functions in `src/lib/api/`.

When adding new UI:
- Prefer existing components before creating new ones.
- Do not put data fetching directly inside shared UI components.
- Use TypeScript types instead of `any` unless there is a clear reason.

When changing behavior:
- Keep existing public props compatible unless the task explicitly asks to change them.
- Add or update tests when the changed logic has branching behavior.

这份规则不追求完整。它先把最容易影响生成结果的几件事说清楚：技术栈、目录、组件边界、类型约束、测试判断。

怎么验证它生效了

Rules 不是写完就万事大吉。你需要用一个小任务试一下：

请给这个项目新增一个用户头像组件，支持传入图片地址、用户名和尺寸。

看 Cursor 的结果：

• 文件是否放在你约定的目录里
• 是否用了项目已有的组件和样式方式
• 是否避免了你明确禁止的写法
• 它解释方案时有没有引用规则里的约定

如果它仍然把文件放错位置，不一定是 Cursor 没读 Rules，也可能是规则写得太抽象。把“保持项目结构清晰”改成“组件放在 src/components/，页面级组件放在 src/app/ 对应路由目录”，效果会稳定很多。

常见误用

最容易出问题的是把 Rules 当成项目百科。把产品背景、历史决策、接口文档、长篇日志都塞进去，AI 每次对话都背着一大包上下文，反而更容易抓不住当前任务。

Rules 应该短。宁愿写几条稳定约束，也不要写一份几千字的“项目全景介绍”。需要临时参考的文档，可以在对话里用 @file 或 @folder 指给 Cursor。

另一个误用是把规则写成愿望：

请写出高质量、可维护、优雅的代码。

这句话没有错，但对生成结果帮助很小。更好的写法是告诉它什么叫可维护：

业务分支超过 3 个时，优先拆出具名函数。
不要在 React 组件里直接拼接复杂请求参数，把转换逻辑放到 `src/lib/`。

Rules 配好之后，下一步要学的是怎么在单次任务里控制上下文。Rules 管长期约定，Context 管当前这次任务要看的材料。