1. 为什么你的 Cursor 总是“不听话”很多人第一次打开 Cursor输入一句“帮我写个登录接口”结果它给你返回一个用 Flask 写的、还带一堆没用的注释、变量命名全是data1、temp的代码。你明明用的是 Spring Boot 项目它却按 Python 风格给你生成你项目里明明规定用 4 个空格缩进它偏给你 2 个空格你反复强调“不要用 Lombok”它下一段代码里又给你塞了个Data。这不是 Cursor 笨而是你没告诉它“规矩”。CursorRules 就是给 AI 编程助手立规矩的东西。它是一份放在项目里的规则文件Cursor 在生成代码、补全、重构之前会先读这份规则然后按规则约束自己的输出。你可以把它理解成给 AI 写的一份“项目开发手册”用什么语言、什么框架、什么命名风格、哪些文件不能碰、哪些依赖不能引入全部写清楚。写一次后面所有对话都自动遵守。这篇面向的是第一次接触 CursorRules 的开发者。我会从零开始给你一份可以直接复制到项目里的.cursorrules骨架再配上settings.json的全局配置片段最后手把手教你在 Cursor 里验证规则到底有没有生效。整套流程走完你就能建立一套可维护的 AI 编程规则体系而不是每次对话都靠“求”它。2. TaoToken 前置给 Cursor 接上稳定的模型通道Cursor 本身是一个编辑器它背后的代码生成能力依赖模型服务。默认情况下 Cursor 会走官方通道但很多人在实际使用中会遇到响应慢、额度不够、或者想切换不同模型对比效果的情况。这时候可以给 Cursor 配置一个兼容 OpenAI 接口协议的模型服务地址TaoToken 就是这样一个入口。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它提供标准的/v1/chat/completions接口Cursor 在设置里填上 Base URL 和 API Key 就能用。你需要先拿到一个 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制出来。这个 Key 只显示一次丢了就重新建一个。拿到之后在 Cursor 里按Ctrl Shift PMac 是Cmd Shift P输入Cursor: Settings找到Models区域把 OpenAI API Key 填进去同时在Override OpenAI Base URL里填https://taotoken.net/api。保存后 Cursor 就会走这个通道请求模型。如果你更习惯用命令行方式管理模型和额度可以打开 https://taotoken.net/console 查看用量和余额。想先试试模型对话效果直接进 https://taotoken.net/chat 就能对话不用装任何东西。对于长期用 Cursor 做编码和 Agent 任务的可以看看 https://taotoken.net/coding-plan 按编码场景做了额度规划比单次调用更划算。这一步做完Cursor 的模型通道就通了。接下来才是重点写规则。3. 可复制配置.cursorrules 骨架与 settings.json 片段3.1 先搞清楚两种规则放哪里Cursor 的规则分两层。一层是全局规则放在 Cursor 的设置里对所有项目生效另一层是项目规则就是项目根目录下的.cursorrules文件只对当前项目生效而且优先级高于全局规则。全局规则适合放你个人的通用偏好比如“永远用中文注释”“缩进用 4 个空格”“不要生成 TODO”。项目规则适合放这个项目特有的约束比如“这是 Spring Boot 项目包名 com.example.orderController 层不能直接调 Mapper”。两层配合使用全局定基调项目定细节。项目规则里没写的自动继承全局规则。3.2 一份可以直接用的 .cursorrules 骨架在项目根目录新建一个文件名字就叫.cursorrules注意前面有个点。把下面这段内容复制进去然后按你的项目实际情况改。# 项目技术栈 - 语言Java 17 - 框架Spring Boot 3.2 - 构建工具Maven - 数据库MySQL 8.0 MyBatis-Plus - 缓存Redis # 代码规范 - 缩进使用 4 个空格禁止使用 Tab - 所有类、方法、字段必须写 Javadoc 注释注释用中文 - 变量命名使用小驼峰常量全大写下划线分隔 - Controller 层只做参数校验和路由业务逻辑写在 Service 层 - Mapper 层只写 SQL不写业务判断 - 禁止在 Controller 里直接注入 Mapper # 依赖约束 - 禁止引入 Lombok所有 getter/setter 手写或用 IDE 生成 - 禁止引入 Fastjson统一使用 Jackson - 新增依赖必须在 pom.xml 中显式声明版本号 # 安全约束 - 禁止在代码中硬编码数据库密码、Redis 密码、API Key - 所有外部输入必须做参数校验使用 Valid 注解 - 禁止使用 System.out.println 输出日志统一用 Slf4j # 文件排除 - 不要修改 application-prod.yml - 不要修改 src/main/resources/db/migration 下的文件 - 不要读取 .env 和 *.key 文件 # 生成偏好 - 生成代码时优先给出完整可编译的类不要给片段 - 如果需求不明确先问我不要自己假设 - 重构时保持原有方法签名不变除非我明确要求改这份骨架覆盖了技术栈声明、代码规范、依赖约束、安全约束、文件排除和生成偏好六个维度。你不需要一次写全先把你最头疼的几个问题写进去比如“禁止用 Lombok”“Controller 不能调 Mapper”效果立竿见影。3.3 settings.json 全局配置片段全局规则在 Cursor 的设置界面里配置但如果你想像管理代码一样管理它可以直接改settings.json。打开命令面板输入Preferences: Open User Settings (JSON)在文件里加入下面这段{ cursor.rules.global: [ 所有代码注释使用中文, 缩进统一使用 4 个空格, 禁止生成 TODO 和 FIXME 注释, 生成代码时不要省略 import 语句, 如果代码超过 50 行先给出结构说明再写实现 ], cursor.rules.applyToAllProjects: true, cursor.rules.priority: project-first }这里cursor.rules.global是一个字符串数组每一项就是一条全局规则。cursor.rules.priority设为project-first表示项目规则优先于全局规则这也是推荐的做法。改完保存重启 Cursor 让配置生效。3.4 规则写法的几个实用技巧规则要写得具体不要写“代码要规范”这种空话。AI 不知道你说的“规范”是什么它需要明确的指令。比如“Controller 层只做参数校验和路由业务逻辑写在 Service 层”就比“分层要清晰”有用得多。规则要可验证。你写“禁止用 Lombok”那就在验证阶段故意让它生成一个实体类看它有没有偷偷加Data。能验证的规则才是有效规则。规则不要太多。一开始写 10 到 15 条就够了写太多 AI 反而会顾此失彼。后面根据实际踩坑情况慢慢加。4. 验证请求怎么确认规则真的生效了规则写完了怎么知道 Cursor 有没有在读不能靠感觉要用具体的测试用例来验证。4.1 测试一技术栈约束在 Cursor 的 Chat 里输入帮我写一个用户查询接口根据用户 ID 返回用户信息。如果规则生效它应该生成一个 Spring Boot 的 Controller 类包名符合你项目结构方法上有 Javadoc 中文注释注入的是 Service 而不是 Mapper返回类型是ResultUserVO之类的统一封装。如果它给你生成了一个 Python 的 Flask 路由或者一个没有注释的裸方法说明规则没生效。4.2 测试二依赖约束输入给我一个 User 实体类包含 id、name、email、createTime 四个字段。规则里写了“禁止引入 Lombok”那它应该手写 getter 和 setter而不是在类上加Data。如果它加了Data说明这条规则没被读到。4.3 测试三文件排除输入帮我看一下 application-prod.yml 里数据库配置对不对。规则里写了“不要修改 application-prod.yml”它应该拒绝读取或修改这个文件或者至少提示你这个文件在排除列表里。如果它直接读出来并给你分析说明排除规则没生效。4.4 测试四生成偏好输入帮我重构一下 OrderService 里的 createOrder 方法。规则里写了“重构时保持原有方法签名不变”它应该只改方法内部实现不改方法名、参数列表和返回类型。如果它把方法签名也改了说明这条规则没起作用。四个测试跑完你就能判断规则文件到底有没有被 Cursor 加载。如果全部通过说明配置成功如果有失败项回到.cursorrules检查对应规则是不是写得太模糊或者位置放错了。4.5 用 API 直接验证模型通道如果你想确认 TaoToken 通道本身是通的可以用 curl 直接发一个请求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API_KEY \ -d { model: gpt-4o, messages: [ {role: user, content: 用一句话说明什么是 CursorRules} ] }返回里如果有choices[0].message.content并且内容合理说明通道正常。这一步和 CursorRules 本身无关但能帮你排除“是模型通道问题还是规则问题”。5. 本篇常见错排查5.1 规则文件放了但完全不生效最常见的原因是文件名或位置不对。.cursorrules必须放在项目根目录也就是和pom.xml或package.json同一层。放在src下面、放在子模块里、或者文件名写成cursorrules少了前面的点都不会被识别。另一个原因是 Cursor 版本太旧。.cursorrules是较新版本才支持的功能如果你用的是很早以前的版本升级到最新版再试。5.2 规则生效了一部分另一部分没反应检查规则之间有没有冲突。比如全局规则写了“缩进用 2 个空格”项目规则写了“缩进用 4 个空格”项目规则优先级高应该以 4 个空格为准。但如果两条规则写在同一个层级里互相矛盾AI 可能会随机选一条执行。解决办法是把冲突的规则合并成一条或者删掉旧的那条。规则文件不是越多越好重复和矛盾的规则会让 AI 困惑。5.3 AI 假装遵守规则实际输出还是老样子这种情况通常是因为规则写得太抽象。比如你写“代码要安全”AI 不知道你指的是 SQL 注入、XSS 还是密码硬编码。改成“所有 SQL 必须用 MyBatis-Plus 的 Wrapper 构造禁止字符串拼接”就具体多了。另一个原因是规则太长AI 在生成时只读了前面几条就开始了。把最重要的规则放在文件最前面次要的放后面。5.4 修改规则后没有重新加载Cursor 不会实时监听.cursorrules文件的变化。改完规则后需要重启 Cursor或者至少新开一个 Chat 会话。在旧会话里继续对话用的还是旧规则。5.5 全局规则和项目规则打架如果你在全局设置里写了“所有项目用 2 个空格缩进”但某个项目需要 4 个空格就在该项目的.cursorrules里明确写“缩进用 4 个空格”。项目规则会覆盖全局规则。如果发现没覆盖检查cursor.rules.priority是不是设成了global-first改成project-first。5.6 规则里写了排除文件但 AI 还是读了排除规则对 Chat 和 Composer 的约束力有限。如果你在 Chat 里明确要求它读某个被排除的文件它可能还是会读。排除规则更多是“默认不主动碰”而不是“绝对禁止访问”。对于真正敏感的文件建议用.cursorignore配合使用或者在对话里明确说“不要读这个文件”。6. 把规则用起来让 Cursor 真正贴合你的项目规则写好了验证也通过了接下来就是日常使用。每次新开一个项目先把.cursorrules建起来哪怕只写三五条最关键的约束也比什么都不写强。用一段时间后你会发现 Cursor 生成的代码越来越像你自己写的变量命名、注释风格、分层结构都跟你项目里现有代码一致改起来省心很多。如果你还没配好模型通道可以先去 https://taotoken.net/api-keys 拿一个 Key然后在 Cursor 里填上 Base URLhttps://taotoken.net/api。想先感受一下模型对话效果直接打开 https://taotoken.net/chat 就能用。长期做编码和 Agent 任务的可以看看 https://taotoken.net/coding-plan 的额度方案。接入过程中遇到报错对照 https://taotoken.net/doc 的文档排查大部分问题都能找到原因。规则文件不是写完就完了它应该跟着项目一起迭代。每次发现 AI 又犯了同样的错就把那条约束补进.cursorrules。三个月后回头看你的规则文件就是一份完整的项目开发规范而 Cursor 就是那个最守规矩的团队成员。