跳到主要内容
api工厂
AI 开发

Cursor Rules 实战:把团队规范写进 .cursor/rules

api工厂资讯栏目 约 5 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:Cursor 的项目规则放在仓库 .cursor/rules/ 目录下的 .mdc 文件里,用 frontmatter 控制四种加载方式(Always、按 globs 匹配、按描述智能加载、手动 @ 引用)。规则要进 Git、要短、要可验证,核心写四块:目录约定、命名规范、禁止改范围、验收命令。提示词管这一轮对话,Rules 管整个仓库——这是团队把 AI 编码从「自由发挥」拉回「按仓规改」的最便宜手段。

一、为什么提示词不够

在对话里写「别动 dist/」「用我们的命名」能管用一次,但新开聊天就忘干净,团队里每个人还得各自复制粘贴。规则文件解决的是持久化与共享:进仓即生效、Git 可审可演进、新人 clone 下来自动继承。先分清几个容易混淆的位置:

机制位置作用范围
User RulesCursor 设置面板个人全局偏好,不进仓库
Project Rules.cursor/rules/*.mdc当前仓库,团队共享
AGENTS.md仓库根或子目录纯 Markdown,跨工具可读
.cursorrules仓库根单文件遗留方案,新项目不建议

注意扩展名必须是 .mdc,同目录普通 .md 不会被规则系统加载。个人习惯(如「用中文简洁回复」)放 User Rules,项目规范一律放 Project Rules,否则换项目会互相污染。

二、四种加载方式怎么配

frontmatter 三个字段决定加载时机:

类型配置适用
Always ApplyalwaysApply: true全仓铁律
Specific FilesalwaysApply: false + globs只对某类文件生效
Apply IntelligentlyalwaysApply: false + descriptionAgent 按描述判断相关性
Apply Manually三者均省略聊天里 @规则名 才带上

一条全仓铁律示例:

markdown
---
description: 本仓基础工程约定
alwaysApply: true
---
- 新文件优先 TypeScript;禁止无说明引入新依赖
- 不要修改 dist/、build/ 与锁文件(除非任务明确要求)
- 改动前先读相关源文件,再提方案
- 一次改动只做一件事,无关格式化不混进业务 diff
- 改完必须实际运行 npm run lint 与 npm run build 并报告结果

一条按路径生效的接口层规则:

markdown
---
description: API 请求层约定
globs: src/api/**/*.ts
alwaysApply: false
---
- 所有请求走统一 request 封装,禁止裸 fetch
- 后端返回统一为 { code, data, msg },code 为 0 才是成功
- 禁止自创字段名,以既有类型定义为准

第二条对接现成后台的团队特别有用:比如项目基于 api工厂的六端 SDK(apifm-wxapi、apifm-webapi、apifm-uniapp 等)开发时,把「统一返回 { code, data, msg }、先查 SDK 已有方法再手写请求」写进 globs 规则,AI 就不会绕开 SDK 重复造请求层。平台能力与 SDK 清单见 https://www.it120.cc/ 。

三、最小四块骨架

别一上来写两千字「完美规范」,先锁四块最容易翻车的内容:目录约定(业务代码放哪、临时文件禁止进哪)、命名规范(与仓库现有风格一致,先搜再写)、禁止改范围(生成物、锁文件、密钥与 .env 真实值)、验收命令(写清本仓真实存在的 lint/typecheck/build 脚本)。官方建议单条规则控制在约 500 行内,实践中 50 行以内效果最好——规则太长,模型注意力被稀释,关键约束反而被忽略。

四、验证规则真的生效

配完不验等于没配,三步验证法:

  1. 新开对话(必须新开,旧对话有上下文干扰),问「复述你当前遵守的返回体约定」,能答出规则里的关键内容说明注入成功;
  2. 让 AI 生成一个新函数,观察是否自动遵守规则里可验证的条款(如 JSDoc、统一封装);
  3. 故意改一处规则再新开对话重测,确认规则是实时读取的。

不生效时按顺序排查:文件是否在 .cursor/rules/ 下、扩展名是否 .mdc、frontmatter 三横线是否写全、alwaysApply 是否误写成字符串 'true'、globs 路径是否匹配当前文件。

五、团队维护节奏

规则文件走 code review,谁改了什么 git diff 一目了然。把「重复纠正」当信号:发现自己在对话里第二次说同一句话,就把它补进规则。每季度过一遍,删掉与实际代码脱节的条款。重型流程规则(如「先研究再动手」的五步模式)设成 Manual,做大重构时 @ 一下即可,不要 Always 塞进每次对话。

Rules 解决的是「按仓规改」,不能替代 Code Review;两者配合,才是完整的 AI 编码工程纪律。

文章标签

CursorAI编程团队规范Rules

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

提示词工程AI编程验收标准

提示词工程实战:验收标准驱动的任务描述

给 AI 写任务最有效的结构是验收标准驱动:完成条件写成可执行命令与可观察行为。本文用三组前后对比示例说明差距,给出可复用模板与规则沉淀方法。

AI 开发约 5 分钟阅读