如何让 Cursor AI Agent始终遵守项目规范：使用自动规则生成技术

ivye • • 免费干货 • 4 阅读

指导如何利用自动规则生成技术，确保 AI 代理在项目中的行为一致性和代码标准的执行。今日前端早读课文章由 @turbodev 分享，@飘飘翻译。

译文从这开始～～

如何自动生成结构化的 Cursor AI 规则（.mdc 文件）。本指南将教你如何利用 AI 智能体和你已有的最佳实践文档，实现统一的代码规范执行。


使用 RepoPrompt 自动生成规则

本教程将指导你如何根据已记录的最佳实践，创建结构化的 Cursor 规则文件（.mdc）。我们将使用在 Cursor 中专门配置的 AI 智能体来正确格式化这些规则。按照这些步骤操作，可以确保你的规则保持一致，并有效引导 AI 在项目中的行为。

✅ 前置条件

已安装 Cursor AI 代码编辑器
基本了解 Cursor 的功能（如聊天、repo prompts 等）
你希望强制执行的一套最佳实践，最好以 Markdown 文件的形式写在项目中

1️⃣ 第一步：获取规则生成规则


BMad 的最佳实践 Cursor 自定义智能体和规则生成器

本流程的核心依赖于一个特定的 Cursor 规则，这个规则专门用于指导 AI 正确创建其他规则。可以把它当作一个 “元规则”：一个关于 “如何制定规则” 的规则。

这并不是一个独立的 “智能体”，而是一个标准的 Cursor 规则文件（.mdc），里面包含了详细的说明（也就是它的系统提示），用于指导新规则文件的格式和结构。

推荐做法：添加这个规则可以让 Cursor 在你请求时高效地创建和更新其他规则，始终参考这些格式标准，从而保持一致性。请按照以下步骤操作：


.cursor/rules/core-rules/rule-generating-agent.mdc

1、如果目录 .cursor/rules/core-rules/ 不存在，先创建它。

2、将下面的内容保存为 .cursor/rules/core-rules/rule-generating-agent.mdc 文件中。

3、（可选）Cursor 有一个专门用于查看规则的界面，但这个界面可能会导致智能体所做的更新丢失。为避免这种情况，可以在 Cursor 设置中添加以下配置，让这些文件像普通文件一样打开：

 "workbench.editorAssociations": {
   "*.mdc": "default"
 }

 

在本教程中，我们会将这个规则文件的内容视为直接加载进聊天中的指令。

鸣谢：这个规则定义最初来自 cursor-custom-agents-rules-generator 项目。该项目会不断更新，所以你现在看到的版本可能已经不是最新的。可访问该项目获取最新版本。感谢 BMad 的创建与分享。

cursor-custom-agents-rules-generator Github：https://github.com/bmadcode/cursor-custom-agents-rules-generator/tree/main

rule-generating-agent.mdc 文件内容：

 ---
 description: 该规则对于整个代码库中规则创建的一致性和质量控制至关重要。在以下情况下必须遵循本规则：(1) 用户请求创建新规则时；(2) 需要修改已有规则时；(3) 用户希望记录某些行为或模式时；(4) 
 请求未来行为变化时。本规则通过标准化格式、命名规范和内容要求，确保规则的组织结构清晰、文档齐全、应用有效。尤其对于维护规则层级结构、让 AI 能正确发现规则、提升规则系统效果具有重要作用。整个规则系统是项目一致性、代码质量以及自动化协助效果的基础。
 globs:
 alwaysApply: true
 ---
 # Cursor 规则格式

 ## 规则文件模板结构

 ---
 description: `详细描述该规则的应用场景，说明何时应用此规则。请包括关键情境、受影响的领域，以及遵守该规则的重要性。描述应详尽但不跑题，足以让智能体在任何场景下能准确判断是否使用该规则。`
 globs: .cursor/rules/**/*.mdc 或留空
 alwaysApply: {true 或 false}
 ---

 # 规则标题

 ## 关键规则

 - 简洁明了地列出智能体必须遵守的操作要点（使用项目符号）

 ## 示例

 <example>
   {规则正确应用的示例}
 </example>

 <example type="invalid">
   {规则错误应用的示例}
 </example>

 ---

 ### 文件夹结构（如不存在请创建）

 所有规则文件需存放在特定组织文件夹中：

 - `.cursor/rules/core-rules`：与 Cursor 智能体行为或规则生成相关的核心规则
 - `.cursor/rules/my-rules`：仅适用于个人的规则，可在共享仓库中 gitignore 忽略
 - `.cursor/rules/global-rules`：始终应用于每个聊天或 Cmd/Ctrl+K 上下文的规则
 - `.cursor/rules/testing-rules`：与测试相关的规则
 - `.cursor/rules/tool-rules`：针对特定工具（如 git、Linux 命令、MCP 工具）的规则
 - `.cursor/rules/ts-rules`：TypeScript 语言相关规则
 - `.cursor/rules/py-rules`：Python 语言相关规则
 - `.cursor/rules/ui-rules`：HTML、CSS、React 等 UI 技术相关规则
 - 如有需要，可新增类似命名的文件夹，例如：`.cursor/rules/cs-rules`（如果项目开始使用 C#）

 ---

 ## 通配符模式示例（Glob Pattern Examples）

 不同类型规则的常见 glob 匹配模式：

 - 核心规则：`.cursor/rules/*.mdc`
 - 编程语言规则：`*.cs`, `*.cpp`
 - 测试标准：`*.test.ts`, `*.test.js`
 - React 组件：`src/components/**/*.tsx`
 - 文档：`docs/**/*.md`, `*.md`
 - 配置文件：`*.config.js`
 - 构建产物：`dist/**/*`
 - 多文件类型扩展名：`*.js`, `*.ts`, `*.tsx`
 - 多重模式组合：`dist/**/*.*`, `docs/**/*.md`, `*test*.*`

 ---

 ## 关键规则

 - 所有规则文件必须以如下方式命名并存放：
   `.cursor/rules/{组织目录}/rule-name-{auto|agent|manual|always}.mdc`
 - 所有规则文件**必须**保存在 `.cursor/rules/**` 路径下，不可存放在其他位置
 - 创建规则前，务必检查 `.cursor/rules/` 下是否已有可更新的规则

 ### 文件开头的 front matter 类型说明：

 前置字段区域（front matter）必须始终写在文件开头，并包含以下三个字段，即使值为空也必须保留：

 - **Manual Rule**（手动规则）：如果用户请求的是手动规则，则 description 和 globs 留空，`alwaysApply: false`，文件名以 `-manual.mdc` 结尾
 - **Auto Rule**（自动规则）：适用于特定文件类型的规则（如所有 TypeScript 或 Markdown 文件），description 留空，`alwaysApply: false`，文件名以 `-auto.mdc` 结尾
 - **Always Rule**（全局规则）：适用于所有聊天和命令窗口，description 和 globs 留空，`alwaysApply: true`，文件名以 `-always.mdc` 结尾
 - **Agent Select Rule**（智能体选择规则）：不需要每次加载，适用于特定目的的规则。必须有详细的 description，说明何时使用，例如代码更改、架构决策、修复 bug 或创建新文件等。globs 留空，`alwaysApply: false`，文件名以 `-agent.mdc` 结尾

 ---

 ### 规则内容注意事项：

 - 内容应聚焦于清晰、可执行的操作指令，不要加入无关说明
 - 如果规则不是始终应用（`alwaysApply: false`），则 description 必须提供足够上下文，让 AI 能明确判断是否适用
 - 使用简洁的 Markdown，适合智能体的上下文窗口处理能力
 - 示例部分内容（XML 结构）需缩进 2 个空格
 - 支持使用 Emoji 和 Mermaid 图表，只要它们有助于增强 AI 对规则的理解
 - 虽然没有明确的长度限制，但内容应控制在精炼实用范围，避免冗余，注重性能影响
 - 每个规则**必须包含**一个正确示例和一个错误示例
 - 通配符（glob pattern）不可使用引号，也不可用 `{}` 进行扩展名分组
 - 若规则是为防止某类错误或行为问题而设，应在示例中体现相关背景

 ---

 ### 规则创建或更新后的返回格式：

 - `AutoRuleGen Success: path/rule-name.mdc`
 - `Rule Type: {规则类型}`
 - `Rule Description: {description 字段的原文}`

📋 第二步：记录你的最佳实践

在创建规则前，需要先准备好相关内容。请收集你希望 AI 遵循的具体标准或最佳实践，这些标准或最佳实践适用于特定领域（例如 TypeScript 编码标准、测试流程或提交消息格式）。

💡 提示：可使用 AI 进行调研和生成

你可以借助具备强大调研能力的 AI 模型（如 Perplexity、Claude 3 Opus、GPT-4 或 Grok）来帮助整理这些最佳实践。给 AI 提供你的项目背景，并让它帮你查找和整理相关标准。

示例提示词（Prompt）：

 目标：针对 {TECHNOLOGY_OR_DOMAIN}，在 {PROJECT_TYPE} 项目背景下，调研并整理出最佳实践清单。

 上下文：

 - 我们的项目使用技术栈：{LIST_KEY_TECHNOLOGIES_FRAMEWORKS}
 - 团队规模为：{TEAM_SIZE}
 - 项目重点关注：{LIST_PROJECT_PRIORITIES，例如：可维护性、性能、安全性}

 操作说明：

 1. 调研 {TECHNOLOGY_OR_DOMAIN} 的成熟最佳实践
 2. 聚焦适用于 {PROJECT_TYPE} 项目及其优先事项的内容
 3. 将结果整理为清晰、可操作的要点，适合文档使用
 4. 输出以 Markdown 格式撰写，并设置合适的标题结构


 ### 变量说明：

 - TECHNOLOGY_OR_DOMAIN = "TypeScript"（例如：Python、React、API 设计、Git 提交信息）
 - PROJECT_TYPE = "web 应用"（例如：命令行工具、移动应用、数据科学项目）
 - LIST_KEY_TECHNOLOGIES_FRAMEWORKS = "Node.js, Express, PostgreSQL"（例如：React、Next.js、Tailwind CSS）
 - TEAM_SIZE = "小团队（3-5 名开发者）"
 - LIST_PROJECT_PRIORITIES = "代码可读性、测试覆盖率、一致的错误处理机制"

 

示例文档内容（docs/your-best-practices.md）：

创建源文档：整理这些最佳实践为清晰的项目文档

请将你收集到的最佳实践整理成一个清晰易懂的文档，建议使用 Markdown 格式编写，并将其保存在项目目录中。例如，可以创建一个名为：docs/typescript-best-practices.md 的文件。

编写最佳实践内容：逐条清晰列出每条规范

 # 项目最佳实践

 ## 使用统一的命名规范

 变量、函数和类应遵循项目约定的命名风格（例如变量使用 camelCase，类名使用 PascalCase）

 ## 添加文档注释

 公共函数和复杂逻辑应有明确的文档注释，说明用途、参数和返回值

 ## 处理错误要稳妥

 应预判可能的错误，并采用适当方式处理（如 try-catch、检查返回值等），避免程序崩溃

 

✨ 第三步：使用代理生成规则

现在，你将引导 “规则格式化代理”（来自步骤 1），根据你的最佳实践文档（来自步骤 2）生成 .mdc 规则文件。


在 Cursor 中使用规则生成代理

打开 Cursor 的 Chat 或 RepoPrompt 界面，调用规则生成智能体（比如通过输入 @rule-generating-agent，前提是你已将该规则保存为 Cursor 中的提示，或在 RepoPrompt 中选择它作为元提示）。 同时，将你的最佳实践文档提供给它作为上下文（例如 @docs/typescript-best-practices.md）。


在 RepoPrompt 中使用规则生成代理

1、给智能体一个清晰的指令，详细说明它该做什么。这个提示词应该引用智能体、最佳实践文档（使用变量形式），并明确生成的规则类型、目标文件夹（也使用变量）以及格式要求。

示例提示词（可复制粘贴使用）：

💡注意：发送前请填写提示词最后的变量定义。

 目标：根据所引用文档（`@{BEST_PRACTICES_DOC_PATH}`）中的最佳实践，生成多个“Agent Select”类型的 Cursor 规则。

 操作说明：
 1. 对文档中的每条独立最佳实践，分别生成一个“Agent Select”类型的规则文件（`.mdc`）
 2. 生成规则时，严格遵守系统提示 `@rule-generating-agent` 中定义的格式和内容要求
 3. 生成完成后，请列出所有已创建规则文件的路径以确认成功

 变量定义：

 - `BEST_PRACTICES_DOC_PATH =`（← 这里填写你的最佳实践文档路径，如 `docs/typescript-best-practices.md`）

 

2、运行智能体：完成提示词后，点击发送（无论是在 Cursor Chat 还是 RepoPrompt 中），让智能体开始工作。生成完成后，检查规则文件内容，可选择提供反馈并接受更改。


查看生成的规则

你可能需要重启 Cursor 或手动打开这些规则文件，系统才会将它们正确索引并生效。

就这样！🎉你已经成功地从文档化的最佳实践中，自动生成了结构化的 Cursor 规则。

通过将 “知识整理”（步骤 2）与 “规则格式化”（步骤 3）分开处理，并使用专门的智能体来执行格式化任务，你可以确保整个 AI 辅助开发流程具备一致性和可维护性。这些规则也将自动被 Cursor 的 AI 引用，确保其行为符合你项目的标准。

关于本文
译者：@飘飘
作者：@turbodev
原文：https://www.ultrawideturbodevs.com/how-to-force-cursor-ai-agents-to-always-follow-your-project-rules-using-auto-rule-generation-techniques/

转自：https://mp.weixin.qq.com/s/ne8xO4sn6AtQJC4_63gvpw

文章版权归原作者所有或来自互联网，未经允许请勿转载。如有侵权请联系我删除，谢谢！
THE END
分享
二维码
打赏
< <上一篇
下一篇>>
文章目录
关闭
目 录