Cursor Rules 在真实项目中的演化
大多数 Cursor Rules 教程都在讲”怎么写”，但实际工作中更困难的问题是：随着项目推进，Rules 应该怎么演化？
一个月前三行的 .cursorrules 现在可能已经膨胀到 300 行，有些规则早已过时，有些规则每天被打破——你不知道该删哪些、加哪些，更不知道什么时候这堆规则才算”好”了。
这篇文章不讲静态最佳实践，而是讲规则的生命周期：从哪里来，怎么生长，何时该重构。
一、第一周：从三行开始
几乎所有人的 Rules 都起步于对话挫败感。你让 Cursor 改一个 API，它把 camelCase 改成了 snake_case；你让它加一个组件，它用了整个项目都不用的 class component 写法。
于是你写下第一条规则：
使用 TypeScript 严格模式，所有变量名用 camelCase，React 组件使用函数式写法。这时候的 Rules 是被动的——哪里痛，贴哪里。三行、五行，每条规则背后都有一次具体的失望。
这个阶段的特征：
- 规则都是禁止型（“不要用 class component”、“不要写 console.log”）
- 没有结构，都在一个文件里
- 规则密度低，还没有冲突
这阶段的正确做法：先记录，先积累，不要急着整理。你还不知道哪些规则是真正重要的。
二、一个月后：膨胀与混乱
一个月后，Rules 文件可能长成这样：
# 技术栈
使用 React 18 + TypeScript + Tailwind CSS
后端用 FastAPI，数据库用 PostgreSQL
# 代码风格
camelCase 变量名
函数式 React 组件
不要写 any 类型，使用具体接口
# 项目规范
API 响应统一用 { data, error, code } 格式
所有日期用 ISO 8601 格式
错误处理要有具体的错误消息
# 注意事项
不要修改 auth 目录下的文件除非明确要求
数据库 migration 不要自动生成，等人工确认
新的第三方库需要先问我
... (后面还有 40 行)这时候出现了几个典型问题：
规则腐烂：三周前加的”不要使用 Redux，用 Zustand”可能已经被推翻了，但规则还在。Cursor 按照过时规则生成代码，你又要花时间纠正。
规则冲突：某条规则说”尽量复用现有组件”，另一条说”不要改动 UI 组件库目录”。Cursor 在两者之间摇摆，表现出不一致的行为。
规则失焦：Rules 文件开始承载太多东西——技术选型决策、代码风格、权限边界、临时注意事项——所有内容被平铺，优先级模糊。
诊断你是否到了这个阶段：如果你在审查 Cursor 输出时，脑子里会想”我不是已经说过这个了吗”，说明规则要么缺失要么失效。
三、分层：从混乱中找到结构
解决膨胀的第一步不是删减，而是分层。
Cursor 的 .cursor/rules/*.md 机制允许按文件 glob 加载不同规则集，这是解决分层问题的正确工具（而不是把所有内容堆进一个 .cursorrules）。
一个典型的分层结构：
.cursor/rules/
├── global.md # 所有文件都加载：项目概述、禁止行为、通信规范
├── frontend.md # *.tsx *.ts：React 规范、组件规则、状态管理
├── backend.md # *.py：FastAPI 规范、数据库操作、安全边界
├── tests.md # *.test.* *.spec.*：测试写法、mock 规范
└── migrations.md # db/migrations/**：数据库变更的特殊注意事项分层之后，每个规则文件的职责变得清晰，而且 Cursor 加载规则更精准——改前端代码时不会加载无关的数据库 migration 注意事项。
关于 .cursorrules 和 .cursor/rules/*.md 的写法基础，可以参考 .cursorrules 最佳实践，这里专注讲演化逻辑。
四、稳定期：有效规则的特征
度过混乱期后，哪些规则会留下来，哪些会消亡？
观察多个真实项目，长期有效的规则有几个共同特征：
特征一：对应真实且频繁的失误
## API 类型定义
所有 API 响应类型必须定义在 src/types/api.ts 中，不要在组件内联类型。这条规则存活，因为如果不写，Cursor 会在组件里内联类型，导致类型散落各处。这是真实、高频的问题。
反例：
## 日志
生产环境不要用 console.log这条规则在大多数项目里是 linter 规则，不需要出现在 Cursor Rules 里——linter 会自动拦截，让 Cursor 知道这条规则意义不大。
特征二：提供上下文，而非限制
## 权限系统
项目使用基于角色的 RBAC，角色定义在 src/constants/roles.ts。
修改任何涉及权限判断的代码时，先查看该文件了解角色层级。这种规则不是命令，而是导航。它让 Cursor 知道去哪里找信息，而不仅仅是”不要做什么”。
特征三：可验证
## 数据库操作
所有数据库写操作必须在事务中执行，使用 db.transaction() 包裹。这条规则 Cursor 能直接在代码里体现，reviewer 也能直接验证。
反例：
写代码要简洁清晰，注重代码质量这种规则没有操作意义，Cursor 无法转化为具体行为。
五、常见的演化陷阱
陷阱一：把架构决策写进 Rules
## 状态管理
使用 Zustand 而不是 Redux，因为更轻量；
使用 React Query 管理服务端状态，不要在 Zustand store 里放 API 数据这类规则正确，但它属于架构文档，不属于 Cursor Rules。架构文档放在 docs/ 或 README 里，需要团队成员都能看到和讨论；而 Cursor Rules 只有开发者在用 Cursor 时才会加载。
把架构决策混入 Rules 的后果：新人看 Rules 比看文档，导致文档荒废；架构调整时 Rules 更新不及时，产生误导。
陷阱二：临时规则变永久
## 临时注意
payment 模块正在重构，本周不要修改 src/payment/ 下的任何文件这类临时规则本该在重构完成后删除，但往往被遗忘。三个月后，新人还在遵守一个早已解除的禁令。
解决方案：临时规则加日期标注，建立定期清理习惯：
## 临时注意（2026-06-10 前有效）
payment 模块正在重构，本周不要修改 src/payment/ 下的任何文件陷阱三：用规则替代测试
## 数据校验
用户输入的 email 必须通过正则校验：/^[^\s@]+@[^\s@]+\.[^\s@]+$/这种规则应该是代码和测试，而不是 Cursor Rules。让 Cursor 每次都”记住”具体的正则，不如封装一个 validateEmail() 函数，让 Cursor 调用。
六、Rules 需要重构的信号
以下信号说明你的 Rules 需要整理了：
| 信号 | 说明 |
|---|---|
| Cursor 频繁忽略某条规则 | 规则太模糊或与模型的默认行为冲突，需要重写或删除 |
| 你在 prompt 里重复规则里的内容 | 规则没有被有效加载或太长导致被截断 |
| Rules 文件超过 200 行 | 该分层或精简了 |
| 同事看不懂 Rules 在说什么 | 规则假设了太多上下文，需要加背景说明 |
| 新人入职按 Rules 操作出错 | 规则有遗漏或不准确，可能是架构变了但规则没更新 |
七、一次真实的 Rules 重构案例
某个 6 个月大的 React + Node.js 项目，Rules 文件在重构前有 180 行，重构后 55 行，效果反而更好。
重构步骤：
- 导出清单：把所有规则列出来，标记”最近 30 天是否真的影响了 Cursor 输出”
- 删除已过时的：项目迁移到 Vite 后，关于 Webpack 配置的规则全部删除
- 移走架构文档：把 6 条架构决策说明移到
docs/architecture.md，Rules 里只留一行：“架构决策见 docs/architecture.md” - 合并重复的：5 条关于 TypeScript 类型的规则合并成 2 条更清晰的
- 分层：把剩余规则按前后端分入不同文件
- 测试效果：用 10 个典型任务测试新 Rules，对比老 Rules 下的输出质量
结果：Cursor 遵从率从约 60% 提升到约 85%（主观估计），生成代码的返工率明显下降。
八、团队场景下的 Rules 管理
如果是多人团队共用一套 Rules，还需要处理协作问题：
Rules 变更走 Code Review：.cursor/rules/*.md 文件纳入 Git 版本控制，修改需要和代码 PR 一样走 review 流程。这样可以防止一个人私自修改规则影响整个团队。
Rules 不是个人喜好：个人的代码风格偏好不应该进入团队 Rules。Rules 里的规则要有团队共识。
定期 Rules 回顾：每个 Sprint 结束或每月，团队集中讨论一次 Rules 是否需要更新。把 Rules 维护变成团队习惯，而不是某个人的负担。
如果你在用 Cursor 进行 API 开发并需要稳定的 AI 接入，YoTradeApi 提供国内可用的 Claude/GPT 中转，支持按量付费，适合团队共享使用。