Cursor 规则：如何让 AI 与您的代码库保持一致

您在 Cursor 中打开一个新对话，粘贴那段已经粘贴过上百次的指令。您的技术栈、命名约定，以及 AI 总是弄错的文件夹结构。接着它为一个只需要函数的需求生成了一个 40 行、包含三层抽象的类。

该从这个噩梦中醒来了。Cursor 规则是项目文件，让粘贴变得不再必要。把您的约定写一次，AI 的输出就会贴合您的代码库，而不是与之对抗。

本教程将为一个使用 FastAPI 和 pytest 的 Python Web 项目构建一组 .mdc 规则文件，涵盖项目上下文、代码简洁性以及 API 错误格式。如果您刚接触 Cursor，建议先学习我们的 Software Development with Cursor 课程，然后打开一个项目并跟着操作。

什么是 Cursor 规则？

Cursor 规则是在项目中位于 .cursor/rules/ 的带有 MDC 专用 frontmatter 的 Markdown 文件。在您的提示到达模型之前，Cursor 会检查匹配到的规则，并将其内容预置到上下文窗口中。您的指令每次都会优先呈现。

每个 .mdc 文件都有三个控制激活的 frontmatter 字段： description、globs 和 alwaysApply。规则可以在每次对话中都生效，或仅在特定文件打开时生效。第三种选项“智能应用”允许代理读取描述并自行判断该规则是否相关。下一节将手把手介绍每种类型。

Cursor 支持四类规则：

项目规则替代了旧的 .cursorrules 文件——一个没有作用域和元数据的根级单文件——通过拆分为多个带有 frontmatter 的 .mdc 文件来实现。

AGENTS.md 是不需要 glob 作用域的项目的更简单替代方案。它是纯 Markdown，除了 Cursor 之外的 AI 编码工具也能识别，且更深层子目录中的文件会覆盖父级文件。

您可以在我们的 基于代理的工作流 文章以及 AI Agent Fundamentals 技能路径中，进一步了解其如何接入您的开发流程。

创建与配置 Cursor 项目规则

本教程余下部分将为一个使用 pytest 的 FastAPI 项目编写规则文件。这些模式可迁移到任意技术栈。

设置规则目录与文件

在项目根目录下创建 .cursor/rules/ 目录。您放在此处的每个 .mdc 文件都会即时成为 Cursor 可用的规则，无需重启。

第一个规则文件 project-context.mdc 让 AI 持久了解您的技术栈和文件夹布局：

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts技术支持

在 Agent 聊天中输入 /create-rule 也是另一种入口：Cursor 会通过聊天面板为您起草一个规则。

上述 alwaysApply: true frontmatter 表示该规则在每次对话中都会加载。按关注点使用短横线命名文件（project-context.mdc、simplicity.mdc、error-responses.mdc），并将每个文件保持在 500 行以内。臃肿的规则文件会吞噬您在上下文窗口中留给实际代码与提示的空间。将 .cursor/rules/ 目录提交到 Git。

配置规则元数据以实现精准匹配

上面的 project-context.mdc 使用了 alwaysApply: true，这是最简单的模式：不管您正在处理哪些文件，每次对话都会加载。对于全项目的上下文，这是正确选择。

有些规则仅适用于代码库的特定部分。将 alwaysApply: false，并添加以逗号分隔的 glob 模式来限定范围。带有 globs: app/routers/**/*.py 的规则只会在匹配文件（此处：app/routers/ 或其子文件夹下的 Python 文件）出现在上下文中时触发，避免将 API 约定带入不相关的对话。

“智能应用”完全跳过文件模式。您将 globs 留空，转而写一个详细的 description，由代理判断该规则对当前对话是否相关。描述质量很重要："Error handling rules" 太过模糊，难以被可靠匹配，而 "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" 则有清晰信号。

没有 globs、没有有意义描述且 alwaysApply: false 的规则会成为仅手动加载的规则，您需要在聊天中输入 @rule-name 才会引入。适合按需调用的参考资料。

撰写规则内容与约束

使用软性语言（“尽量保持函数简短”“优先使用异步端点”）编写的规则，会给 AI 留下忽视它们的空间。请改用命令式："Functions must be under 30 lines. All endpoints must be async."

开头提到 AI 会为只有一个实现的需求生成包含三层抽象的 40 行类。阻止这种行为的规则是 simplicity.mdc：

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead技术支持

效果立竿见影。当只有一个实现时，AI 不再倾向于抽象基类；只有两种情况时，也会使用 if 语句。

第三个规则 error-responses.mdc 使用 glob 作用域，仅在处理 API 路由文件时触发：

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response技术支持

在可能的情况下，请指向代码库中的现有文件，而不是把代码复制进规则中。类似“参见 app/routers/users.py 以获取规范的端点结构”的表述，能随着代码演进保持准确；而复制的片段在源文件被重构的那一刻就会过时。

测试并验证规则是否附加

Cursor 没有内置指示器显示某次对话中哪些规则处于激活状态。您需要通过测试行为来验证。

打开一个新的 Agent 聊天，写一个应当触发某条规则的提示。对于 error-responses.mdc，试试：“在 app/routers/users.py 中添加一个按 ID 删除用户的 DELETE 端点。”如果生成的错误处理与规则中的 JSON 结构完全不符，或跳过了带有 detail 字典的 HTTPException，那说明匹配出了问题。

使用 glob 作用域的规则需要在您的提示中引用匹配文件，或在编辑器中打开匹配文件。若在测试 error-responses.mdc 时未提及任何 app/routers/ 下的文件，该规则就不会被激活。 

“智能应用”规则则是基于主题：尝试一个与规则描述相关的提示，再尝试一个无关的提示，对比输出。代理应在第一个提示上遵循规则，在第二个上忽略。

让您的 Cursor 规则始终有效

上个月还有效的规则，在一次重构或文件夹改名后，可能会误导 AI。

排查匹配失败

规则不触发的最常见原因是文件扩展名：规则必须使用 .mdc，位于 .cursor/rules/ 的纯 .md 文件会被静默忽略。

除此之外：

• 过于宽泛的 globs（如 **/*.py）会让规则附加到项目中的每个 Python 文件。请收窄至 app/routers/**/*.py 或 tests/**/*.py，只在该触发的地方触发。

• 当描述过于通用时，您会发现“智能应用”规则漏掉一些对话。上文元数据部分的优劣描述示例在此同样适用。

• 冲突规则更难发现。当两条规则对同一批文件给出相互矛盾的指令时，AI 会选其一（通常是后加载的那条）。通过收窄 glob 作用域以避免重叠，或将相关指引整合到单个文件中来修复。

有个值得注意的小问题：对 .mdc 文件的更改有时会在未保存的情况下消失。如果编辑无法生效，请完全关闭 Cursor，在未保存更改的弹窗中选择“Override”，再重新打开。

在对话中途让规则“记牢”

规则可能在对话一开始正确触发，但在五条消息后被忽略。原因是上下文窗口的新近性偏置：随着对话增长，模型会优先考虑最近的消息，而忽略顶部注入的指令。这是 Cursor 社区最常见的抱怨，没有哪项设置能直接解决。

权宜之计是“强化”。当输出开始偏离您的规则时，在下一个提示中加一句“请遵循项目的错误响应规则”之类的话。这会把指令重新放入模型的近期上下文。 

对每次响应都很重要的规则（格式、命名），用更短更直接的表述在长对话中比长段落更能经得住考验。

包含代码示例的规则，也比纯文本指令更不容易“跑偏”。与其写“使用提前返回处理错误”，不如给出一个简短的前后对比代码块来展示您想要的模式。随着上下文累积，模型对真实代码的锚定要比对散文描述更可靠。

维护与修剪规则

在任何重大重构、依赖升级或文件夹重组后，审查一次规则。引用了已弃用 API 或已删除文件的规则会向 AI 提供错误指令。过时的 globs 更加悄无声息：将 app/api/ 重命名为 app/routers/ 后，限定在旧路径的规则会毫无提示地停止触发。

“修剪”也可以反向进行。随着模型进步，它们无需明说也能掌握常见约定。如果 AI 已经在未提示的情况下遵循某条规则，请删除该规则以回收 token。健康的规则集合会随着时间推移而精简，而不是只增不减。

在团队环境中扩展规则

像对待应用代码那样对待规则。通过 Pull Request 进行更改，并在进入 .cursor/rules/ 前达成团队共识。

对于使用 Business 或 Enterprise 方案的组织，团队规则允许管理员在 Cursor 仪表板上为所有成员强制执行规则。“立即启用”使规则默认生效，同时允许用户将其关闭。“强制执行此规则”则移除选择权，适用于如安全实践与合规要求等不容商量的约定。

结语

从一两条您最常纠正的模式开始。如果您每次会话都在改同一种 AI 输出（错误格式不对、不必要的抽象），那就说明这是一条待写的规则。随着您发现重复性错误再逐步补充，并删掉那些不再起作用的规则。

本教程中的 .mdc 文件适用于 FastAPI 项目。对于 Next.js 前端或 Rust CLI 工具，您的文件会有所不同——这正是关键所在：它们编码的是您团队的约定，而非通用最佳实践。 

如果您想更深入了解 Cursor，请查看我们的 Cursor 2.0 指南。若想与其他 AI 编码助手对比，推荐阅读以下对比文章：

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf