★ FEATURED ARTICLE 1. 为什么你的 Cursor 总是“自作主张”从一次真实翻车说起你有没有遇到过这种情况让 Cursor 帮你改一个后端接口的返回格式结果它顺手把整个 Controller 层的命名风格全改了还“贴心”地删掉了你写了半天的注释。更崩溃的是它把error: 0改成了code: 200前端同学当场在群里 你。这不是 Cursor 笨而是你没给它立规矩。Cursor Rules 就是 AI 编码助手的“员工手册”——它规定了 AI 在你项目里能做什么、不能做什么、用什么技术栈、返回什么结构、注释怎么写。没有 Rules 的 Cursor就像一个刚入职但没人带的新人技术能力很强但完全不懂你们团队的规矩。这篇是 Cursor 教程的第二篇聚焦 Rules 配置实战。我会带你从零写出一套可直接复制的.cursorrules和.cursor/rules/*.mdc配置覆盖后端、前端、接口文档三个场景并给出用 VS Code 对照验证 Rules 是否生效的检查步骤。适合正在用 Cursor 做真实项目、被 AI 乱改代码困扰、想把提示词变成团队工程资产的开发者。核心检索词先明确Cursor Rules 是什么它是 Cursor 读取的规则文件用来约束 AI 编码助手的行为。能做什么统一代码风格、固定返回结构、强制中文回复、限制修改范围。适合谁所有用 Cursor 写生产代码的人尤其是团队协作场景。我试过在一个 Spring Boot 项目里不加任何 Rules让 Cursor 连续改了三个接口结果它每次返回结构都不一样前端联调时直接炸了。后来把 Rules 配好同样三个接口AI 生成的代码结构完全一致连注释格式都统一了。这就是 Rules 的价值把“每次都要重复说的话”变成“一次配置永久生效”。2. Cursor Rules 的两种形态与目录结构.cursorrules和.cursor/rules到底怎么选在动手写配置之前先把 Rules 的存放位置和生效范围搞清楚。Cursor 目前支持两种规则文件形态很多人混着用结果规则冲突AI 行为诡异。第一种是项目根目录下的.cursorrules文件。这是一个纯文本文件没有 frontmatter没有触发条件只要在项目根目录Cursor 就会自动读取。它的优点是简单直接适合放“全局通用规则”比如“始终用中文回复”“所有方法必须写注释”。缺点是所有规则一股脑塞进去项目大了之后文件会非常长而且没法针对特定文件类型做差异化控制。第二种是.cursor/rules/目录下的.mdc文件。这是 Cursor 推荐的现代做法每个规则文件独立支持 frontmatter 元数据可以设置alwaysApply、globs、description等字段实现“始终应用”“按文件后缀应用”“手动 引用”四种触发模式。团队协作场景强烈建议用这种因为每个规则文件可以单独 review、单独修改不会互相污染。目录结构建议这样组织your-project/ ├── .cursorrules # 全局兜底规则可选 ├── .cursor/ │ └── rules/ │ ├── 00-global.mdc # 全局中文回复、提交规范 │ ├── 10-backend.mdc # 后端分层、命名、异常处理 │ ├── 11-api-doc.mdc # 接口文档同步更新规范 │ ├── 20-frontend.mdc # 前端Vue3 Vant 技术栈 │ └── 30-framework-spring.mdc # 框架级Spring Boot 约定 ├── src/ └── README.md文件名前面的数字是排序用的Cursor 会按文件名顺序加载规则。00-放最通用的10-放后端20-放前端这样 AI 在处理不同文件时能按优先级匹配。关于触发模式.mdc文件的 frontmatter 支持四种触发模式frontmatter 写法适用场景Always ApplyalwaysApply: true全局规则每次对话都生效Intelligentlydescription: ...规则用于满足描述内容的文件Apply to Specific Filesglobs: src/**/*.java只对特定后缀或目录生效Apply Manual不设 alwaysApply不设 globs需要 手动引用才生效这里有个坑如果你同时写了alwaysApply: true和globsCursor 会以alwaysApply为准globs被忽略。所以想按文件类型生效就不要写alwaysApply: true。另外用户级规则账号通用在 Cursor 设置里的 Rules for AI 中配置比如“Always respond in 简体中文”。项目级规则优先级高于用户级两者会合并但项目级可以覆盖用户级。团队协作时把项目级规则提交到 Git新成员拉下来就自动生效不用每个人手动配。3. 可直接复制的 Rules 配置片段后端、前端、接口文档三件套这一节是全文的核心给出可以直接复制到项目里的配置片段。每个片段都标注了文件路径和触发模式你按自己的项目结构微调即可。3.1 全局规则.cursor/rules/00-global.mdc这个文件放最通用的约束比如中文回复、提交规范、禁止行为。--- description: 全局通用规则所有对话生效 alwaysApply: true --- ## 响应语言 - 始终使用简体中文回复用户代码注释可以用英文但优先中文。 ## Git 操作 - 完成一项功能开发后主动执行 commit。 - commit message 使用简洁中文格式feat: 新增用户登录接口。 - 不要在一个 commit 里混入多个不相关的修改。 ## 禁止行为 - 不允许在对话中执行 npm run dev 或 mvn spring-boot:run 启动项目。 - 不允许创建测试文档或临时说明文件。 - 不允许修改与当前任务无关的代码。 - 不允许使用未经验证的第三方依赖。3.2 后端规则.cursor/rules/10-backend.mdc后端规则重点约束分层结构、返回格式、异常处理。这里给出一个 Spring Boot 项目的配置。--- description: 后端开发规则适用于 Java 和 Spring Boot 项目 globs: src/main/java/**/*.java --- ## 项目结构 - 按功能或领域划分目录遵循关注点分离原则。 - Controller 层只做参数校验和路由不写业务逻辑。 - Service 层写业务逻辑Manager 层做数据聚合Mapper 层做数据访问。 - 目录嵌套不超过 4 层。 ## 返回格式 所有接口统一返回以下结构不允许自定义其他格式 json { error: 0, body: {}, message: success, success: true }error为 0 表示成功非 0 表示业务错误码。body为数据体没有数据时返回空对象{}。message为提示信息成功时固定为success。success为布尔值与error 0保持一致。代码规范每个方法必须写注释说明功能、入参、返回值。单个方法行数不超过 300 行。使用描述性的变量名和函数名禁止a、b、tmp这类命名。异常必须捕获并转换为统一返回结构不允许直接抛到 Controller。优先使用项目已有的工具类和枚举不重复造轮子。生成代码前检查生成任何业务代码前先查看func.md文档确认是否已有相关服务。如果已有类似功能优先扩展现有方法而不是新建类。新增服务后同步更新func.md文档。### 3.3 前端规则.cursor/rules/20-frontend.mdc 前端规则约束技术栈和组件使用避免 AI 引入不相关的库。 markdown --- description: 前端开发规则适用于 Vue3 项目 globs: src/**/*.vue,src/**/*.js --- ## 技术栈 - 使用 Vue3 Vant 框架使用原生 JavaScript不使用 TypeScript。 - 状态管理使用 Pinia管理用户登录态和购物车数据。 - 所有后端调用必须走 src/api 目录下的 API 封装不允许在页面里直接写 axios。 - 优先使用 Vant 现有组件不重复实现。 ## 页面结构 - 页面组件嵌套不超过 3 层。 - 开发页面前先扫描 README.md 的项目结构看是否有可复用组件或工具方法。 - 更新文件后同步更新 README.md 中的项目结构目录。 ## 限制 - 不允许在 Vue 页面中定义测试数据所有数据必须来自后端服务或 mock 接口。 - 不允许创建测试用例除非明确要求。 - 使用真实 UI 图片不使用占位符图片。3.4 接口文档规则.cursor/rules/11-api-doc.mdc接口文档规则强制 AI 在改接口时同步更新文档这是团队协作中最容易被忽略的一环。--- description: API 文档同步规则 globs: src/main/java/**/controller/**/*.java --- ## 文档同步要求 当生成或修改 API 接口时以下变更必须同步更新 API 文档 - 入参结构变更 - 返回参数变更 - URL 地址变更 - 请求方式变更 ## 文档格式 每个接口文档包含以下部分 ### 基本信息 - 接口名称简短描述 - 功能描述详细业务用途 - 接口地址/api/endpoint - 请求方式GET/POST ### 请求参数 用 JSON 示例加表格说明表格列参数名、类型、必填、说明、示例值。 ### 响应参数 用 JSON 示例加表格说明如果 body 是对象列出所有子字段格式为 body.字段名。 ## 注意 - 文档中的示例值必须真实可用不允许写 xxx 或 test。 - 如果接口有分页必须说明默认页码和每页数量。3.5 框架级规则.cursor/rules/30-framework-spring.mdc框架级规则可以引用社区维护的规则库。比如 Spring Boot 的规则可以参考awesome-cursor-rules-mdc项目里的配置把常用的分层约定、注解使用规范复制进来。这里给一个精简版--- description: Spring Boot 框架约定 globs: src/main/java/**/*.java --- ## 注解使用 - Controller 使用 RestController不混用 Controller。 - Service 实现类使用 Service接口不加注解。 - 依赖注入优先使用构造器注入不使用 Autowired 字段注入。 ## 配置管理 - 配置项统一放在 application.yml不使用 application.properties。 - 敏感配置使用环境变量占位符 ${DB_PASSWORD}不硬编码。 ## 日志 - 使用 SLF4J不使用 System.out.println。 - 日志级别入口用 info异常用 error调试用 debug。这些配置片段可以直接复制到你的项目里按实际包名和目录调整globs即可。配好之后Cursor 在生成代码时会自动读取这些规则你不需要每次在对话里重复“用中文回复”“返回结构要统一”。4. 验证 Rules 是否生效用 VS Code 对照检查的完整步骤配好 Rules 之后怎么确认它真的生效了很多人配完就不管了结果 AI 行为没变化以为是 Cursor 的 bug。其实大概率是规则文件没被读取或者触发条件写错了。下面是一套用 VS Code 对照验证的检查步骤你可以跟着做一遍。4.1 检查文件位置和命名首先确认.cursor/rules/目录在项目根目录下不是src/里面。用 VS Code 打开项目在资源管理器里应该能看到.cursor/ rules/ 00-global.mdc 10-backend.mdc如果看不到.cursor目录可能是被隐藏了。在 VS Code 设置里搜索files.exclude确认没有把.cursor排除掉。另外.mdc文件的后缀必须是.mdc不是.md写错了 Cursor 不认。4.2 检查 frontmatter 格式打开一个.mdc文件确认开头是三横线包裹的 frontmatter--- description: 后端开发规则 globs: src/main/java/**/*.java ---注意globs的值要用引号包裹多个 glob 用逗号分隔。如果globs写成了src/main/java/**/*.java但没加引号YAML 解析可能出错规则就不生效。4.3 用 VS Code 的 Cursor 插件查看规则加载状态Cursor 是基于 VS Code 的如果你在 VS Code 里装了 Cursor 插件可以在输出面板里看到规则加载日志。步骤打开 VS Code按Ctrl Shift U打开输出面板。在右上角下拉框选择Cursor或Cursor Rules。查看日志里是否有Loaded rule: 10-backend.mdc这样的信息。如果没有日志说明规则文件没被识别。检查文件是否在.cursor/rules/下frontmatter 是否合法。4.4 用实际对话验证规则生效最直接的验证方式是开一个 Cursor 对话让它生成一段代码看是否符合规则。比如你的后端规则里写了“返回结构统一为 error/body/message/success”那就输入帮我写一个查询用户信息的接口返回用户 ID、用户名、邮箱。如果规则生效AI 生成的代码应该包含统一的返回结构而不是直接返回User对象。如果它返回了User对象说明规则没生效回到 4.1 检查文件位置。再比如全局规则里写了“始终使用简体中文回复”如果 AI 用英文回复说明00-global.mdc没被加载。检查alwaysApply: true是否写对。4.5 用手动引用验证 Manual 规则如果你有规则设置了手动触发不写alwaysApply不写globs需要在对话里用引用。比如10-backend 帮我写一个订单创建接口如果引用后 AI 行为符合规则说明 Manual 规则配置正确。如果引用后没反应检查文件名是否写对Cursor 里后面跟的是文件名不含.mdc后缀。4.6 常见验证失败的原因现象可能原因解决方法AI 不遵守返回格式globs没匹配到当前文件检查文件路径是否在 glob 范围内AI 用英文回复全局规则没加载确认alwaysApply: true写在 frontmatter规则冲突AI 行为随机多个规则文件内容矛盾合并冲突规则或调整加载顺序Manual 规则不生效对话里没加引用在输入框用文件名引用改了规则但没变化Cursor 缓存了旧规则重启 Cursor 或重新打开项目验证通过后把.cursor/rules/目录提交到 Git团队其他成员拉下来就自动生效。新成员不需要手动配置AI 行为就和团队规范一致了。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth 一次讲清在配置 Cursor Rules 和接入模型服务的过程中你可能会遇到一些报错。这一节把最常见的几类错误和排查方法列出来对照真实报错信息定位问题。5.1 401 UnauthorizedAPI Key 无效或未配置报错信息通常长这样Error: 401 Unauthorized {error:{message:Invalid API key provided,type:invalid_request_error}}这个错误说明请求携带的 API Key 无效。排查步骤第一检查 Key 是否复制完整。很多人在控制台复制 Key 时漏掉了开头或结尾的字符导致鉴权失败。重新复制一次确保没有多余空格。第二检查 Key 是否过期或被删除。登录控制台在 API Keys 页面确认 Key 状态是 active。第三检查请求头格式。Base URL 和 Key 的配置要匹配比如Base URL: https://taotoken.net/api API Key: sk-xxxxxxxxxxxxxxxx Model ID: claude-sonnet-4-20250514如果你用的是 Claude Code 或 Cline 这类工具配置项名称可能不同但核心三件套不变Base URL、API Key、Model ID。缺一个都会报 401。5.2 local proxy failed本地代理连接失败报错信息Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890这个错误说明工具尝试连接本地代理端口但端口没有服务在监听。常见原因是之前配过代理后来关掉了但配置还留在环境变量或工具设置里。排查方法检查系统环境变量HTTP_PROXY和HTTPS_PROXY如果指向了一个不存在的端口删掉或改成正确的。在 Cursor 设置里搜索proxy确认没有开启不需要的代理配置。如果你没有使用任何代理直接把相关配置清空即可。TaoToken 的 API 地址是直连的不需要额外代理。5.3 reading choices响应格式解析失败报错信息Error: reading choices: unexpected end of JSON input这个错误通常出现在流式响应场景。工具期望收到 OpenAI 格式的choices数组但实际收到的响应不是标准格式或者响应被截断了。排查步骤第一确认 Base URL 是否正确。有些工具默认拼接/v1/chat/completions如果你的 Base URL 已经包含了/api再拼/v1就会 404返回 HTML 错误页解析 JSON 时就会报reading choices。第二确认 Model ID 是否拼写正确。模型名写错时部分服务会返回错误信息而不是标准响应导致解析失败。第三检查网络是否稳定。流式响应中途断开也会导致 JSON 不完整。可以先用非流式模式测试确认基础请求能通。5.4 OAuth 相关报错认证流程未完成报错信息Error: OAuth authentication failed: invalid_grant这个错误出现在使用 OAuth 登录的场景比如 Claude Code 的账号授权。invalid_grant通常表示授权码已过期或被重复使用。排查方法重新发起 OAuth 流程不要复用之前的授权链接。如果多次失败检查系统时间是否准确时间偏差过大会导致 token 校验失败。如果你用的是 API Key 模式而不是 OAuth这个错误不会出现。在 Claude Code 里可以通过auth.json配置 API Key 模式避免 OAuth 流程。auth.json的路径通常在~/.claude/auth.json内容格式{ apiKey: sk-xxxxxxxxxxxxxxxx, baseUrl: https://taotoken.net/api }配置好后Claude Code 会直接用 API Key 鉴权不走 OAuth。5.5 规则不生效但没有任何报错这是最隐蔽的问题没有报错但 AI 就是不遵守规则。排查思路第一确认.mdc文件的 frontmatter 是合法的 YAML。可以用在线 YAML 校验工具检查常见错误是冒号后面没空格、引号不匹配。第二确认globs匹配到了当前编辑的文件。比如你写的是src/main/java/**/*.java但当前文件在src/test/java/下就不会匹配。第三确认没有多个规则文件冲突。比如00-global.mdc说“用中文回复”10-backend.mdc说“用英文回复”AI 会随机选一个。合并冲突规则即可。第四重启 Cursor。规则文件修改后Cursor 有时不会热加载重启后才会重新读取。6. 把 Rules 变成团队资产从个人配置到协作规范的落地建议Rules 配好之后怎么让它从“个人技巧”变成“团队资产”这一节给几个落地建议。第一把.cursor/rules/目录提交到 Git和代码一起版本管理。新成员克隆项目后Cursor 自动读取规则不需要口头传达“我们返回结构要统一”。规则变更走 PR review和代码变更一样有记录。第二规则文件按职责拆分不要一个文件塞所有内容。全局规则、后端规则、前端规则、接口文档规则分开每个文件不超过 100 行。这样修改时影响范围可控review 也清晰。第三定期清理过期规则。项目技术栈升级后旧规则可能不再适用。比如从 Vue2 升级到 Vue3前端规则里的选项式 API 约定就要删掉。建议每个季度 review 一次规则文件。第四给规则文件写注释说明每条规则的背景。比如“返回结构统一为 error/body/message/success”这条注释里写“前端统一按 error 字段判断成功失败不要改”。这样后来的人知道为什么这么定不会随手删掉。第五用手动规则处理低频场景。比如代码重构规范、数据库迁移规范不需要每次对话都生效配成 Manual 规则需要时引用即可。这样避免规则文件过长影响 AI 响应速度。如果你在团队里推广 Cursor建议先在一两个项目试点把 Rules 配好跑两周收集反馈后再推广到其他项目。规则不是越多越好而是越准越好。一条“返回结构统一”的规则比十条“代码要优雅”的规则有用得多。最后如果你需要接入模型服务来配合 Cursor 使用可以走 API Keys 页面创建 Key接入文档里有各工具的配置示例。验证模型是否可用时用模型对话页面发一条测试消息即可。长期做编码和 Agent 任务的话Coding Plan 更适合高频使用场景。
阅读完成 · 觉得有帮助？
