1. 为什么你的 Cursor 总写出“不像自己项目”的代码刚用 Cursor 那阵子我最常遇到的场景是这样的项目里明明统一用 4 空格缩进、接口层必须带 JSDoc 注释、状态管理只允许用 Zustand结果 AI 补全出来的代码偏偏用 2 空格、注释全靠// TODO、还顺手给我引了个 Redux Toolkit。每次都得手动改一遍改到最后我甚至怀疑——到底是我在用 AI还是 AI 在训练我给它擦屁股。这个问题的根源不在模型能力而在于 Cursor 默认不知道你项目的“潜规则”。它看到的是当前打开的文件片段看不到你团队沉淀在 README、ESLint 配置、代码评审意见里的那些约定。Cursor Rules 就是用来补这块信息的它是一组可配置的指令告诉 AI 在生成、修改、理解代码时应该遵守什么风格、什么边界、什么技术选型。具体来说Rules 能约束三类行为应该做什么比如“新增 API 路由必须写 Zod 校验”、不应该做什么比如“禁止在组件里直接调 fetch”、以及怎么做比如“日期统一用 dayjs不用 moment”。它适合个人开发者统一自己的编码习惯也适合团队把评审标准前置到 AI 生成阶段。而 Rules 本身是分层的这也是很多人配了却没生效的原因。你可能会在global.rules、User Rules、Project Rules 之间来回切换却搞不清谁覆盖谁。这篇就按“分层配置 可复制片段 验证是否生效”的顺序把 Cursor Rules 从 global.rules 到 Project Rules 的实践讲透顺带把团队协作里规则文件怎么组织也说清楚。2. Cursor Rules 分层配置global.rules、User Rules 与 Project Rules 的边界先把概念对齐。Cursor 的 Rules 不是单一文件而是按作用范围分成几个层级理解它们的边界比背语法重要得多。User Rules 是账号级的跟着你的 Cursor 账号走换项目也生效。它适合放“跨项目通用”的偏好比如“始终用中文回答”“解释代码时先给结论再给细节”“不要主动重构我没让你动的文件”。这类规则不该塞项目特有的东西否则换个项目就变成噪音。Project Rules 是项目级的存在项目目录里跟着 Git 走团队共享。它才是放框架约定、API 规范、目录结构约束的地方。Cursor 现在主推的是.cursor/rules/目录下的.mdc文件每个文件可以带 frontmatter 控制生效范围比如只对src/api/**生效。老项目里你可能还会看到根目录的.cursorrules单文件它仍然能用但组织能力弱团队协作时容易变成一坨。global.rules 这个概念在不同版本里表述不太一样本质上指的是“对所有项目生效的通用规则层”。在实际分层里我习惯把它理解成三层通用规则跨语言比如命名、注释、安全底线、语言规则针对 Go/Python/TS 等、框架规则针对 Next.js、React、FastAPI 等。User Rules 承载通用层Project Rules 承载语言层和框架层这样职责最清晰。优先级关系上越靠近项目的规则越具体应该覆盖越通用的规则。也就是说 Project Rules 里的框架规则 语言规则 User Rules 里的通用偏好。但要注意Cursor 不是严格的“后者覆盖前者”的配置合并而是把这些规则一起塞进上下文靠语义让模型判断。所以规则之间如果互相矛盾模型会摇摆。我的做法是通用层只写“不会和任何项目冲突”的底线具体风格全部下沉到 Project Rules避免打架。团队协作里规则文件的组织方式直接决定它会不会腐烂。我的建议是按“目录 职责”拆.mdc文件而不是写一个巨大的.cursorrules。比如00-base.mdc放通用底线10-typescript.mdc放语言规则20-nextjs.mdc放框架规则30-api.mdc用 globs 限定只对 API 目录生效。这样谁改哪块一目了然评审时也能单独讨论。3. 可复制配置.cursorrules 与 Project Rules 片段这一节直接给能抄的配置。先说过渡期的.cursorrules再说现在推荐的.cursor/rules/*.mdc。如果你项目还在用根目录单文件.cursorrules可以这样写注意它是纯文本不需要 frontmatter# 通用底线 - 始终用中文回答解释改动原因时先给结论。 - 不要主动重构未被要求的文件改动范围最小化。 - 新增依赖前必须先说明理由不要静默引入。 # TypeScript / React 约定 - 使用 2 空格缩进字符串统一双引号语句结尾带分号。 - 组件一律函数式 hooks禁止 class 组件。 - 状态管理统一用 Zustand禁止引入 Redux。 - 所有网络请求走 src/lib/request.ts 封装禁止组件内直接 fetch。 - 类型定义优先 interface联合类型用 type。 # API 层约定 - 新增接口必须写 Zod schema 做入参校验。 - 接口返回统一 { code, data, message } 结构。 - 错误处理用 try/catch 统一 logger禁止 console.log。但更推荐的是 Project Rules 目录方式。先建目录mkdir -p .cursor/rules然后写00-base.mdc这是通用底线alwaysApply: true表示始终注入--- description: 项目通用底线规则 alwaysApply: true --- - 始终用中文回答解释改动先给结论。 - 改动范围最小化不主动重构无关文件。 - 新增依赖前说明理由。再写10-typescript.mdc用 globs 限定只对 TS 文件生效--- description: TypeScript 与 React 编码约定 globs: [src/**/*.ts, src/**/*.tsx] alwaysApply: false --- - 2 空格缩进双引号语句结尾分号。 - 组件用函数式 hooks禁止 class 组件。 - 状态管理统一 Zustand禁止 Redux。 - 网络请求走 src/lib/request.ts禁止组件内直接 fetch。 - 类型优先 interface联合类型用 type。最后写30-api.mdc只对 API 目录生效把接口规范钉死--- description: API 层接口规范 globs: [src/api/**/*.ts] alwaysApply: false --- - 新增接口必须写 Zod schema 做入参校验。 - 返回统一 { code, data, message } 结构。 - 错误用 try/catch 统一 logger禁止 console.log。 - 每个导出函数必须有 JSDoc说明参数与返回。这里有个关键点globs写对了规则才会在对应文件被打开时注入。alwaysApply: true的规则会一直占用上下文所以只放真正全局的底线别把框架细节塞进去否则上下文被稀释模型反而抓不住重点。如果你用的是 Cursor 的图形界面User Rules 在 Settings 里配置直接粘贴通用偏好即可比如“始终用中文回答”“不要主动重构”。它和 Project Rules 是叠加关系不是替代关系。4. 验证规则是否生效具体操作步骤与成功结果配完不验证等于没配。下面是我实测下来比较靠谱的验证流程。第一步确认规则文件被识别。在 Cursor 里打开 Chat输入看看能不能引用到规则文件或者打开 Settings 的 Rules 面板Project Rules 应该列出你.cursor/rules/下的所有.mdc。如果没列出来多半是目录层级不对——.cursor/rules/必须在项目根目录不能嵌套在src里。第二步做一次“对抗性测试”。故意让 AI 生成一段违反规则的代码看它会不会被拉回来。比如在src/api/user.ts里输入帮我写一个获取用户列表的接口函数如果30-api.mdc生效它应该输出带 Zod 校验、返回{ code, data, message }、带 JSDoc 的代码。如果它直接给你一个裸fetch加console.log说明规则没注入。第三步验证 globs 的边界。在src/components/UserList.tsx里输入同样的请求这次30-api.mdc不该生效因为 globs 只匹配src/api/**但10-typescript.mdc应该生效输出应该是函数式组件、Zustand、走封装请求。如果 API 规则也跑进来了说明你的 globs 写宽了。第四步看 Cursor 的规则命中提示。新版 Cursor 在 Chat 回复上方会显示本次引用了哪些 Rules点开能看到具体文件。这是最直接的证据。如果列表里没有你期望的规则回去检查alwaysApply和globs。成功的结果长这样你在 API 目录里让 AI 加接口它自动带上 Zod schema 和统一返回结构你在组件目录里让它加交互它自动用 Zustand 而不是useState堆状态你让它解释代码它用中文先给结论。这时候规则才算真正落地。5. 常见报错排查401、local proxy failed 与规则不生效规则配好了但请求层面也可能出问题。下面是我踩过的几类。第一类401 Unauthorized。这通常和 Rules 无关而是模型请求的鉴权失败。如果你是通过 API 方式接入模型检查 Key 是否过期、Base URL 是否写对。用 TaoToken 这类统一入口时Base URL 填https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。401 出现时先确认 Key 有没有多余空格再确认请求头是不是Authorization: Bearer key。第二类local proxy failed或连接超时。这类报错多半是本地网络到接口端点的链路问题不是 Rules 语法问题。先确认 Base URL 可达再确认没有把端点写成带路径的完整 URL有些客户端要求 Base URL 不带/v1由客户端自己拼。如果你在 Cursor 里配的是自定义模型端点检查 Settings 里的 Override OpenAI Base URL 是否和文档一致。第三类规则“看起来配了但不生效”。这是最高频的。排查顺序先看.cursor/rules/是否在项目根目录再看.mdc的 frontmatter 有没有写错globs是数组还是字符串必须是数组再看alwaysApply是不是全设成了false导致没有任何规则常驻最后看规则之间有没有互相矛盾比如 User Rules 说“用单引号”Project Rules 说“用双引号”模型就会随机选。第四类reading choices之类的解析报错。这通常是接口返回结构和你客户端预期不一致比如你用了 OpenAI 兼容格式但端点返回了别的结构。确认 Base URL 和模型 ID 匹配模型 ID 要填端点实际支持的名称别自己编。如果你在 Cursor 里接的是 Claude Code 或 Codex 这类编码 Agent配置要写全三件套Base URL、Key、Model ID。缺一个都会导致请求失败或规则不加载。Base URL 用https://taotoken.net/apiKey 用控制台生成的Model ID 按文档里列出的填。三件套对齐后再回头看 Rules 是否生效才有意义。6. 把 Rules 接进你的日常编码流规则配完不是终点怎么让它持续有用才是。我的做法是把 Rules 当成代码评审的前置层每次评审发现 AI 反复犯的错就补一条到对应的.mdc里而不是只在评审里说一次。这样规则库会跟着项目一起长。团队协作上.cursor/rules/一定要进 Git并且在 PR 里像评审代码一样评审规则改动。谁加的规则、为什么加、影响哪些目录都写清楚。避免有人往00-base.mdc里塞框架细节那会污染所有项目文件。另外规则不是越多越好。上下文是有预算的alwaysApply: true的规则每条都在消耗预算。我的经验是常驻规则控制在 5 条以内其余全部用globs按需注入。这样模型在具体文件里能拿到最相关的约束而不是被一堆无关规则干扰。如果你还没开始配建议从00-base.mdc加一条“改动范围最小化”开始先感受规则生效带来的差异再逐步下沉语言和框架规则。需要生成 Key 或查看接入文档时可以从 API Keys 页面和接入文档入手想先验证模型对话效果用模型对话页面试几轮如果是长期编码或 Agent 场景直接上 Coding Plan 更省心。规则调顺之后你会发现 Cursor 的输出终于开始像“你写的代码”了。 Cursor Rules 使用指南：从 global.rules 到 Project Rules 的配置实践
1. 为什么你的 Cursor 总写出“不像自己项目”的代码刚用 Cursor 那阵子我最常遇到的场景是这样的项目里明明统一用 4 空格缩进、接口层必须带 JSDoc 注释、状态管理只允许用 Zustand结果 AI 补全出来的代码偏偏用 2 空格、注释全靠// TODO、还顺手给我引了个 Redux Toolkit。每次都得手动改一遍改到最后我甚至怀疑——到底是我在用 AI还是 AI 在训练我给它擦屁股。这个问题的根源不在模型能力而在于 Cursor 默认不知道你项目的“潜规则”。它看到的是当前打开的文件片段看不到你团队沉淀在 README、ESLint 配置、代码评审意见里的那些约定。Cursor Rules 就是用来补这块信息的它是一组可配置的指令告诉 AI 在生成、修改、理解代码时应该遵守什么风格、什么边界、什么技术选型。具体来说Rules 能约束三类行为应该做什么比如“新增 API 路由必须写 Zod 校验”、不应该做什么比如“禁止在组件里直接调 fetch”、以及怎么做比如“日期统一用 dayjs不用 moment”。它适合个人开发者统一自己的编码习惯也适合团队把评审标准前置到 AI 生成阶段。而 Rules 本身是分层的这也是很多人配了却没生效的原因。你可能会在global.rules、User Rules、Project Rules 之间来回切换却搞不清谁覆盖谁。这篇就按“分层配置 可复制片段 验证是否生效”的顺序把 Cursor Rules 从 global.rules 到 Project Rules 的实践讲透顺带把团队协作里规则文件怎么组织也说清楚。2. Cursor Rules 分层配置global.rules、User Rules 与 Project Rules 的边界先把概念对齐。Cursor 的 Rules 不是单一文件而是按作用范围分成几个层级理解它们的边界比背语法重要得多。User Rules 是账号级的跟着你的 Cursor 账号走换项目也生效。它适合放“跨项目通用”的偏好比如“始终用中文回答”“解释代码时先给结论再给细节”“不要主动重构我没让你动的文件”。这类规则不该塞项目特有的东西否则换个项目就变成噪音。Project Rules 是项目级的存在项目目录里跟着 Git 走团队共享。它才是放框架约定、API 规范、目录结构约束的地方。Cursor 现在主推的是.cursor/rules/目录下的.mdc文件每个文件可以带 frontmatter 控制生效范围比如只对src/api/**生效。老项目里你可能还会看到根目录的.cursorrules单文件它仍然能用但组织能力弱团队协作时容易变成一坨。global.rules 这个概念在不同版本里表述不太一样本质上指的是“对所有项目生效的通用规则层”。在实际分层里我习惯把它理解成三层通用规则跨语言比如命名、注释、安全底线、语言规则针对 Go/Python/TS 等、框架规则针对 Next.js、React、FastAPI 等。User Rules 承载通用层Project Rules 承载语言层和框架层这样职责最清晰。优先级关系上越靠近项目的规则越具体应该覆盖越通用的规则。也就是说 Project Rules 里的框架规则 语言规则 User Rules 里的通用偏好。但要注意Cursor 不是严格的“后者覆盖前者”的配置合并而是把这些规则一起塞进上下文靠语义让模型判断。所以规则之间如果互相矛盾模型会摇摆。我的做法是通用层只写“不会和任何项目冲突”的底线具体风格全部下沉到 Project Rules避免打架。团队协作里规则文件的组织方式直接决定它会不会腐烂。我的建议是按“目录 职责”拆.mdc文件而不是写一个巨大的.cursorrules。比如00-base.mdc放通用底线10-typescript.mdc放语言规则20-nextjs.mdc放框架规则30-api.mdc用 globs 限定只对 API 目录生效。这样谁改哪块一目了然评审时也能单独讨论。3. 可复制配置.cursorrules 与 Project Rules 片段这一节直接给能抄的配置。先说过渡期的.cursorrules再说现在推荐的.cursor/rules/*.mdc。如果你项目还在用根目录单文件.cursorrules可以这样写注意它是纯文本不需要 frontmatter# 通用底线 - 始终用中文回答解释改动原因时先给结论。 - 不要主动重构未被要求的文件改动范围最小化。 - 新增依赖前必须先说明理由不要静默引入。 # TypeScript / React 约定 - 使用 2 空格缩进字符串统一双引号语句结尾带分号。 - 组件一律函数式 hooks禁止 class 组件。 - 状态管理统一用 Zustand禁止引入 Redux。 - 所有网络请求走 src/lib/request.ts 封装禁止组件内直接 fetch。 - 类型定义优先 interface联合类型用 type。 # API 层约定 - 新增接口必须写 Zod schema 做入参校验。 - 接口返回统一 { code, data, message } 结构。 - 错误处理用 try/catch 统一 logger禁止 console.log。但更推荐的是 Project Rules 目录方式。先建目录mkdir -p .cursor/rules然后写00-base.mdc这是通用底线alwaysApply: true表示始终注入--- description: 项目通用底线规则 alwaysApply: true --- - 始终用中文回答解释改动先给结论。 - 改动范围最小化不主动重构无关文件。 - 新增依赖前说明理由。再写10-typescript.mdc用 globs 限定只对 TS 文件生效--- description: TypeScript 与 React 编码约定 globs: [src/**/*.ts, src/**/*.tsx] alwaysApply: false --- - 2 空格缩进双引号语句结尾分号。 - 组件用函数式 hooks禁止 class 组件。 - 状态管理统一 Zustand禁止 Redux。 - 网络请求走 src/lib/request.ts禁止组件内直接 fetch。 - 类型优先 interface联合类型用 type。最后写30-api.mdc只对 API 目录生效把接口规范钉死--- description: API 层接口规范 globs: [src/api/**/*.ts] alwaysApply: false --- - 新增接口必须写 Zod schema 做入参校验。 - 返回统一 { code, data, message } 结构。 - 错误用 try/catch 统一 logger禁止 console.log。 - 每个导出函数必须有 JSDoc说明参数与返回。这里有个关键点globs写对了规则才会在对应文件被打开时注入。alwaysApply: true的规则会一直占用上下文所以只放真正全局的底线别把框架细节塞进去否则上下文被稀释模型反而抓不住重点。如果你用的是 Cursor 的图形界面User Rules 在 Settings 里配置直接粘贴通用偏好即可比如“始终用中文回答”“不要主动重构”。它和 Project Rules 是叠加关系不是替代关系。4. 验证规则是否生效具体操作步骤与成功结果配完不验证等于没配。下面是我实测下来比较靠谱的验证流程。第一步确认规则文件被识别。在 Cursor 里打开 Chat输入看看能不能引用到规则文件或者打开 Settings 的 Rules 面板Project Rules 应该列出你.cursor/rules/下的所有.mdc。如果没列出来多半是目录层级不对——.cursor/rules/必须在项目根目录不能嵌套在src里。第二步做一次“对抗性测试”。故意让 AI 生成一段违反规则的代码看它会不会被拉回来。比如在src/api/user.ts里输入帮我写一个获取用户列表的接口函数如果30-api.mdc生效它应该输出带 Zod 校验、返回{ code, data, message }、带 JSDoc 的代码。如果它直接给你一个裸fetch加console.log说明规则没注入。第三步验证 globs 的边界。在src/components/UserList.tsx里输入同样的请求这次30-api.mdc不该生效因为 globs 只匹配src/api/**但10-typescript.mdc应该生效输出应该是函数式组件、Zustand、走封装请求。如果 API 规则也跑进来了说明你的 globs 写宽了。第四步看 Cursor 的规则命中提示。新版 Cursor 在 Chat 回复上方会显示本次引用了哪些 Rules点开能看到具体文件。这是最直接的证据。如果列表里没有你期望的规则回去检查alwaysApply和globs。成功的结果长这样你在 API 目录里让 AI 加接口它自动带上 Zod schema 和统一返回结构你在组件目录里让它加交互它自动用 Zustand 而不是useState堆状态你让它解释代码它用中文先给结论。这时候规则才算真正落地。5. 常见报错排查401、local proxy failed 与规则不生效规则配好了但请求层面也可能出问题。下面是我踩过的几类。第一类401 Unauthorized。这通常和 Rules 无关而是模型请求的鉴权失败。如果你是通过 API 方式接入模型检查 Key 是否过期、Base URL 是否写对。用 TaoToken 这类统一入口时Base URL 填https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。401 出现时先确认 Key 有没有多余空格再确认请求头是不是Authorization: Bearer key。第二类local proxy failed或连接超时。这类报错多半是本地网络到接口端点的链路问题不是 Rules 语法问题。先确认 Base URL 可达再确认没有把端点写成带路径的完整 URL有些客户端要求 Base URL 不带/v1由客户端自己拼。如果你在 Cursor 里配的是自定义模型端点检查 Settings 里的 Override OpenAI Base URL 是否和文档一致。第三类规则“看起来配了但不生效”。这是最高频的。排查顺序先看.cursor/rules/是否在项目根目录再看.mdc的 frontmatter 有没有写错globs是数组还是字符串必须是数组再看alwaysApply是不是全设成了false导致没有任何规则常驻最后看规则之间有没有互相矛盾比如 User Rules 说“用单引号”Project Rules 说“用双引号”模型就会随机选。第四类reading choices之类的解析报错。这通常是接口返回结构和你客户端预期不一致比如你用了 OpenAI 兼容格式但端点返回了别的结构。确认 Base URL 和模型 ID 匹配模型 ID 要填端点实际支持的名称别自己编。如果你在 Cursor 里接的是 Claude Code 或 Codex 这类编码 Agent配置要写全三件套Base URL、Key、Model ID。缺一个都会导致请求失败或规则不加载。Base URL 用https://taotoken.net/apiKey 用控制台生成的Model ID 按文档里列出的填。三件套对齐后再回头看 Rules 是否生效才有意义。6. 把 Rules 接进你的日常编码流规则配完不是终点怎么让它持续有用才是。我的做法是把 Rules 当成代码评审的前置层每次评审发现 AI 反复犯的错就补一条到对应的.mdc里而不是只在评审里说一次。这样规则库会跟着项目一起长。团队协作上.cursor/rules/一定要进 Git并且在 PR 里像评审代码一样评审规则改动。谁加的规则、为什么加、影响哪些目录都写清楚。避免有人往00-base.mdc里塞框架细节那会污染所有项目文件。另外规则不是越多越好。上下文是有预算的alwaysApply: true的规则每条都在消耗预算。我的经验是常驻规则控制在 5 条以内其余全部用globs按需注入。这样模型在具体文件里能拿到最相关的约束而不是被一堆无关规则干扰。如果你还没开始配建议从00-base.mdc加一条“改动范围最小化”开始先感受规则生效带来的差异再逐步下沉语言和框架规则。需要生成 Key 或查看接入文档时可以从 API Keys 页面和接入文档入手想先验证模型对话效果用模型对话页面试几轮如果是长期编码或 Agent 场景直接上 Coding Plan 更省心。规则调顺之后你会发现 Cursor 的输出终于开始像“你写的代码”了。