1. 为什么 Cursor v0.45 之后规则要拆成 .mdc 文件如果你最近升级了 Cursor打开老项目发现根目录那个.cursorrules文件好像不太灵了别慌这不是你的错觉。从 v0.45 版本开始官方把单文件规则模式标记为弃用转而推荐在.cursor/rules目录下用.mdc扩展名的文件来管理规则。这个变化看起来只是换了个文件位置实际上解决了一个很现实的痛点上下文窗口被无效信息塞满。我拿一个真实项目举例。之前我把 TypeScript 类型规范、数据库查询约定、React 组件命名风格、Tailwind 类名排序规则全写在一个.cursorrules里大概四百多行。每次在 Agent 模式下让它改一个按钮样式它会把整个规则文件读进去里面关于 Prisma schema 的约束、API 错误码的约定全都被塞进上下文。结果就是真正跟当前任务相关的规则可能只有二十行剩下三百多行纯属陪跑Token 消耗直接翻倍响应还变慢。.mdc文件的设计思路就是按需加载。每个文件有三个关键部分Description 用自然语言描述这条规则管什么Globs 用文件模式匹配比如**/*.tsxContent 写具体的 Markdown 规则正文。Agent 模式会根据你当前操作的文件路径和对话里提到的关键词自动挑选匹配的.mdc文件注入上下文。你改.tsx文件时ui.mdc被激活你动schema.prisma时db.mdc才进场。typescript 的通用规范单独放一个ts.mdc靠 Globs 匹配**/*.ts和**/*.tsx。但这里有个容易被忽略的前提真正在消耗 Token 的是 Cursor 的 Agent 模式。你规则拆得再细如果 Agent 请求走的通道不稳定或者计费不透明该花的钱一分没少还多了一层排查成本。所以我在配置.mdc之前会先把模型通道换成 TaoToken这样每次 Agent 调用都能在后台看到具体的请求记录和 Token 消耗规则有没有生效、有没有被重复加载一目了然。2. 先把 TaoToken 通道接进 Cursor 的 Models 设置Cursor 本身支持自定义模型接入你可以在设置里把 Base URL 指向兼容 OpenAI 接口规范的服务。TaoToken 的 API 地址是https://taotoken.net/api注意这里不要加/v1后缀也不要带任何查询参数直接填这个根地址就行。Key 需要你先去官网创建一个。打开https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册账号进入控制台后找到 API Keys 页面点创建新 Key。建议给这个 Key 起个能识别的名字比如cursor-agent-mdc方便后面在 TaoToken 后台看调用记录时对应上。创建完复制那串 Key它只显示一次丢了就得重新生成。回到 Cursor按Cmd Shift PWindows 是Ctrl Shift P打开命令面板输入Models找到Cursor: Open Models Settings或者直接点右上角齿轮图标进 Settings左侧选 Models。在模型列表下方有个Add model或者Custom model的入口点进去填两个东西Base URL 填https://taotoken.net/apiAPI Key 填你刚复制的那串。模型名称根据你在 TaoToken 侧开通的模型来填比如claude-sonnet-4-20250514或者gpt-4o具体以控制台模型列表为准。填完之后点 Verify 或者 SaveCursor 会发一个测试请求。如果提示连接成功说明通道通了。这时候你可以在 TaoToken 的 console 里看到一条测试调用记录状态码 200 就稳了。如果报 401检查 Key 有没有多余空格如果报 404大概率是 Base URL 多写了/v1。注意Cursor 的 Models 设置里填的 Base URL 不要带 UTM 参数只填https://taotoken.net/api这个纯地址。UTM 是给官网链接用的API 端点不需要。通道配好之后你可以在 Cursor 里选这个自定义模型作为 Agent 模式的默认模型。这样后面所有.mdc规则的加载和 Agent 的自动应用走的都是 TaoToken 这条线消耗多少 Token 在后台有据可查。3. 手动创建 .cursor/rules 目录并编写第一个 .mdc 文件通道就绪后回到项目根目录。如果你之前有.cursorrules文件先别急着删可以留着做参考但 Agent 已经不会优先读它了。手动创建目录结构.cursor/rules/。注意.cursor是隐藏文件夹在 Finder 里按Cmd Shift .显示隐藏文件在 VS Code 里直接新建就行。在rules目录下新建一个文件比如local-search.mdc。用编辑器打开你会看到 Cursor 为.mdc文件提供的专用视图顶部有三个字段Description、Globs、Content。如果没看到这个视图说明文件扩展名不对确认是.mdc而不是.md。Description 写这条规则的用途用自然语言描述Agent 会基于这个描述来判断要不要加载。比如写当用户提到本地搜索、Local Search、全文检索相关需求时应用此规则。Globs 填文件匹配模式如果这条规则只针对特定文件类型写**/*.ts或**/*.tsx如果希望 Agent 在对话中提到关键词就加载Globs 可以留空靠 Description 触发。Content 区域用 Markdown 写具体规则。我拿一个本地搜索的实现约定举例# 本地搜索实现规范 ## 技术选型 - 使用 FlexSearch 作为全文检索库 - 索引构建在 Web Worker 中完成避免阻塞主线程 - 搜索结果显示高亮关键词使用 mark 标签 ## 代码结构 - 搜索逻辑统一放在 src/lib/search/ 目录 - 索引初始化函数命名为 initSearchIndex - 查询函数命名为 queryIndex接收 (keyword: string, limit?: number) ## 性能要求 - 索引构建时间不超过 200ms - 单次查询响应时间低于 50ms - 支持防抖输入间隔 300ms 后才触发查询写完之后保存。你可以用同样的方式继续拆出db.mdc、ui.mdc、api.mdc。每个文件只关心一个维度Description 写清楚触发条件Globs 精确匹配文件范围。这样 Agent 在改Button.tsx时只会加载ui.mdc不会把数据库连接池的配置也拖进来。另外.mdc的 Content 里可以用符号引用项目里的其他文件。比如你有一个docs/api-conventions.md可以在规则里写docs/api-conventions.mdAgent 会把那个文件的内容也纳入参考。这个能力适合把长篇幅的规范文档外置规则文件本身保持精简。4. 在 Agent 模式里验证规则是否被自动应用规则文件写好了怎么确认 Agent 真的在读它我试过最直接的办法在 Agent 对话里提一个规则文件里写好的关键词看它是否按照规则里的约定来执行。拿刚才的local-search.mdc举例。打开 Cursor 的 Agent 模式快捷键Cmd I或点侧边栏的 Agent 图标输入帮我实现一个 Local Search 功能用 FlexSearch索引放 Web Worker 里。注意这里我故意提到了Local Search这个 Description 里的关键词。如果规则生效Agent 的回复里应该会体现出initSearchIndex、queryIndex这些命名约定以及 300ms 防抖、200ms 索引构建时间这些性能要求。它生成的代码结构应该落在src/lib/search/目录下。如果 Agent 完全无视这些约定自己另起了一套命名那说明规则没被加载。这时候去 TaoToken 的 console 看这次请求的详情。一条正常的 Agent 调用会显示模型名称、输入 Token 数、输出 Token 数、耗时。如果输入 Token 数明显比你不加规则时多了一截说明.mdc的内容被成功注入上下文了。如果输入 Token 数跟裸对话差不多那规则大概率没被匹配上。排查方向有几个Description 里的关键词是否足够明确Globs 是否写错了导致文件没匹配上或者.mdc文件是否放在了正确的.cursor/rules/目录下。还有一个容易踩的坑Cursor 有时候需要重启或者重新加载窗口才会识别新建的规则文件。按Cmd Shift P执行Developer: Reload Window试试。验证通过之后再把db.mdc、ui.mdc这些逐条补齐。每加一条就用类似的方式在 Agent 里触发一次确认加载正常。不要一次性把所有规则全写完再测出了问题不好定位是哪个文件的 Description 或 Globs 写岔了。5. 本篇常见错排查Base URL 填错导致 404最常见的是在https://taotoken.net/api后面多加了/v1或者/v1/chat/completions。Cursor 的自定义模型设置里只需要填根地址它会自己拼接路径。如果你填了完整路径请求就打到不存在的端点上了。另外确认没有在 URL 里带 UTM 参数API 端点不认这些。Key 权限不足或余额为零TaoToken 控制台创建的 Key 如果没绑定正确的模型权限或者账户余额不足Cursor 侧会报 403 或 429。去 console 的 API Keys 页面检查 Key 的状态确认它关联的模型列表里有你在 Cursor 里填的那个模型名称。余额不足的话充值后等一两分钟再试。规则文件不生效先确认文件扩展名是.mdc不是.md再确认目录是.cursor/rules/不是.cursorrule/或.cursor/rules少了个点。Description 写得太模糊也会导致 Agent 匹配不上比如只写「一些规则」这种Agent 没法判断什么时候该加载。Globs 如果写了*.tsx只能匹配根目录下的 tsx 文件要匹配子目录得用**/*.tsx。Agent 回复里规则时有时无这种情况通常是 Globs 和 Description 同时设置了但当前操作的文件路径不满足 Globs 条件而对话里又没提到 Description 的关键词。Agent 的规则加载是「或」的关系两个条件满足一个就会加载。如果两个都不满足规则就不进场。检查你当前编辑的文件路径是否在 Globs 覆盖范围内。Token 消耗异常高如果发现某次 Agent 调用消耗的 Token 远超预期去 TaoToken 后台看请求详情。可能是某个.mdc文件的 Content 写得太长或者 Globs 用了**/*导致所有文件操作都触发加载。把规则拆得更细Globs 写得更精确能有效控制上下文体积。6. 通道与规则都稳了之后.mdc规则体系配合 TaoToken 的调用记录你能清楚看到每条规则在实际 Agent 任务中贡献了多少 Token。哪些规则经常被加载但内容很少被用到可以考虑合并或精简哪些规则从来没被触发过检查 Description 和 Globs 是不是写偏了。如果你主要用 Agent 做长期编码任务比如持续迭代一个功能模块可以看看 Coding Plan 的计费方式是否更适合你的使用节奏https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。日常想快速验证某个模型对规则的理解能力用模型对话页面直接测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。Key 的管理和新建在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入过程中遇到报错先翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite大部分 Base URL 和鉴权问题里面都有说明。规则拆分的粒度没有标准答案我的习惯是一个.mdc只解决一类问题Description 里把触发场景写成人话Globs 尽量精确到文件后缀或子目录。每加一条规则就在 Agent 里跑一次验证确认加载正常再继续。这样积累下来的规则库才是真正能帮你省 Token 而不是烧 Token 的。
1. 为什么 Cursor v0.45 之后规则要拆成 .mdc 文件如果你最近升级了 Cursor打开老项目发现根目录那个.cursorrules文件好像不太灵了别慌这不是你的错觉。从 v0.45 版本开始官方把单文件规则模式标记为弃用转而推荐在.cursor/rules目录下用.mdc扩展名的文件来管理规则。这个变化看起来只是换了个文件位置实际上解决了一个很现实的痛点上下文窗口被无效信息塞满。我拿一个真实项目举例。之前我把 TypeScript 类型规范、数据库查询约定、React 组件命名风格、Tailwind 类名排序规则全写在一个.cursorrules里大概四百多行。每次在 Agent 模式下让它改一个按钮样式它会把整个规则文件读进去里面关于 Prisma schema 的约束、API 错误码的约定全都被塞进上下文。结果就是真正跟当前任务相关的规则可能只有二十行剩下三百多行纯属陪跑Token 消耗直接翻倍响应还变慢。.mdc文件的设计思路就是按需加载。每个文件有三个关键部分Description 用自然语言描述这条规则管什么Globs 用文件模式匹配比如**/*.tsxContent 写具体的 Markdown 规则正文。Agent 模式会根据你当前操作的文件路径和对话里提到的关键词自动挑选匹配的.mdc文件注入上下文。你改.tsx文件时ui.mdc被激活你动schema.prisma时db.mdc才进场。typescript 的通用规范单独放一个ts.mdc靠 Globs 匹配**/*.ts和**/*.tsx。但这里有个容易被忽略的前提真正在消耗 Token 的是 Cursor 的 Agent 模式。你规则拆得再细如果 Agent 请求走的通道不稳定或者计费不透明该花的钱一分没少还多了一层排查成本。所以我在配置.mdc之前会先把模型通道换成 TaoToken这样每次 Agent 调用都能在后台看到具体的请求记录和 Token 消耗规则有没有生效、有没有被重复加载一目了然。2. 先把 TaoToken 通道接进 Cursor 的 Models 设置Cursor 本身支持自定义模型接入你可以在设置里把 Base URL 指向兼容 OpenAI 接口规范的服务。TaoToken 的 API 地址是https://taotoken.net/api注意这里不要加/v1后缀也不要带任何查询参数直接填这个根地址就行。Key 需要你先去官网创建一个。打开https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册账号进入控制台后找到 API Keys 页面点创建新 Key。建议给这个 Key 起个能识别的名字比如cursor-agent-mdc方便后面在 TaoToken 后台看调用记录时对应上。创建完复制那串 Key它只显示一次丢了就得重新生成。回到 Cursor按Cmd Shift PWindows 是Ctrl Shift P打开命令面板输入Models找到Cursor: Open Models Settings或者直接点右上角齿轮图标进 Settings左侧选 Models。在模型列表下方有个Add model或者Custom model的入口点进去填两个东西Base URL 填https://taotoken.net/apiAPI Key 填你刚复制的那串。模型名称根据你在 TaoToken 侧开通的模型来填比如claude-sonnet-4-20250514或者gpt-4o具体以控制台模型列表为准。填完之后点 Verify 或者 SaveCursor 会发一个测试请求。如果提示连接成功说明通道通了。这时候你可以在 TaoToken 的 console 里看到一条测试调用记录状态码 200 就稳了。如果报 401检查 Key 有没有多余空格如果报 404大概率是 Base URL 多写了/v1。注意Cursor 的 Models 设置里填的 Base URL 不要带 UTM 参数只填https://taotoken.net/api这个纯地址。UTM 是给官网链接用的API 端点不需要。通道配好之后你可以在 Cursor 里选这个自定义模型作为 Agent 模式的默认模型。这样后面所有.mdc规则的加载和 Agent 的自动应用走的都是 TaoToken 这条线消耗多少 Token 在后台有据可查。3. 手动创建 .cursor/rules 目录并编写第一个 .mdc 文件通道就绪后回到项目根目录。如果你之前有.cursorrules文件先别急着删可以留着做参考但 Agent 已经不会优先读它了。手动创建目录结构.cursor/rules/。注意.cursor是隐藏文件夹在 Finder 里按Cmd Shift .显示隐藏文件在 VS Code 里直接新建就行。在rules目录下新建一个文件比如local-search.mdc。用编辑器打开你会看到 Cursor 为.mdc文件提供的专用视图顶部有三个字段Description、Globs、Content。如果没看到这个视图说明文件扩展名不对确认是.mdc而不是.md。Description 写这条规则的用途用自然语言描述Agent 会基于这个描述来判断要不要加载。比如写当用户提到本地搜索、Local Search、全文检索相关需求时应用此规则。Globs 填文件匹配模式如果这条规则只针对特定文件类型写**/*.ts或**/*.tsx如果希望 Agent 在对话中提到关键词就加载Globs 可以留空靠 Description 触发。Content 区域用 Markdown 写具体规则。我拿一个本地搜索的实现约定举例# 本地搜索实现规范 ## 技术选型 - 使用 FlexSearch 作为全文检索库 - 索引构建在 Web Worker 中完成避免阻塞主线程 - 搜索结果显示高亮关键词使用 mark 标签 ## 代码结构 - 搜索逻辑统一放在 src/lib/search/ 目录 - 索引初始化函数命名为 initSearchIndex - 查询函数命名为 queryIndex接收 (keyword: string, limit?: number) ## 性能要求 - 索引构建时间不超过 200ms - 单次查询响应时间低于 50ms - 支持防抖输入间隔 300ms 后才触发查询写完之后保存。你可以用同样的方式继续拆出db.mdc、ui.mdc、api.mdc。每个文件只关心一个维度Description 写清楚触发条件Globs 精确匹配文件范围。这样 Agent 在改Button.tsx时只会加载ui.mdc不会把数据库连接池的配置也拖进来。另外.mdc的 Content 里可以用符号引用项目里的其他文件。比如你有一个docs/api-conventions.md可以在规则里写docs/api-conventions.mdAgent 会把那个文件的内容也纳入参考。这个能力适合把长篇幅的规范文档外置规则文件本身保持精简。4. 在 Agent 模式里验证规则是否被自动应用规则文件写好了怎么确认 Agent 真的在读它我试过最直接的办法在 Agent 对话里提一个规则文件里写好的关键词看它是否按照规则里的约定来执行。拿刚才的local-search.mdc举例。打开 Cursor 的 Agent 模式快捷键Cmd I或点侧边栏的 Agent 图标输入帮我实现一个 Local Search 功能用 FlexSearch索引放 Web Worker 里。注意这里我故意提到了Local Search这个 Description 里的关键词。如果规则生效Agent 的回复里应该会体现出initSearchIndex、queryIndex这些命名约定以及 300ms 防抖、200ms 索引构建时间这些性能要求。它生成的代码结构应该落在src/lib/search/目录下。如果 Agent 完全无视这些约定自己另起了一套命名那说明规则没被加载。这时候去 TaoToken 的 console 看这次请求的详情。一条正常的 Agent 调用会显示模型名称、输入 Token 数、输出 Token 数、耗时。如果输入 Token 数明显比你不加规则时多了一截说明.mdc的内容被成功注入上下文了。如果输入 Token 数跟裸对话差不多那规则大概率没被匹配上。排查方向有几个Description 里的关键词是否足够明确Globs 是否写错了导致文件没匹配上或者.mdc文件是否放在了正确的.cursor/rules/目录下。还有一个容易踩的坑Cursor 有时候需要重启或者重新加载窗口才会识别新建的规则文件。按Cmd Shift P执行Developer: Reload Window试试。验证通过之后再把db.mdc、ui.mdc这些逐条补齐。每加一条就用类似的方式在 Agent 里触发一次确认加载正常。不要一次性把所有规则全写完再测出了问题不好定位是哪个文件的 Description 或 Globs 写岔了。5. 本篇常见错排查Base URL 填错导致 404最常见的是在https://taotoken.net/api后面多加了/v1或者/v1/chat/completions。Cursor 的自定义模型设置里只需要填根地址它会自己拼接路径。如果你填了完整路径请求就打到不存在的端点上了。另外确认没有在 URL 里带 UTM 参数API 端点不认这些。Key 权限不足或余额为零TaoToken 控制台创建的 Key 如果没绑定正确的模型权限或者账户余额不足Cursor 侧会报 403 或 429。去 console 的 API Keys 页面检查 Key 的状态确认它关联的模型列表里有你在 Cursor 里填的那个模型名称。余额不足的话充值后等一两分钟再试。规则文件不生效先确认文件扩展名是.mdc不是.md再确认目录是.cursor/rules/不是.cursorrule/或.cursor/rules少了个点。Description 写得太模糊也会导致 Agent 匹配不上比如只写「一些规则」这种Agent 没法判断什么时候该加载。Globs 如果写了*.tsx只能匹配根目录下的 tsx 文件要匹配子目录得用**/*.tsx。Agent 回复里规则时有时无这种情况通常是 Globs 和 Description 同时设置了但当前操作的文件路径不满足 Globs 条件而对话里又没提到 Description 的关键词。Agent 的规则加载是「或」的关系两个条件满足一个就会加载。如果两个都不满足规则就不进场。检查你当前编辑的文件路径是否在 Globs 覆盖范围内。Token 消耗异常高如果发现某次 Agent 调用消耗的 Token 远超预期去 TaoToken 后台看请求详情。可能是某个.mdc文件的 Content 写得太长或者 Globs 用了**/*导致所有文件操作都触发加载。把规则拆得更细Globs 写得更精确能有效控制上下文体积。6. 通道与规则都稳了之后.mdc规则体系配合 TaoToken 的调用记录你能清楚看到每条规则在实际 Agent 任务中贡献了多少 Token。哪些规则经常被加载但内容很少被用到可以考虑合并或精简哪些规则从来没被触发过检查 Description 和 Globs 是不是写偏了。如果你主要用 Agent 做长期编码任务比如持续迭代一个功能模块可以看看 Coding Plan 的计费方式是否更适合你的使用节奏https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。日常想快速验证某个模型对规则的理解能力用模型对话页面直接测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。Key 的管理和新建在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入过程中遇到报错先翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite大部分 Base URL 和鉴权问题里面都有说明。规则拆分的粒度没有标准答案我的习惯是一个.mdc只解决一类问题Description 里把触发场景写成人话Globs 尽量精确到文件后缀或子目录。每加一条规则就在 Agent 里跑一次验证确认加载正常再继续。这样积累下来的规则库才是真正能帮你省 Token 而不是烧 Token 的。
