Cursor Rules 是提供给 Agent 的可重复使用指令，适合记录构建命令、架构边界、代码规范和评审检查，不必在每个提示词中重新说明。有效的规则应该简短、范围明确、能够验证；团队共同使用的规则还应随代码进入版本管理。
选择合适的 Cursor 指令类型
Cursor 当前文档描述了几种常用范围：
| 指令 | 存放位置 | 适合用途 |
|---|---|---|
| 项目规则 | .cursor/rules/*.mdc | 可提交、可限定仓库文件范围的指令 |
| 用户规则 | Cursor 用户自定义设置 | 跨项目生效的个人偏好 |
| 团队规则 | 团队管理控制台 | 当前套餐支持的组织统一标准 |
AGENTS.md | 项目根目录或相关子目录 | 不需要规则前置信息的纯 Markdown 指令 |
需要按文件匹配或智能附加时使用项目规则；只需要清楚、可阅读的目录级说明时，可以使用 AGENTS.md。个人语气偏好应留在用户规则，不要提交到每个仓库。
创建一条最小项目规则
项目规则使用 .cursor/rules 下的 .mdc 文件。该目录中的普通 .md 不是结构化项目规则。创建 .cursor/rules/typescript-checks.mdc：
---
description: TypeScript validation workflow for source changes
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---
- Preserve strict TypeScript settings.
- Follow existing module and naming patterns.
- Run the narrowest relevant test before the full type check.
- Do not weaken a type or skip a test to make validation pass.description 应说明规则何时有用，globs 将范围限制在相关文件，alwaysApply: false 则避免在处理无关文档时也消耗上下文。
也可以在 Agent 中使用 /create-rule，或从 Customize → Rules 添加规则。生成后必须先检查文件内容，再提交到仓库。
理解规则应用方式
当前界面可能使用更易读的名称展示应用模式。规则在概念上可以：
- 在每个相关会话中加入；
- 涉及匹配文件时自动附加；
- 根据清楚的描述由 Agent 判断是否使用；
- 只有手动提及时才使用。
应尽量少用永久附加规则。每条指令都会占用上下文，也可能与具体任务冲突。包含多类项目的大仓库更适合文件范围或智能附加规则。
使用 AGENTS.md 保存可读的仓库指令
简单项目可以创建 AGENTS.md：
# Project instructions
## Workflow
- Read docs/DEVELOPMENT.md before editing.
- Use pnpm for package commands.
- Run pnpm validate before proposing a merge.
## Boundaries
- Keep public routes backward compatible.
- Never commit .env files or credentials.Cursor 当前规则文档支持项目根目录和子目录中的 AGENTS.md。更具体的子目录指令用于该目录下的工作。每个文件只保留与当前范围相关的内容，不要在每一级重复同一规则。
编写可以验证的规则
较弱的规则：
编写优秀、整洁的代码，并遵循最佳实践。更有效的规则：
修改 src/api/**/*.ts 时，使用项目现有 schema 工具校验外部输入。
返回 src/api/errors.ts 规定的错误结构。
先运行 pnpm test api，再执行完整验证命令。后者定义了范围、现有参考和检查方式，可以约束行为，同时不会凭空引入新架构。
测试 Cursor Rule 是否生效
- 在目标仓库新建一个 Agent 对话。
- 引用应该匹配规则的文件。
- 修改前要求 Agent 总结当前相关指令。
- 提出一个小改动，检查是否采用预期模式和命令。
- 换成不匹配的文件，确认规则没有泄漏到无关任务。
不要用高风险迁移或生产凭证流程测试规则。规则只是在影响模型行为，不是访问控制或合规边界。
Cursor Rules 常见问题
项目规则没有生效
检查 .mdc 扩展名、前置信息、描述、应用模式和 glob。*.ts 不会递归匹配所有 TypeScript 文件；真正需要递归时应使用相应模式。
多条指令冲突
Cursor 当前文档描述的优先关系是团队规则、项目规则、用户规则。删除重复内容，把权威指令放在正确范围。具体任务提示词不应暗中绕过组织政策。
Agent 使用了过期命令
同时更新规则和项目文档。规则应指向权威文件，不要在多个位置复制一大段命令清单。
加规则后回答质量反而下降
把宽泛规则拆成单一主题文件，缩短永久附加内容，删除与正确性无关的风格偏好，再用新对话测试。
Rules 与 MCP 解决不同问题
Rules 提供持续指令，MCP 则连接外部工具和数据。规则可以说明何时使用工具，但不会安装或保护工具。继续阅读 Cursor MCP 配置教程，用明确配置和审批边界添加能力。