wbstorm

如何写 Cursor Rules：项目规则文件写什么、Agent 怎么用

在 .cursor/rules 写 .mdc：选挂载方式、写可执行正文，Agent 会在匹配时把规则放进上下文开头。

Cursor Agent 不会在两次对话之间记住你的口头约束。同一句「别改路由」贴第三次时，就该写进项目规则，让下一场对话开场就带着它。

官方文档把这套机制叫 Cursor Rules。项目规则放在 .cursor/rules，文件必须是 .mdc。同目录里的普通 .md 会被忽略。这是编辑器教程，不是头脑风暴产品说明书。

建 .mdc写 frontmatterAgent 注入

项目规则是什么

对照 cursor.com/docs/context/rules。四类来源里，入门只需要仓库里的项目文件。规则生效时，正文出现在模型上下文开头。

.mdc
项目规则扩展名
4 种
挂载方式
开头
注入位置
来源放哪里何时进上下文
Project Rules.cursor/rules/*.mdc按 frontmatter
User RulesCustomize → RulesAgent（Chat），全局
Team Rules控制台（Team / Enterprise）全仓库；可强制
AGENTS.md根目录或子目录纯 Markdown，无 frontmatter

四步写出第一条规则

  1. 1

    建文件

    在仓库建 .cursor/rules/your-name.mdc。也可在 Agent 里输入 /create-rule，或打开侧栏 Customize → Rules → Add Rule。子文件夹可以，扩展名必须是 .mdc。

  2. 2

    选挂载方式

    alwaysApply: true 每场都带。globs 在匹配文件进入上下文时带。只写 description 时由 Agent 判断。三者都空则只在聊天里 @规则名 时带上。

  3. 3

    写可执行正文

    写成内部文档：禁止项、命名、目录边界。用 @filename.ts 指向范例，不要把整份文件贴进规则。官方建议单条不超过 500 行。

  4. 4

    提交并核对

    把规则推进 git，团队才共享同一套约束。在 Customize 里看状态。Agent 仍漏读时，在对话里 @ 这条规则。

正文里该写什么

01

linter 管不到的约定

例如「生成文件不准改」「新服务必须带结构化错误」。常见风格交给 ESLint / rustfmt，不要把整本风格指南塞进规则。

02

架构边界

哪一层能碰数据库、哪条目录禁止跨引。Agent 已经会用 git 和 npm，不必罗列日常命令。

03

指向仓库里的范例

用 @ 引用已有模板。代码一变，规则不会过期。发现 Agent 反复犯同一错，再补一条，而不是开场就堆二十份。

---
description: TypeScript conventions for this repo
globs: **/*.{ts,tsx}
alwaysApply: false
---

# TypeScript
- Prefer named exports
- Do not edit files under dist/
- New API clients follow @src/api/client.ts

Agent 怎么用这条规则

匹配成功后，规则正文出现在上下文开头，用来生成代码、解释改动、走工作流。冲突时官方顺序是 Team Rules → Project Rules → User Rules，先出现的优先。Rules 不影响 Cursor Tab。User Rules 不作用于 Inline Edit（Cmd/Ctrl+K）。

和 AGENTS.md 怎么选

只想放一段人人能读的说明，用仓库根或子目录的 AGENTS.md。嵌套文件在处理该目录及其子目录时自动合并，更具体的优先。需要按 glob 或手动 @ 的精细控制，继续用 .mdc。

规则写完、要摊开草图时，回 wbstorm 用房间号即可，另见 创建或加入房间 和 白板基础。

为什么规则没有生效？

先对挂载类型。Apply Intelligently 必须有 description。按文件必须让 glob 命中当前上下文里的路径。普通 .md 放在 .cursor/rules 会被忽略。

规则会影响 Tab 补全吗？

官方 FAQ 写：Rules 不影响 Cursor Tab 或其他非 Agent 功能。User Rules 也不作用于 Inline Edit。

可以引用其他文件吗？

可以。在规则正文里写 @filename.ts。也可以在聊天里 @ 规则名做手动挂载。

这是 wbstorm 的功能说明吗？

不是。本文只讲 Cursor 编辑器的项目规则。wbstorm 是浏览器头脑风暴房间，和规则文件无关。

创建房间