# Cursor首席设计师12条黄金法则：高质量代码生成技巧

> 来源：Cursor首席设计师Ryo Lu分享的AI编程最佳实践

## 核心理念

使用Cursor得当 = 快速、干净的代码  
使用不当 = AI意大利面，你得收拾一整周

## 12条黄金法则



![image-20250627175927166](..\assets\images\RyoLu-cursor-usage-suggestion-12.png)

### 中英文对照表

| 序号 | 原文 | 翻译 |
|------|----------|----------|
| 1 | Set 5-10 clear project rules upfront so Cursor knows your structure and constraints. Try /generate rules for existing codebases. | 预先设定5-10条明确的项目规则，让Cursor了解你的结构和限制。对于现有代码库，可以尝试使用/generate rules命令。 |
| 2 | Be specific in prompts. Spell out tech stack, behavior, and constraints like a mini spec. | 在提示中要具体明确。像写一份微型规格书一样，详细说明技术栈、行为和约束条件。 |
| 3 | Work file by file; generate, test, and review in small, focused chunks. | 逐文件处理；以小而专注的模块为单位进行生成、测试和审查。 |
| 4 | Write tests first, lock them, and generate code until all tests pass. | 先写测试，锁定它们，然后生成代码直到所有测试通过。 |
| 5 | Always review AI output and hard‑fix anything that breaks, then tell Cursor to use them as examples. | 始终审查AI的输出，对任何出错的地方进行硬性修复，然后告诉Cursor以这些修复作为示例。 |
| 6 | Use @ file, @ folders, @ git to scope Cursor's attention to the right parts of your codebase. | 使用@file、@folders、@git来限定Cursor对代码库中正确部分的注意力范围。 |
| 7 | Keep design docs and checklists in .cursor/ so the agent has full context on what to do next. | 将设计文档和检查清单保存在.cursor/目录下，这样代理就能全面了解下一步该做什么。 |
| 8 | If code is wrong, just write it yourself. Cursor learns faster from edits than explanations. | 如果代码有误，直接自己动手修改。Cursor从编辑中学习的速度比解释更快。 |
| 9 | Use chat history to iterate on old prompts without starting over. | 利用聊天记录迭代旧提示，无需从头开始。 |
| 10 | Choose models intentionally. Gemini for precision, Claude for breadth. | 有意识地选择模型。Gemini用于精确性，Claude用于广度。 |
| 11 | In new or unfamiliar stacks, paste in link to documentation. Make Cursor explain all errors and fixes line by line. | 在新的或不熟悉的技术栈中，粘贴文档链接。让Cursor逐行解释所有错误和修复。 |
| 12 | Let big projects index overnight and limit context scope to keep performance snappy. | 让大项目过夜索引，并限制上下文范围以保持性能敏捷。 |

### 1. 设定明确的项目规则

**核心：** 预先设定5-10条明确的项目规则，让Cursor了解你的结构和限制

**操作：**
- 对于现有代码库，使用 `/generate rules` 命令
- 在项目根目录创建 `.cursorrules` 文件
- 定义代码风格、架构约束、命名规范

**基础示例：**
```
- 使用Spring Boot 1.5.13 + Spring Cloud Edgware.SR4架构
- 所有微服务遵循com.zhht包结构规范
- Controller必须继承BaseController并包含健康检查
- Feign客户端必须实现fallback降级处理
- 数据库操作统一使用MyBatis，禁用JPA
- Redis缓存键必须在CacheKey常量类中定义
- MQTT连接使用固定ClientId，cleanSession=false
```

**实际案例：`/generate rules` 命令生成的完整项目规则**

通过在项目根目录运行 `/generate rules` 命令，Cursor自动分析了一个微服务停车管理系统并生成了详细的项目规则文档。这个案例展示了如何为复杂的多模块项目建立全面的开发规范。

**生成的规则文档包含：**
- **项目概览**：4个微服务的职责划分和技术栈
- **架构模式**：Spring Cloud服务发现、Feign客户端、断路器等
- **包结构约定**：统一的代码组织规范
- **配置管理**：环境配置和部署规范
- **编码规范**：命名约定、错误处理、缓存模式等

**完整示例文档：** [`cursor_generate_cursor_rules.md`](cursor_generate_cursor_rules.md)

**关键收益：**
1. **自动化分析**：无需手动梳理项目结构
2. **全面覆盖**：涵盖架构、编码、配置、部署各个层面
3. **标准化**：确保团队遵循统一的开发规范
4. **可维护性**：新成员可快速理解项目架构

这个实际案例证明了 `/generate rules` 命令的强大功能，能够为复杂项目快速建立完整的开发指南。

### 2. 精准提示词设计

**公式：** 技术栈 + 行为规范 + 约束条件

**对比：**
- ❌ **模糊提示：** "写一个设备管理功能。"
- ✅ **精准提示：** "在micro-cloud-adapter服务中用Spring Boot实现MQTT设备管理Controller，继承CheckAliveController模式，实现设备状态监控和命令下发，使用RedisCacheTemplate缓存设备信息，包含Feign客户端调用其他服务，添加完整的异常处理和日志记录。"

**要点：**
- 详细说明技术栈
- 明确行为规范
- 列出约束条件
- 像写技术规格书一样详细

### 3. 文件级迭代：小步快跑

**策略：**
- 单文件生成：每个文件独立生成、测试、审查
- 避免全局失控，逐步集成
- 小而专注的模块化开发

**流程：**
1. 选择单个文件进行生成
2. 立即测试该文件功能
3. 审查代码质量
4. 确认无误后集成到项目

**案例：** 开发停车管理系统时，先独立生成"DeviceCmdController"，测试MQTT消息处理通过后再集成到micro-cloud-adapter服务。

### 4. 测试驱动开发（TDD）

**流程：**
1. 人工编写测试用例（如JUnit单元测试）
2. 锁定测试，让Cursor生成代码直至测试通过
3. 若失败，将错误日志提供给AI修正

**优势：**
- 解决AI"逻辑正确但功能错误"的问题
- 确保代码质量和功能正确性
- 提供明确的成功标准

**示例：**
```java
// 先写测试
@Test
public void testMqttMessageHandler() {
    // 准备测试数据
    String deviceId = "DEVICE_001";
    String message = "{\"cmd\":\"heartbeat\",\"data\":{\"status\":\"online\"}}";
    
    // 执行测试
    MqttMessageHandler handler = new MqttMessageHandler();
    boolean result = handler.handleDeviceMessage(deviceId, message);
    
    // 验证结果
    assertTrue(result);
    verify(redisCacheTemplate).set(CcaCacheKey.getDeviceStatusKey(deviceId), "online");
}

// 然后让Cursor生成MqttMessageHandler实现代码
```

### 5. 人工审查与反馈

**原则：**
- 始终审查AI的输出
- 手动修正错误代码
- 将修正作为示例反馈给Cursor

**操作：**
- 修复后用 `@fixed` 标记并说明原因
- 训练AI适应你的编码风格
- 建立持续改进的反馈循环

**案例：** AI生成的DeviceCmdController漏了@EnableEurekaClient注册，手动补全后提示："所有Controller都需要继承CheckAliveController，并添加统一的异常处理@ControllerAdvice"。

### 6. 注意力锚定：精准定位

**命令：**
- `@file` - 限定到特定文件
- `@folder` - 限定到特定文件夹
- `@git` - 对比分支差异

**场景应用：**
- 修复Bug时：`@file:micro-cloud-adapter/src/main/java/com/zhht/adapter/MqttMessageHandler.java` 锁定文件
- 重构时：`@micro-cprs/src/main/java/com/zhht/controller` 限定修改范围
- 版本对比：`@git#px_1.0_20250218` 避免误改

**好处：** 防止AI"走神"，避免修改无关代码

### 7. 设计文档管理

**方法：**
- 在 `.cursor/` 目录存放设计文档和检查清单
- 包含架构图、接口文档、开发规范
- 更新代码时同步更新文档

**文档结构：**
```
.cursor/
├── docs/
│   ├── microservices-architecture.md
│   ├── mqtt-integration-guide.md
│   └── deployment-checklist.md
└── rules/
    ├── microservices-architecture.mdc
    └── coding-patterns.mdc
```

**作用：** 确保AI有完整的上下文信息，知道下一步该做什么

### 8. 直接修改代码

**真相：** AI从你的编辑中学习的速度，比听解释快10倍！

**操作：**
- 发现错误直接重写
- 添加注释说明修改原因
- 让AI从你的编辑中学习

**案例：** AI生成的MQTT重连逻辑过于复杂，直接重写并注释："使用固定ClientId + cleanSession=false，让MQTT协议自动处理重连，无需复杂逻辑"。

### 9. 聊天历史利用

**技巧：**
- 使用 `/history` 调取历史对话
- 迭代和优化旧提示词
- 对高频问题保存为模板

**应用：**
- 复用成功的提示词模式
- 避免重复解释相同问题
- 建立个人提示词库

### 10. 智能模型选择

**推荐：**
- **高精度任务：** 使用Gemini
- **创意性任务：** 使用Claude 3.5  
- **通用编程任务：** 使用GPT-4

**任务类型详解：**

**高精度任务** - 需要精确计算、严格逻辑、零容错
- 算法实现和优化
- 数学计算和公式推导
- 性能分析和复杂度计算
- 数据结构设计
- 精确的参数配置

**创意性任务** - 需要创新思维、综合分析、多方案比较
- 系统架构设计和重构
- 复杂问题诊断和解决方案
- 技术选型和方案评估
- 业务逻辑抽象和建模
- 代码审查和优化建议

**通用编程任务** - 标准化、重复性、遵循既定模式
- CRUD操作和API开发
- 常见业务功能实现
- 标准组件和模板代码
- 配置文件和脚本编写
- 日常功能开发

**策略：** 根据任务特点选择最适合的模型，而非一概而论

### 11. 新技术学习

**操作：**
- 粘贴官方文档链接
- 让AI逐行解释错误
- 结合实际项目进行学习

**示例：** 
```
@https://spring.io/projects/spring-cloud 请解释Eureka服务发现的原理，
并结合当前项目的@EnableEurekaClient配置，提供完整的服务注册和发现解决方案
```

### 12. 大项目优化

**策略：**
- **过夜索引：** 提前做好全项目索引，提升响应速度
- **上下文裁剪：** 使用 `@micro-cloud-adapter` 限定AI仅关注MQTT适配器模块
- **资源管理：** 避免AI分析target/目录等构建文件浪费资源

**适用场景：**
- 微服务架构重构
- MQTT连接问题排查
- 跨服务Feign调用优化

## 实战技巧总结

### 提示词模板

```
技术栈：[Spring Boot 1.5.13 + Spring Cloud Edgware.SR4 + MyBatis]
任务：[实现MQTT设备管理功能]
约束：[使用RedisCacheTemplate缓存，实现Feign降级，包含完整异常处理]
文件范围：[@micro-cloud-adapter/src/main/java/com/zhht/controller]
测试要求：[包含JUnit单元测试，Mock Redis和MQTT客户端]
```

### 工作流程

1. **准备阶段：** 设定项目规则 + 准备测试用例
2. **生成阶段：** 精准提示 + 文件级迭代
3. **审查阶段：** 人工检查 + 直接修改
4. **优化阶段：** 利用历史 + 模型选择

### 注意事项

- ✅ 始终先写测试，后写实现
- ✅ 保持提示词的具体性和完整性
- ✅ 及时审查和修正AI输出
- ✅ 建立并维护项目规则文档
- ❌ 避免一次性生成大量文件
- ❌ 不要忽略AI输出的审查环节
- ❌ 不要在提示词中含糊其辞



