规范文件

Cursor 规则写在哪：.cursor/rules 与 AGENTS.md

Cursor 规则文件放哪、什么格式、四种应用方式，根目录与子目录 AGENTS.md 的范围，旧 .cursorrules 现状。按官方文档核对，未实测。

Cursor 有四类规则：项目规则、用户规则、团队规则和 AGENTS.md。本文只讲和仓库文件有关的两种：.cursor/rules 里的项目规则，以及根目录、子目录的 AGENTS.md，并说明旧的 .cursorrules 在官方当前文档里的情况。

核验日期: 2026年10月28日 · 未实测
适用于: Cursor 仅适用 Cursor[1]
涉及工具: Cursor

文件位置

路径	适用范围	读取方式
`.cursor/rules`	项目规则目录，受版本控制	Cursor：规则为 .mdc 文件；.md 文件被忽略[1]
`AGENTS.md`	项目根目录	Cursor：作为 .cursor/rules 的简单替代，纯 markdown、无元数据[1]
`frontend/AGENTS.md`	子目录（路径取自官方页面样例）	Cursor：处理该目录及其子目录的文件时自动应用，与上级合并，更具体的优先[1]

什么时候用

你在 Cursor 里想把项目约定写成文件并提交到仓库。[1]
你想知道一条规则为什么没有被应用，或者想选合适的应用方式。[1]
你想知道根目录和子目录的 AGENTS.md 在 Cursor 里各管到哪。[1]

什么时候不用

你用的不是 Cursor：其他工具的加载规则不同，本文不适用。[1]
你要找旧 .cursorrules 的迁移或兼容说明：官方当前文档未提及，待确认。[1]

规则文件的位置和格式

版本口径：Cursor 规则页没有标注文档版本，本文以 2026-10-28 核验日期读到的 cursor.com/docs/rules 页面为准，之后官方改动不在本文范围内。[1]

项目规则放在 .cursor/rules 里，是 .mdc 文件，受版本控制；文件名可以随便取。
官方写：项目规则必须使用 .mdc 扩展名；.cursor/rules 里的普通 .md 文件会被规则系统忽略，因为它没有可以写 description、globs 和 alwaysApply 的 frontmatter。想用纯 markdown，官方建议改用 AGENTS.md。
可以用文件夹整理规则，例如 .cursor/rules/frontend/components.mdc。
每条规则由 frontmatter 元数据和正文组成；frontmatter 用来控制规则怎么被应用。

[1]

示例：一个带 frontmatter 的规则文件（我们自拟，字段取自官方页面）

---
description: Frontend component conventions
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Keep components under 200 lines

[1]

四种应用方式

规则类型与 frontmatter 字段的对应（按官方原文整理）
应用方式	官方说明	frontmatter 条件
Always Apply	每个聊天会话都应用	alwaysApply 为 true；此时 globs 和 description 被忽略
Apply to Specific Files	文件匹配指定模式时应用	alwaysApply 为 false；description 一栏原表写「—」；globs 为 provided（有值）；匹配的文件在上下文中时自动附加
Apply Intelligently	Agent 根据 description 判断是否相关	alwaysApply 为 false；description 为 provided（有值）；globs 为 omitted（省略）；Agent 阅读 description，相关时才拉入
Apply Manually	在聊天里用 @ 提到时应用，例如 @my-rule	alwaysApply 为 false；description 为 omitted（省略）；globs 为 omitted（省略）；仅在聊天里 @ 提到该规则时包含（原表写 false / omitted / omitted，不是三者都不设置）

[1]

官方 FAQ：规则没生效时，先检查规则类型；Apply Intelligently 要确保写了 description，Apply to Specific Files 要确保文件模式能匹配到相关文件。
globs 用逗号分隔多个模式，例如 docs/**/*.md, docs/**/*.mdx。

[1]

四类规则和它们的顺序

Cursor 的四类规则
类型	放在哪里	官方说明
Project Rules	仓库里的 .cursor/rules	随代码版本控制，限定在你的代码库范围内
User Rules	Cursor 设置里的 Customize → Rules	对所有项目生效，由 Agent（Chat）使用
Team Rules	团队后台	Team 和 Enterprise 计划可用
AGENTS.md	项目根目录或子目录	markdown 格式的 Agent 指令，是 .cursor/rules 的简单替代

[1]

多条规则同时适用时，官方写的顺序是 Team Rules、Project Rules、User Rules；所有适用的规则会合并，指引冲突时靠前的来源优先。[1]

根目录和子目录 AGENTS.md 管到哪

根目录：AGENTS.md 放在项目根目录，是 .cursor/rules 的替代，适合简单场景；它是没有元数据的纯 markdown 文件。
子目录：官方写 Cursor 支持项目根目录和子目录里的 AGENTS.md；放在任意子目录的 AGENTS.md，会在处理该目录及其子目录的文件时自动应用。
嵌套时：子目录文件的指令与上级目录的合并，更具体的指令优先。

[1]

官方页面里的目录树样例有 AGENTS.md（全局）、frontend/AGENTS.md、frontend/components/AGENTS.md 和 backend/AGENTS.md，分别对应项目整体、前端、组件和后端。[1]

旧的 .cursorrules

官方当前文档未提及 .cursorrules，是否仍被读取、是否已弃用，待确认。以官方当前页面为准：项目规则放 .cursor/rules 的 .mdc 文件，纯 markdown 用 AGENTS.md。[1]

来源

以下均为官方页面，核验日期见各条；链接指向核验时的版本。

Cursor · Rules | Cursor Docs
2026年10月28日

发现错误？告诉我们 →