先给结论
Cursor Rules 是让 AI 编程从「猜你想要什么」变成「按你的规矩干活」的唯一开关：把编码风格、目录约定、常用命令、禁区写进 .cursor/rules/ 下的 Markdown 文件，智能体每次会话都会先读，不需要你在聊天框里重复交代。配置成本约 10 分钟，收益是每次对话都少解释三遍。
规则文件最大的价值不是「让 AI 更聪明」，而是把你脑子里的团队约定外化成可版本化的文件。它既是 AI 的上下文，也是新同事的入职文档。
三种规则放哪里
| 类型 | 位置 | 生效范围 | 适合放什么 |
|---|---|---|---|
| 项目规则 | .cursor/rules/*.mdc | 当前仓库，可进 Git | 技术栈、目录约定、命令、禁区 |
| 用户规则 | 侧边栏「自定义 → 规则」 | 所有项目，随账号同步 | 表达偏好，如「回答简洁、别复述问题」 |
| AGENTS.md | 仓库根目录 | 当前仓库，自动识别 | 精简版项目说明，跨工具通用 |
四档生效方式，别全选「始终应用」
创建规则时 Cursor 会让你选类型，这个选择直接决定成本：
- Always（始终应用）：每次对话都塞进上下文。只给最核心的 1-2 条，写多了就是持续烧 token 。
- Auto Attached（应用到特定文件）：按 glob 匹配，比如
*.tsx才加载 React 规范。这是最该用的一档。 - Agent Requested（智能应用）：由模型自己判断相关性，但有 description 字段供它判断。
- Manual（手动）：只有你在对话里 @ 提它时才加载，适合低频的专项规范。
一条好规则长什么样
---
description: API 路由与错误处理约定
globs: app/api/**/*.ts
alwaysApply: false
---
# API 约定
## 错误返回
- 所有可能失败的操作用 Result 模式返回，不抛裸异常
- 校验失败统一 400 + { code, message }
## 参考实现
- 见 app/api/users/route.ts
- 见 lib/result.ts
## 禁区
- 不要在路由里直接写 SQL，走 lib/db 的仓储层
- 不要在响应里返回内部堆栈注意三点：引用文件而不是复制内容（代码变了规则不会过期）、给出反例（禁区比正面要求更有效）、规则保持聚焦（每条不超过 500 行，大规则拆成小文件）。
六个能立刻写的规则
- 项目地图：monorepo 有哪几个包、各自职责、入口在哪。
- 命令清单：
npm run build / typecheck / test，并注明「跑测试优先跑单个文件」。 - 代码风格：模块规范（ESM 优先）、导入写法、命名约定。
- 典型范例：新增一个 API 端点照哪个文件抄。
- 已知雷区：遗留模块别动、某服务返回值可能为 null 。
- 验证要求：改完必须跑什么命令才算完成。
什么时候不该加规则
① 能交给 linter/格式化工具的事（缩进、引号、分号）——加规则是浪费上下文。
② AI 本来就会的常见命令（git commit 、 npm install）。
③ 极罕见的边界情况——规则越多，每条被遵守的概率越低。
判断标准很简单：同一个错误你看到第二次，才值得写成规则。
② AI 本来就会的常见命令（git commit 、 npm install）。
③ 极罕见的边界情况——规则越多，每条被遵守的概率越低。
判断标准很简单：同一个错误你看到第二次，才值得写成规则。
把规则用进代码审查
规则写好后，审查环节也能复用。在仓库根放 BUGBOT.md，把资深工程师的判断标准固化：
- 改了
server/却没动测试文件 → 提示补测试； - 改了
auth/、payments/→ 要求安全审查； - 出现
.Result、.Wait()的异步写法 → 直接标红。
这样每次 PR 都自动跑一遍资深同事的脑子，而且标准恒定不会因为赶时间而缩水。
常见错误
- 规则写成风格指南大合集：一句话，让 linter 干 linter 的活。
- 全部设为 alwaysApply：上下文被规则塞满，真正的问题反而被挤掉。
- 不进 Git：规则不版本化，等于每个同事各写各的，团队收益归零。
- 一次写二十条：从最少的两三条开始，看到重复错误再补，否则你只是在写没人看的文档。
相关阅读
规则文件叫什么后缀？
放在
.cursor/rules/ 目录下，后缀为 .mdc，内容是 Markdown 加一段 frontmatter（description / globs / alwaysApply）。AGENTS.md 和项目规则冲突怎么办？
两者都会被读取，AGENTS.md 适合放跨工具通用的精简说明。需要更精细控制生效时机时，用 .cursor/rules/ 里的项目规则覆盖。
规则会拖慢响应速度吗？
会。 alwaysApply 的规则每次对话都进上下文，建议只留最核心的一两条，其余交给 globs 匹配或按需 @ 引用。
团队怎么共享规则？
把
.cursor/rules/ 整个目录提交到 Git 即可，同事拉代码后自动生效，不需要任何额外同步操作。
评论 (0)