Cursor 规则配置指南：从三份 TypeScript 示例开始

这样做，是为了减少代码审查时的返工。举个时间核算的例子：四名开发者，每人每周做三次、每次五分钟的纠正，就有 60 分钟花在重复落实约定上。这不代表配置规则后就一定能省下这些时间。应该记录哪些纠正不再需要，再扣除维护规则的时间。订阅费用是另一回事，详见 Cursor 价格说明。

Cursor 规则放在哪里？

团队共用的编码约定，应当和代码放在一起。个人对回复方式的偏好，则留在个人设置里。

子目录中的 AGENTS.md 会与上级目录的说明共同生效，作用于所在目录及其下级目录；更具体的说明优先。对于 Team、Project 和 User Rules，文档给出的冲突优先级是 Team → Project → User。Cursor 规则文档

对小团队，我通常会先选项目规则。“使用现有的表单组件”属于仓库约定；“最终回复简短些”属于个人偏好。分开放，个人习惯才不会不知不觉变成团队要求。

每条规则该在什么时候加载？

规则正文上方那一小段 frontmatter 配置，决定了规则何时加载到上下文中。

“由 Agent 按需选择”，是指 Agent 根据规则的描述判断是否使用它。glob 则是用于匹配文件路径的模式。加载行为与语法

可以把规则加载理解为把任务单送到对应的工作台。指令写得再好，如果执行任务时根本没有收到，也起不了作用。安全底线应始终加载，代码风格约定应随相关文件加载；至于是否适用取决于任务内容的指导，再交给 Agent 按需选择。

TypeScript Web 应用可直接使用的三条规则

在仓库中创建以下文件。它们是供团队参考的内部约定，frontmatter 字段和匹配模式语法采用 Cursor 文档中的写法。正文中的指令只是便于调整的起点，并非 Cursor 规定的编码标准。

代码风格：随 TypeScript 文件加载

保存为 .cursor/rules/style.mdc：

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

- Follow the nearest existing module's naming and import conventions.
- Prefer named exports unless the framework requires a default export.
- Reuse existing UI components and utilities before adding alternatives.
- Keep formatting in the repository's formatter and linter configuration.

这个示例假设应用代码位于 src/ 下，请根据仓库的实际结构调整路径。它刻意关注格式化工具无法替你决定的事，比如应用里是否已经有合适的按钮组件或日期工具函数。如果团队采用了不同的导出约定，也应相应修改。规则应该描述仓库的实际约定，而不是悄悄替你重新设计项目。

测试：说明哪些任务需要测试

保存为 .cursor/rules/tests.mdc：

---
description: Testing requirements when adding features, fixing bugs, or changing TypeScript behavior
alwaysApply: false
---

- Cover changed behavior with a focused regression test.
- Use the existing test runner, fixtures, and file naming conventions.
- Read package.json for the relevant test script; do not invent a command.
- Report the command and actual result, or explain why tests were not run.

目标是得到有用的测试，以及如实报告的执行结果。修复 bug 后，应有证据表明原先出错的情况已被测试覆盖；重构则应保持相关行为不变。这两类工作都不需要另起一套测试框架，也不该把“测试已编写”当成“测试已通过”来汇报。

如果某项任务需要明确使用这份检查清单，就在请求中加上 @tests。如果团队要求每项任务都遵守，则把加载方式改为 Always Apply。这应当是有意识的团队决策：只有描述字段时，选择权仍在 Agent 手中。

安全：底线要求要简短明确

保存为 .cursor/rules/security.mdc：

---
alwaysApply: true
---

- Never put secrets in source code, test fixtures, or application logs.
- Use existing server-side authentication and authorization helpers.
- Validate untrusted input at server boundaries with the existing schemas.
- Do not remove permission checks to make a feature or test pass.

知道仓库中相关模块的位置后，就把“现有的辅助函数”替换为实际模块路径。安全底线应当让人在普通功能开发中也能清楚理解。“保证安全”很难让审查者据此检查；“保留授权检查”则是一项具体要求。

这个文件提供的是指令，本身不构成安全边界。仍然需要在代码中执行访问检查，并审查敏感改动。Cursor 也提醒，不要把 AI 指导当作唯一的安全控制措施。Team Rules 说明

用一次真实改动验证配置

选一个过去经常需要反复纠正的小任务。修改表单校验就很合适：既涉及组件，又改变行为，还会接收用户输入。

1. 先写下预期结果。 明确要复用哪个现有组件、测试什么行为，以及保留哪一处输入校验边界。
2. 保存这三个文件，并检查规则状态。 Cursor 的 Customize → Rules 中可以查看规则；Agent 中也可使用 /create-rule。创建规则
3. 把相关文件放入上下文，再提出修改请求。 请求要贴近真实工作。如果在任务里把每条规则都重述一遍，就无法判断规则配置是否发挥了作用。
4. 检查代码 diff 和报告的检查结果。 要看约定是否实际落实，不能只看一句“已遵守规则”。如果这次验证必须使用测试清单，就明确要求 @tests。
5. 把有效的规则与代码改动一起提交。 给团队一个可以审查的起点。先把含糊的句子改清楚，再考虑增加文件。

如果某项约定没有被遵守，要分清两种情况：规则根本没有进入任务上下文，还是已经进入上下文却没有发挥作用。前者需要修正加载方式；后者需要更清楚的指令、示例，或自动化检查。

哪些约定值得长期保留？

先处理那些反复出现、给团队带来最大成本的问题。下面这些用途，按可能减少的审查负担排序，供你取舍。

这并不意味着你必须再创建五个文件。没有发生过的问题，先不写。如果机器能精确检查某项要求，就优先使用自动化检查。好的规则，填补的是任务请求与仓库现有工具之间的空白。

旧的 .cursorrules 文件该怎么处理？

按当前文档配置项目规则，应使用 .cursor/rules/*.mdc。截至 2026 年 10 月 11 日，规则文档页面没有提到 .cursorrules，因此无法据此确认旧文件是否仍然有效。当前文档

如果仓库还保留着旧文件，我建议把其中有用的指令迁移到各自职责明确的项目规则中，可以从上面的三个文件开始。先选好触发方式，用真实任务验证，再停用旧文件。不要因为某条约定已经写在那里，就继续保留过时的做法。

与 CLAUDE.md、AGENTS.md 有什么对应关系？

它们的共同思路，都是提供一份长期有效的项目说明：Claude Code 有 CLAUDE.md，Codex 会读取 AGENTS.md 中的工作约定。Cursor 的纯 Markdown 选项也适合这种简单用途，而 .mdc 文件进一步提供了加载方式的选择。底层约定应保持一致，但每个工具如何加载，都需要单独配置；复制文字，并不等于复制了设置。如果团队同时使用多个 Agent，应指定一位共享约定的负责人，避免这些文件各说各话。

配置完成后，值得做的两个小工具

对工程负责人而言，仓库规则检查器更值得尝试：检查文件扩展名、支持的 frontmatter 字段，以及没有匹配到任何已跟踪文件的模式。最小可用版本可以只是在代码审查时运行、输出本地报告的工具。需求信号还比较有限：本文研究中，DataForSEO 返回的 “cursor rules examples”预估月搜索量为 140 次。这说明有人关注相关问题，并不能证明有人愿意付费。局限也很明确：规则的结构即使完全有效，内容仍可能缺乏指导价值。指标定义

团队约定审查材料包，则可能帮助同时维护多个仓库的负责人。把反复出现的审查意见和认可的示例整理成规则修改提案，以 diff 呈现，并为每项改动指定审查者。DataForSEO 返回的 “cursor team rules”预估月搜索量为 70 次。先作为内部工具使用即可；原生 Team Rules 已经解决了分发问题，再做一个存储规则的控制台，产品价值有限。真正有用的工作，是判断哪些内容值得成为长期指令。指标定义

配置时常见的问题

下周，挑一项反复需要纠正的问题，把对应规则写准确，再用下一个普通的拉取请求试一试。如果你还在考虑是否选择这款产品，可以阅读 Cursor 评测或 Cursor 替代工具推荐。

如果你希望把这套做法接入团队的开发流程，可以了解 AI 生产系统服务。