Cursor Rules 实战指导：构建高效稳定的 AI 代码生成规范体系
文章来源：得物技术 - Cursor Rules优化实战
文章作者：阳凯
发布时间：2025年6月23日
📋 目录
🎯 核心问题与挑战
问题本质
随着 AI 辅助编程工具的普及，Cursor IDE 已经成为越来越多开发者的选择。然而，在实际使用过程中，我们发现了一个关键问题：
如何让 AI 真正理解项目需求并生成高质量、一致性的代码？
AI 协作规范的特殊性
与传统的代码规范不同，AI 协作规范需要考虑更多维度：
mindmap
root((AI 协作规范挑战))
理解维度
业务逻辑理解
技术要求理解
上下文感知
质量维度
架构一致性
代码质量标准
性能优化
协作维度
团队统一标准
规范维护成本
冲突解决机制
核心挑战
- 如何让 AI 准确理解业务逻辑和技术要求
- 如何确保生成代码的架构一致性和质量标准
- 如何在团队中推广和维护统一的开发模式
- 如何避免规范冲突和维护成本过高的问题
⚠️ 旧版 Rules 的痛点分析
问题一：规则冗余与表述模糊
症状表现： - 大量无效描述，包括模糊要求（如”确保高性能”） - 重复定义和基础能力提示 - 冗余信息增加 token 消耗 - 分散 AI 注意力，显著降低代码生成效率
影响： - Token 消耗增加，成本上升 - AI 理解困难，生成质量下降 - 维护成本高，难以定位问题
问题二：提示词冲突
症状表现： - 规范中角色定义混乱（架构师、开发者等矛盾角色） - 缺乏规则优先级机制 - 多规则同时生效时产生行为矛盾 - 无法形成明确执行路径
影响： - AI 行为不一致 - 代码生成结果不可预测 - 团队协作困难
问题三：维护困境
症状表现： - 文档职责边界不清 - 新增规则时难以定位归属文件 - 修改单一功能需跨多文件调整 - 规则间依赖关系不透明 - 维护成本指数级增长
影响： - 规范更新困难 - 团队协作效率低 - 规范逐渐失效
🏗️ 新版 Rules 设计理念
核心设计原则
flowchart TB
A[设计理念] --> B[分层架构]
A --> C[职责分离]
A --> D[按需调用]
B --> B1[基础层]
B --> B2[模块层]
B --> B3[流程层]
C --> C1[单一职责]
C --> C2[边界清晰]
D --> D1[场景识别]
D --> D2[智能调用]
三层结构设计
新版本采用清晰的三层架构，每层都有明确的职责和边界：
graph TB
A[Cursor Rules 三层架构] --> B[基础层<br/>basic/]
A --> C[模块层<br/>modules/]
A --> D[流程层<br/>workflow/]
B --> B1[通用基础规范<br/>必须调用]
B --> B2[代码质量<br/>技术栈<br/>命名规范]
C --> C1[架构分层规范<br/>按需调用]
C --> C2[组件/页面<br/>服务/工具]
D --> D1[业务场景规范<br/>按需调用]
D --> D2[CRUD页面<br/>错误监控<br/>数据埋点]
style B fill:#e1f5ff
style C fill:#fff4e1
style D fill:#ffe1f5
标准化规则格式
为了确保规范的一致性和可维护性，定义了统一的规则格式：
# 规则名称
## 基础规范
- 明确的技术要求和实现标准
## 强制行为
- 必须执行的具体操作和约束
## 禁止行为
- 严格禁止的操作和做法，需要避免的常见错误
## 示例代码
- 具体的代码示例和最佳实践
- 也通过 [文件名](mdc:路径) 引用外部示例
格式优势： - ✅ 结构清晰：每个部分的职责明确，便于 AI 理解 - ✅ 可执行性：强制/禁止行为都有明确的操作指导 - ✅ 示例驱动：用实际代码代替抽象描述
AI 协作执行协议
为了确保 AI 能够正确理解和执行规范，设计了明确的 AI 协作协议提示词：
# AI协作执行规则
## 规则分类
- basic/下的通用规则: 必须调用，通用基础规范
- modules/下的模块规则: 按需调用，架构分层规范
- workflow/下的流程规则: 按需调用，业务场景规范
## 执行流程
1. 识别场景 → 调用相关规则
2. 读取示例代码 → 作为生成参考
3. 执行强制/禁止行为 → 确保代码质量
4. 应用设计原则 → 组件化、单一职责、分层设计
## 质量保障
- 所有规则必须100%执行，重点关注强制行为和禁止行为
🔍 三层架构深度剖析
1. 基础层的精细化设计
基础层是整个规范体系的根基，将原来混乱的 MDC 文件，精确拆分为 7 个职责单一的规范文件：
| 文件名 | 职责 | 核心内容 |
|---|---|---|
basic.mdc |
项目基础规范 | 目录结构、技术栈、开发流程 |
code-quality.mdc |
代码质量控制 | 复杂度限制、安全性要求 |
go.mdc |
Go语言规范 | 类型定义、接口设计、错误处理 |
comment.mdc |
注释规范 | Go doc格式、包注释、函数注释 |
code-names.mdc |
命名规范 | 变量、函数、结构体命名约定 |
format.mdc |
格式化规范 | gofmt、goimports配置 |
test.mdc |
测试规范 | 单元测试、基准测试、测试覆盖率 |
拆分好处： - ✅ 职责明确：每个文件只关注一个特定领域 - ✅ 维护便利：修改某个规范不会影响其他领域 - ✅ 学习友好：新人可以逐个理解每个规范的要求
示例：code-quality.mdc
# 代码质量分规范（通用规则）
## 强制行为
- 所有请求必须采用 HTTPS 协议
- 确保第三方库安全可靠
## 禁止行为
- 代码复杂度限制
- 单个文件不得超过 500 行
- 条件复杂度不得超过 10
- 单个函数不得超过 199 行
- 超过限制时，应优先按功能模块拆分为多个函数或文件
- 禁止在代码中包含明文密码或硬编码 token
- 禁止出现敏感词
- 避免重复代码块
- 不允许单词拼写错误或不符合命名规范
- 禁止使用魔数(如 `if status == 3`)，应使用常量(如 `if status == StatusLogin`)
- 禁止忽略错误处理，所有错误必须显式处理
- 禁止使用 `panic` 处理业务逻辑错误，应使用 `error` 返回
2. 模块层的分层设计
模块层的设计遵循 Go 后端分层架构思想，将复杂的应用拆分为职责明确的模块：
graph TB
A[模块层架构] --> B[接口层]
A --> C[业务逻辑层]
A --> D[数据访问层]
A --> E[模型层]
B --> B1[handler.mdc<br/>HTTP处理器规范]
B --> B2[middleware.mdc<br/>中间件规范]
C --> C1[service.mdc<br/>业务服务规范]
C --> C2[utils.mdc<br/>工具函数规范]
D --> D1[repository.mdc<br/>数据仓库规范]
D --> D2[model.mdc<br/>数据模型规范]
E --> E1[config.mdc<br/>配置管理规范]
E --> E2[constant.mdc<br/>常量定义规范]
示例：服务层规范（service.mdc）
# 业务服务生成规范（模块规则）
## 存放位置规范（按优先级）
- [p0] 业务服务：internal/service/{module}/{service}.go
- [p1] 通用服务：internal/service/common/{service}.go
- 接口定义：对应的 interface.go 文件
## 标准代码模板
go package user
import ( “context” “github.com/your-project/internal/model” “github.com/your-project/internal/repository” )
// UserService 用户服务接口 type UserService interface { GetUserList(ctx context.Context, req *GetUserListReq) (*GetUserListResp, error) }
type userService struct { repo repository.UserRepository }
// NewUserService 创建用户服务实例 func NewUserService(repo repository.UserRepository) UserService { return &userService{ repo: repo, } }
// GetUserList 获取用户列表 func (s *userService) GetUserList(ctx context.Context, req *GetUserListReq) (*GetUserListResp, error) { users, total, err := s.repo.List(ctx, req.Page, req.PageSize, req.Keyword) if err != nil { return nil, fmt.Errorf(“获取用户列表失败: %w”, err) }
return &GetUserListResp{
List: users,
Total: total,
}, nil
}
## 强制行为
- 所有服务必须实现接口，便于测试和依赖注入
- 服务方法必须接收 context.Context 作为第一个参数
- 错误处理必须使用 fmt.Errorf 包装，保留错误链
- 服务命名采用 {Module}Service 格式
- 所有公共方法必须有完整的 Go doc 注释
3. 流程层的场景化设计
流程层是当前架构的创新点，针对具体业务场景定制化规范，将复杂的业务场景标准化。
| 流程文件 | 业务场景 | 核心功能 |
|---|---|---|
crud-api.mdc |
CRUD API开发 | CRUD接口完整开发流程 |
log.mdc |
错误监控 | 日志记录和错误处理流程 |
middleware.mdc |
中间件开发 | 认证、限流等中间件标准流程 |
...... |
…… | …… |
示例：crud-api.mdc
# CRUD API生成规范（流程规则）
深入研究代码并理解[insert feature]是如何工作的。一旦你明白了，让我知道，我将提供我的任务给你。
## 工作流程
按以下流程进行任务执行，如果评估存在非必须流程，可跳过。
- MCP读取接口信息
- 从用户输入中提取以下信息：
- 资源名称（如：用户、订单）
- 字段列表（字段名、类型、是否必填、是否可搜索）
- 操作项（创建、查询、更新、删除）
- 业务规则和约束
- 评估完整的需求内容复杂度，考虑未来的扩展性，合理设计分层目录结构
- 各个模块保持单一职责，遵循 handler -> service -> repository 分层
- 使用命令行批量创建目录文件（包含 handler.go、service.go、repository.go、model.go 等）
- 文件暂不生成代码
- 配置路由信息（使用 gin/echo 等框架）
- 生成 model 文件，确保所有结构体定义清晰，包含 json tag 和 validate tag
- 生成 constant 文件，定义状态码、错误码等常量
- 生成 repository 文件，实现数据访问层
- 生成 service 文件，实现业务逻辑层
- 生成 handler 文件，实现 HTTP 接口层
- 生成单元测试文件
## 强制行为
- 使用标准 RESTful API 设计，路径采用 /api/v1/{resource} 格式
- 所有接口必须实现统一的响应格式（包含 code、message、data）
- 分页参数统一使用 page 和 page_size
- 所有数据库操作必须使用事务（如需要）
- 错误处理必须使用自定义错误类型，包含错误码和错误信息
- 所有接口必须添加请求参数验证
- 分页设置支持10、20、50、100
- 所有公共方法必须有完整的 Go doc 注释
- 必须实现对应的单元测试，覆盖率不低于 80%
## 禁止行为
- 禁止在 handler 中直接操作数据库
- 禁止在 service 中直接使用 HTTP 相关类型
- 禁止忽略错误处理
- 禁止使用 panic 处理业务错误
- 禁止硬编码配置信息
.....
流程层优势： - ✅ 开发效率：标准化流程减少决策时间 - ✅ 质量一致性：所有表格页面都遵循相同的标准 - ✅ 维护性：统一的结构便于后期维护
🚀 最佳实践指南
快速开始
第一步：创建基础架构
.cursor/rules/
├── ai.mdc # AI协作总纲
├── basic/ # 基础规范目录
│ ├── basic.mdc
│ ├── code-quality.mdc
│ ├── go.mdc
│ ├── format.mdc
│ ├── comment.mdc
│ ├── code-names.mdc
│ └── test.mdc
├── modules/ # 模块规范目录
│ ├── handler.mdc
│ ├── middleware.mdc
│ ├── service.mdc
│ ├── repository.mdc
│ ├── model.mdc
│ ├── utils.mdc
│ ├── config.mdc
│ └── constant.mdc
└── workflow/ # 流程规范目录
├── crud-api.mdc
├── log.mdc
└── middleware.mdc
└── ......
第二步：配置 AI 协作协议
在 ai.mdc 中定义核心协作规则：
# AI协作执行规则
## 规则分类
- basic/下的通用规则: 必须调用，通用基础规范
- modules/下的模块规则: 按需调用，架构分层规范
- workflow/下的流程规则: 按需调用，业务场景规范
## 执行流程
1. 识别场景 → 调用相关规则
2. 读取示例代码 → 作为生成参考
3. 执行强制/禁止行为 → 确保代码质量
4. 应用设计原则 → 组件化、单一职责、分层设计
## 质量保障
- 所有规则必须100%执行，重点关注强制行为和禁止行为
分阶段实施计划
gantt
title Cursor Rules 实施计划
dateFormat YYYY-MM-DD
section 试点阶段
选择试点项目 :done, des1, 2025-01-01, 2025-01-07
收集反馈 :active, des2, 2025-01-08, 2025-01-21
section 优化阶段
优化规范内容 : des3, 2025-01-22, 2025-02-05
开发工具 : des4, 2025-02-06, 2025-02-20
section 标准化阶段
制定团队标准 : des5, 2025-02-21, 2025-03-07
持续改进机制 : des6, 2025-03-08, 2025-03-22
| 阶段 | 目标 | 关键活动 |
|---|---|---|
| 试点阶段 | 验证规范有效性 | 选择1-2个项目试点，收集反馈 |
| 优化阶段 | 完善规范内容 | 根据试点反馈优化规范，开发工具 |
| 标准化阶段 | 形成团队标准 | 制定团队级标准，持续改进机制 |
实施检查清单
💼 实战案例
案例一：CRUD API 开发
场景：需要开发一个用户管理 API，包含列表查询、详情查询、创建、更新、删除功能。
使用流程：
- 识别场景：这是典型的 CRUD API 开发场景
- 调用规则：AI 自动调用
workflow/crud-api.mdc - 执行流程：
- MCP 读取接口信息
- 提取用户需求（字段列表、业务规则等）
- 设计分层目录结构（handler、service、repository、model）
- 批量创建文件
- 生成 model 结构体（包含 json tag、validate tag）
- 生成 repository 数据访问层
- 生成 service 业务逻辑层
- 生成 handler HTTP 接口层
- 生成单元测试
- 质量检查：确保符合所有强制行为和禁止行为
结果：生成的代码完全符合团队规范，分层清晰，易于维护和测试。
案例二：业务服务开发
场景：需要开发一个新的用户列表查询服务。
使用流程：
- 识别场景：这是业务服务开发场景
- 调用规则：
- 基础层：
basic/code-quality.mdc、basic/go.mdc（必须） - 模块层：
modules/service.mdc、modules/repository.mdc（按需）
- 基础层：
- 执行流程：
- 使用 MCP 工具获取接口详情
- 生成符合标准的 service 接口和实现
- 生成对应的 repository 接口和实现
- 生成 model 结构体定义
- 完整的错误处理和上下文传递
- 生成单元测试
- 质量检查：确保符合命名规范、错误处理、接口设计等要求
结果：生成的服务代码规范统一，接口清晰，错误处理完善，易于测试和维护。
📊 效果对比
优化前后对比
| 维度 | 优化前 | 优化后 | 提升 |
|---|---|---|---|
| 规则文件数 | 3-5 个大文件 | 20+ 个职责单一文件 | 结构清晰 |
| Token 消耗 | 高（冗余信息多） | 低（精准调用） | 降低 40-60% |
| 代码生成质量 | 不稳定 | 稳定一致 | 显著提升 |
| 维护成本 | 高（跨文件修改） | 低（单文件修改） | 降低 70% |
| 团队协作 | 困难（规范冲突） | 顺畅（统一标准） | 显著改善 |
核心优势
mindmap
root((三层架构优势))
单一职责
每个文件职责明确
维护简单
冲突减少
分层架构
基础→模块→流程
依赖明确
扩展容易
按需调用
场景识别
精准调用
效率提升
示例驱动
代码示例
AI理解准确
执行到位
持续进化
迭代优化
适应变化
持续改进
📝 总结与展望
核心价值
基于以下设计思路，通过构建三层架构的 AI 协作规范体系：
- 单一职责：每个规范文件只负责一个功能领域，规则维护简单，冲突减少。
- 分层架构：基础→模块→流程的清晰层级，规则依赖明确，扩展容易。
- 按需调用：根据开发场景智能调用相关规范，使得上下文信息精准，效率提升。
- 示例驱动：用代码示例代替抽象描述，AI 理解准确，执行到位。
- 持续进化：支持规范的迭代优化和扩展，研发适应变化，持续改进。
方法论推广
这套方法论不仅适用于 Cursor Rules，更可以推广到其他 AI 协作工具的规范设计中：
- Claude Code：可以应用相同的分层架构思想
- GitHub Copilot：可以借鉴按需调用的设计理念
- 其他 AI 工具：示例驱动的规范设计具有通用性
未来展望
在 AI 辅助编程快速发展的今天，构建一套清晰、系统化的协作规范，将是每个开发团队的核心竞争力。
建议行动： 1. ✅ 立即开始构建自己的 Rules 体系 2. ✅ 从基础层开始，逐步完善 3. ✅ 在团队中推广，形成统一标准 4. ✅ 持续优化，适应项目变化
📚 参考资料
最后更新：2026年1月14日
版本：1.0
基于文章：得物技术 - 阳凯《Cursor Rules优化实战：构建高效稳定的AI代码生成规范体系》