目录
- 一、背景
- 二、旧版 Rules 痛点
- 三、新版 Rules 设计理念
- 四、三层结构深度剖析
-
- 基础层的精细化设计
-
- 模块层的分层设计
-
- 流程层的场景化设计
- 五、最佳实践
- 六、总结
一、背景
随着 AI 辅助编程工具的普及，Cursor IDE 成为越来越多开发者的选择。但在真实工程里，大家很快会遇到同一个关键问题：如何让 AI 真正理解项目需求，并持续生成高质量、强一致性的代码？
解决思路不是堆更多“最佳实践”，而是构建一套系统化的 AI 协作规范。它和传统代码规范相比，需要额外考虑更多维度：
- 如何让 AI 准确理解业务逻辑和技术要求
- 如何确保生成代码的架构一致性和质量标准
- 如何在团队中推广并长期维护统一开发模式
- 如何避免规范互相冲突、维护成本越来越高
本文基于真实落地经验，复盘 Cursor Rules 的优化过程：如何从混乱的规范堆叠，演进到清晰、高效的 AI 协作规范架构（也欢迎在 云栈社区 交流类似实践）。
二、旧版 Rules 痛点
优化前，团队的规范体系主要有三个核心问题，直接影响 AI 生成质量与效率。
问题一：规则冗余与表述模糊
旧规范里存在大量无效描述：模糊要求（如“确保高性能”）、重复定义、基础能力提示等。这类内容不仅增加 token 消耗，还会分散 AI 注意力，导致生成效率下降、结果不稳定。
问题二：提示词冲突
角色定义混乱：同一套规范里，AI 被要求同时扮演架构师、开发者等不同角色。更关键的是缺少规则优先级机制，多规则同时生效时容易互相打架，AI 很难形成明确的执行路径。
问题三：维护困境
文档职责边界不清：新增规则时难以判断归属文件；修改一个功能往往需要跨多文件同步；规则依赖关系也不透明，维护成本呈指数增长。
三、新版 Rules 设计理念
针对上述问题，新版规则体系的核心理念是：分层架构 + 职责分离 + 按需调用。
三层结构设计
新版本采用清晰的三层架构，每层都有明确的职责与边界：
标准化规则格式
为了保证一致性与可维护性，先统一每份规则的结构格式：
# 规则名称
## 基础规范
- 明确的技术要求和实现标准
## 强制行为
- 必须执行的具体操作和约束
## 禁止行为
- 严格禁止的操作和做法，需要避免的常见错误
## 示例代码
- 具体的代码示例和最佳实践
- 也通过 [文件名](mdc:路径) 引用外部示例
该格式的收益点：
- 结构清晰：每部分职责明确，AI 更容易抓重点。
- 可执行性：强制/禁止行为可直接转为执行约束。
- 示例驱动：用代码示例替代抽象描述，减少理解偏差。
AI 协作执行协议
仅有规则还不够，还需要一个“AI 执行协议”告诉它：规则怎么选、怎么用、先后顺序是什么。
# AI协作执行规则
## 规则分类
- basic/下的通用规则: 必须调用，通用基础规范
- modules/下的模块规则: 按需调用，架构分层规范
- workflow/下的流程规则: 按需调用，业务场景规范
## 执行流程
1. 识别场景 → 调用相关规则
2. 读取示例代码 → 作为生成参考
3. 执行强制/禁止行为 → 确保代码质量
4. 应用设计原则 → 组件化、单一职责、分层设计
## 质量保障
- 所有规则必须100%执行，重点关注强制行为和禁止行为
四、三层结构深度剖析
接下来拆解三层结构如何落地，以及每一层解决了什么问题。
1. 基础层的精细化设计
基础层是整个规范体系的根基。我们将原来混乱的 MDC 文件，拆分为 7 个职责单一的规范文件：
| 文件名 |
职责 |
核心内容 |
| basic.mdc |
项目基础规范 |
目录结构、技术栈、开发流程 |
| code-quality.mdc |
代码质量控制 |
复杂度限制、安全性要求 |
| ts.mdc |
TypeScript 规范 |
类型定义、严格模式配置 |
| comment.mdc |
注释规范 |
JSDoc 格式、文件头注释 |
| code-names.mdc |
命名规范 |
变量、函数、组件命名约定 |
| style.mdc |
样式规范 |
CSS/Less 编写标准 |
| lint.mdc |
代码检查 |
ESLint、Prettier 配置 |
拆分后的直接收益：
- 职责明确：每个文件只关注一个领域，减少耦合。
- 维护便利：改某个规范，不会“牵一发动全身”。
- 学习友好：新人可以按主题逐个理解。
这里的 ESLint、Prettier 属于前端工程化常见实践，可参考 前端框架/工程化 的相关讨论沉淀更多团队经验。
示例：code-quality.mdc 定义了代码质量分规范（通用规则）：
# 代码质量分规范（通用规则）
## 强制行为
- 所有请求必须采用 HTTPS 协议
- 确保第三方库安全可靠
## 禁止行为
- 代码复杂度限制
- 单个文件不得超过 500 行
- 条件复杂度不得超过 10
- 单个函数不得超过 199 行
- 超过限制时，应优先按功能模块拆分为多个函数或文件
- 禁止使用非得物域名的外部 CDN 资源
- 禁止在代码中包含明文密码或硬编码 token
- 禁止出现敏感词
- 避免重复代码块
- 不允许单词拼写错误或不符合命名规范
- 避免在前端直接进行金额计算(导致精度丢失)
- 禁止使用魔数(如 a === '3')，应使用常量(如 a === statusMap.login)
2. 模块层的分层设计
模块层遵循前端分层架构思想，把复杂应用拆成职责明确、可组合的模块规范：
- 表现层：components.mdc（组件规范）、pages.mdc（页面规范）
- 业务逻辑层：hooks.mdc（状态管理）、utils.mdc（工具函数）
- 数据服务层：service.mdc（API 接口）、constants.mdc（配置管理）
- 路由层：route.mdc（路由配置和导航）
这种分层的价值在于：AI 每次生成代码时，不是“凭感觉写文件”，而是先对齐分层模型，再在对应层里产出代码与结构。
示例：服务层规范（service.mdc）定义了 API 接口的标准化开发流程：
# API接口生成规范（模块规则）
## 存放位置规范（按优先级）
- [p0] 页面级API：src/pages/{pageName}/services/{modules}.ts
- [p1] 全局API：src/services/{modules}.ts
- 类型文件：对应的 .interface.ts 文件
## 标准代码模板
import { request } from '@/utils/request';
import { UniversalResp } from '@/utils/request-operation';
import { IUserListReq, IUserListDataRes } from './interface';
/**
* 获取用户列表
* @param data 请求参数
*/
export const fetchUserListApi = async (data: IUserListReq) => {
return request.post<UniversalResp<IUserListDataRes>>(
'/api/user/list',
data
);
};
## 强制行为
- 使用MCP Server的mooncake_get_api_details工具获取接口详情
- 响应数据必须使用UniversalResp<T>泛型包装
- 接口命名采用fetch{ApiFileName}Api格式
- 类型定义必须完整，包含完整字段注释
3. 流程层的场景化设计
流程层是这套架构的创新点：面向具体业务场景，把“做事的方法”也标准化。这样 AI 不止知道“代码要怎么写”，还知道“任务应该按什么顺序推进”。
| 流程文件 |
业务场景 |
核心功能 |
| curd-page.mdc |
curd 页面开发 |
curd 页面完整使用流程 |
| log.mdc |
错误监控 |
APM 监控和错误日志处理流程 |
| sendBuried.mdc |
数据埋点 |
用户行为埋点标准流程 |
| ...... |
|
|
示例：curd-page.mdc 定义了完整的表格页面开发流程：
该流程确保：
- 开发效率：标准流程减少决策时间与返工。
- 质量一致性：同类页面输出风格与结构更统一。
- 维护性：统一目录结构与职责划分，后期可持续演进。
# pro-table生成新页面（流程规则）
深入研究代码并理解[insert feature]是如何工作的。一旦你明白了，让我知道，我将提供我的任务给你。
## 工作流程
按以下流程进行任务执行，如果评估存在非必须流程，可跳过。
- MCP读取接口信息
- 从用户输入中提取以下信息：
- 列表名称
- 筛选项（需标记hideInTable）
- 展示项（需标记hideInSearch）
- 操作项
- 工具栏按钮
- 评估完整的需求内容复杂度，考虑未来的扩展性，合理设计分层目录结构
- 各个模块保持单一职责，考虑合理的业务组件拆分，避免大量代码都在页面主入口文件
- 使用命令行批量创建目录文件（包含各类文件ts、tsx、less等）
- 文件暂不生成代码
- 配置页面的路由信息
- 生成类型文件，确保所有类型定义清晰
- 生成constants文件，定义所需常量
- 生成services文件，实现数据服务
- 生成所需的 hooks 文件
- 生成页面（必需）和components（如需）文件 完成UI层
## 强制行为
- 使用pro-table进行开发，包括筛选表单，符合最佳实践
- 筛选项和列表项配置创建useColumns.tsx声明，筛选项（需标记hideInTable）、展示项（需标记hideInSearch）
- 左侧字段按需固定，操作项右侧固定，最多显示两个，超出折叠显示
- 文本左对齐，数字右对齐，状态枚举居中显示
- 分页设置支持10、20、50、100
- .....
# 禁止行为
.....
五、最佳实践
1. 快速开始
第一步：创建基础架构
.cursor/rules/
├── ai.mdc # AI协作总纲
├── basic/ # 基础规范目录
│ ├── basic.mdc
│ ├── code-quality.mdc
│ ├── ts.mdc
│ ├── style.mdc
│ ├── comment.mdc
│ ├── code-names.mdc
│ └── lint.mdc
├── modules/ # 模块规范目录
│ ├── components.mdc
│ ├── pages.mdc
│ ├── hooks.mdc
│ ├── service.mdc
│ ├── constants.mdc
│ ├── utils.mdc
│ └── route.mdc
└── workflow/ # 流程规范目录
├── curd-page.mdc
├── log.mdc
└── send-buried.mdc
└── ......
第二步：配置 AI 协作协议
在 ai.mdc 中定义核心协作规则（让 AI “知道怎么执行”）：
# AI协作执行规则
## 规则分类
- basic/下的通用规则: 必须调用，通用基础规范
- modules/下的模块规则: 按需调用，架构分层规范
- workflow/下的流程规则: 按需调用，业务场景规范
## 执行流程
1. 识别场景 → 调用相关规则
2. 读取示例代码 → 作为生成参考
3. 执行强制/禁止行为 → 确保代码质量
4. 应用设计原则 → 组件化、单一职责、分层设计
## 质量保障
所有规则必须100%执行，重点关注强制行为和禁止行为
2. 分阶段实施计划
| 阶段 |
目标 |
关键活动 |
| 试点阶段 |
验证规范有效性 |
选择 1-2 个项目试点，收集反馈 |
| 优化阶段 |
完善规范内容 |
根据试点反馈优化规范，开发工具 |
| 标准化阶段 |
形成团队标准 |
制定团队级标准，持续改进机制 |
六、总结
这套 Cursor Rules 体系的关键，不是“写得更长”，而是基于以下设计思路，构建可扩展、可维护的三层 AI 协作规范：
- 单一职责：每个规范文件只负责一个功能领域，维护更直观，冲突更少。
- 分层架构：基础 → 模块 → 流程，层级清晰，依赖明确，扩展更容易。
- 按需调用：根据场景调用相关规则，上下文更精准，生成效率更高。
- 示例驱动：用代码示例替代抽象描述，AI 理解更准确，执行更到位。
- 持续进化：支持迭代扩展，团队能在变化中持续改进。
AI 辅助编程发展很快，但真正拉开差距的，往往不是工具本身，而是你是否建立了“可执行、可演进”的协作规范体系。想把经验系统化沉淀？可以进一步参考 人工智能 板块中关于提示词与工程化落地的讨论。
发表于 2 小时前
|
查看: 2|
回复: 0
