Cursor AI 编码规范与架构守护指南

版本：v1.0 适用场景：个人 / 团队使用 Cursor 进行中大型项目开发 核心目标：在保留 AI 编码 10 倍效率的同时，实现 100% 的细节掌控和零架构漂移

一、核心原则与分工（必须严格遵守）

1.1 不可动摇的分工边界

1.2 黄金法则

1. 永远不要让 AI 写你看不懂的代码：任何一行代码你必须完全理解

2. 一次只让 AI 做一件事：单个任务代码量不超过 50 行

3. 架构先行，代码后行：没有架构文档，不写一行业务代码

4. 测试定义行为：先写测试，再让 AI 生成实现

二、项目初始化阶段：架构前置锁

这是防止架构漂移最重要的阶段，必须在写任何业务代码前完成。

2.1 创建项目架构文档

在项目根目录创建 docs/architecture.md，包含以下内容：

# 项目架构文档
## 1. 系统概述
- 项目名称：
- 核心功能：
- 技术栈：
- 依赖版本：

## 2. 模块划分
```mermaid
graph TD
    A[API层] --> B[服务层]
    B --> C[数据访问层]
    D[通用工具层] --> A
    D --> B
    D --> C

3. 核心数据流

4. 模块依赖规则

• ✅ API 层只能依赖 Service 层

• ✅ Service 层只能依赖 Repository 层和工具层

• ✅ Repository 层只能依赖数据库和工具层

• ❌ 禁止任何循环依赖

• ❌ 禁止 API 层直接访问数据库

5. 核心接口定义

5.1 用户服务接口

interface UserService {
  register(dto: UserRegisterDTO): Promise<UserVO>;
  login(dto: UserLoginDTO): Promise<LoginResponse>;
  getUserById(id: string): Promise<UserVO>;
}

6. 编码规范

• 所有函数必须添加 JSDoc 注释

• 使用 TypeScript 严格模式，禁止使用any类型

• 错误处理必须使用 try-catch，统一返回标准错误格式

• 数据库操作必须使用事务

### 2.2 配置Cursor全局上下文
在Cursor中执行以下操作，让AI永远遵循你的架构：
1. 打开命令面板（Ctrl+Shift+P）
2. 选择 "Cursor: Add Context File"
3. 添加 `docs/architecture.md`
4. 确认："从现在开始，所有代码生成必须严格遵循此架构文档"

### 2.3 建立不可变层与可变层
| 不可变层（禁止AI修改） | 可变层（AI可快速迭代） |
|------------------------|------------------------|
| 路由结构 | 具体API实现 |
| 中间件链 | 业务逻辑 |
| 数据库连接层 | UI组件 |
| 统一响应格式 | 配置文件 |
| 核心工具类 | 测试用例 |

---

## 三、日常开发流程：细节掌控标准作业程序
### 3.1 任务拆解标准流程
任何功能都必须拆解为**不超过50行代码**的原子任务，每个任务有明确的输入和输出。

#### ❌ 错误的任务描述

帮我实现用户管理功能

#### ✅ 正确的任务拆解
1. "根据架构文档中的User实体，生成UserRegisterDTO类，包含email、password、confirmPassword字段，添加JSR-380验证注解"
2. "实现UserRepository中的findByEmail方法，参数为email，返回Optional<User>"
3. "实现UserService中的register方法，参数为UserRegisterDTO，返回UserVO，步骤：验证邮箱是否存在→密码加密→保存用户→生成JWT"
4. "实现UserController中的/register接口，处理POST请求，参数绑定和异常处理"

### 3.2 代码生成与检查SOP
每次Cursor生成代码后，必须完成以下三步检查：

#### 第一步：逻辑检查（必做）
- 逐行阅读代码，确认逻辑与你的预期完全一致
- 任何看不懂的代码，立即要求："逐行解释这段代码的作用"
- 确认没有引入未在架构文档中定义的依赖

#### 第二步：边界检查（必做）
- 参数为空的情况是否处理
- 数据库错误、网络超时等异常是否处理
- 边界值（如最大长度、最小值）是否验证
- 权限控制是否正确实现

#### 第三步：风格检查（必做）
- 命名是否符合项目规范
- 是否添加了必要的注释
- 代码格式是否统一
- 是否有重复代码可以提取

### 3.3 Cursor高效使用技巧
- **@-mention引用**：使用`@文件名`引用现有文件，`@函数名`引用现有函数
- **代码片段库**：将常用模式（控制器、服务、DTO模板）保存为代码片段
- **增量修改**：不要让AI重写整个文件，只修改需要改变的部分
- **上下文清理**：定期清理聊天历史，避免旧上下文干扰新代码生成

---

## 四、架构守护：自动化防线
### 4.1 AI时代的TDD流程
测试是防止架构漂移最有效的工具，流程优化为：
1. **你**：编写测试用例（定义代码的正确行为）
2. **Cursor**：根据测试用例生成实现代码
3. **你**：运行测试，验证结果
4. **Cursor**：修复测试失败的问题
5. **你**：重构代码，保持架构整洁

### 4.2 架构单元测试
用代码强制执行架构规则，在CI/CD中自动运行：

#### TypeScript示例（使用dependency-cruiser）
```javascript
// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: "api-not-allowed-to-access-repository",
      comment: "API层不能直接访问Repository层",
      from: { path: "src/controllers/" },
      to: { path: "src/repositories/" }
    },
    {
      name: "no-circular-dependencies",
      comment: "禁止循环依赖",
      circular: true
    }
  ]
};

Java 示例（使用 ArchUnit）

@Test
public void controllersShouldOnlyDependOnServices() {
  noClasses()
    .that().resideInAPackage("..controllers..")
    .should().dependOnClassesThat().resideInAPackage("..repositories..")
    .check(importedClasses);
}

4.3 定期架构复盘

• 频率：每周 30 分钟

• 内容：

  • 检查本周代码是否符合架构规范

  • 记录出现的架构漂移问题及原因

  • 讨论是否需要调整架构以适应新需求

  • 更新架构文档

五、团队协作规范

5.1 团队 AI 编码公约

1. 所有人必须使用相同的架构文档和自定义指令

2. 核心架构修改必须经过团队评审

3. 代码审查重点：架构一致性 > 业务逻辑 > 实现细节

4. 禁止提交 AI 生成的未经过逐行检查的代码

5.2 优化后的代码审查流程

1. 提交者：完成自测和自审，确保代码符合规范

2. AI：自动检查代码风格、语法错误、常见漏洞

3. 审查者：

   1. 架构是否符合文档要求

   2. 业务逻辑是否正确

   3. 是否有安全隐患

   4. 测试用例是否充分

六、Cursor 高级配置

6.1 全局自定义指令

在 Cursor 设置 → Features → Custom Instructions 中添加：

# 代码生成规则
1. 严格遵循项目根目录docs/architecture.md中的架构设计
2. 所有函数必须添加JSDoc注释，说明功能、参数、返回值和异常
3. 使用TypeScript严格模式，禁止使用any类型
4. 错误处理必须使用try-catch，统一返回{code: number, message: string, data: any}格式
5. 数据库操作必须使用事务，确保数据一致性
6. 不要引入未在package.json中声明的依赖
7. 保持代码简洁，避免过度设计

# 代码审查规则
当我让你审查代码时，请重点检查：
1. 是否符合架构规范
2. 逻辑是否正确
3. 是否处理了边界情况和异常
4. 是否有安全漏洞
5. 是否可以优化性能

6.2 项目级配置文件

在项目根目录创建 .cursorrules 文件，覆盖全局配置：

# 项目特定规则
architecture: docs/architecture.md
coding_style: .eslintrc.js
test_framework: jest
database: postgresql

七、常见问题与解决方案

问题 1：AI 总是生成不符合架构的代码

解决方案：

• 确保架构文档清晰、具体，包含代码示例

• 使用@docs/architecture.md明确引用

• 生成代码前先问："这段代码是否符合我们的架构规范？"

• 对于严重违反架构的代码，直接删除重写

问题 2：代码量太大，无法逐行检查

解决方案：

• 严格执行任务拆解，单个任务不超过 50 行

• 使用 AI 辅助审查："帮我逐行解释这段代码，指出可能存在的问题"

• 重点检查核心逻辑和异常处理，样板代码可以快速浏览

问题 3：团队成员使用 AI 的方式不一致

解决方案：

• 制定统一的《AI 编码规范》并强制执行

• 组织培训，确保所有人掌握正确的使用方法

• 在代码审查中重点检查 AI 代码的质量

• 建立最佳实践分享机制

八、快速开始检查清单

✅ 完成架构文档编写并添加到 Cursor 上下文 ✅ 配置全局自定义指令和项目级规则 ✅ 建立不可变层与可变层的边界 ✅ 配置架构单元测试并集成到 CI/CD ✅ 制定团队 AI 编码公约 ✅ 对所有开发人员进行培训

总结

使用 Cursor 进行高效且高质量的开发，关键在于建立规则，而不是限制能力。通过架构前置、精细拆解、自动化守护和团队规范，你可以在享受 AI 带来的 10 倍效率提升的同时，保持对代码的完全掌控。

记住：AI 是放大器，它会放大你的优点，也会放大你的缺点。好的流程和规范，是让 AI 成为你最好助手的唯一途径。