Cursor高阶玩法：.cursorrules编写与Spec-Driven开发实战，把AI调教成专属结对编程搭档

Cursor高阶玩法：.cursorrules编写与Spec-Driven开发实战，把AI调教成专属结对编程搭档

90%的开发者只用到了Cursor 20%的能力，本文手把手教你解锁剩余80%

一、引言：为什么你的Cursor还不如别人的Copilot？

最近在读者群里看到一个很有意思的吐槽："都说Cursor强，我用了两周，感觉和Copilot也没什么区别啊，就多了个对话框而已。"

这条吐槽下面跟了几十条回复，点赞最高的评论一针见血："你怕是只用了Cursor 20%的功能。"

这个场景太熟悉了。很多人跟风装上了Cursor，但使用方式还停留在"按Tab补全 + Ctrl+K聊天"，体验和Copilot拉不开差距，甚至因为习惯了JetBrains的键位，反而觉得"也就那样"。

但真实情况是：Cursor的强大藏在配置层和交互模式里 。不配置.cursorrules、不用@-mention、不玩Composer/Agent模式，等于只用了Cursor 20%的能力。

那么问题来了------剩余的80%到底是什么？怎么用？

先给结论：Cursor的本质不是"更好的Copilot"，而是一个"可编程的AI开发环境"。 它的核心设计理念是：把项目的上下文（规则、约束、架构）显式地告诉AI，让AI在正确的边界内生成代码。

用好Cursor，就三件事：

1. 写好规则（.cursorrules） ------ 让AI懂你的项目规范
2. 说好上下文（@-mention） ------ 让AI精准理解你的意图
3. 玩转工作流（Composer/Agent） ------ 让AI帮你批量干活

本文会逐一拆解这三件事，并附上一套可直接复用的Android/Kotlin项目.cursorrules完整模板 和一个从需求到上线的Spec-Driven完整工作流演示。

读完这篇，你会把Cursor从"代码补全工具"升级为"真正理解你项目架构的结对编程搭档"。

二、.cursorrules：项目的"AI宪法"

2.1 什么是.cursorrules？为什么它如此重要？

通俗理解：.cursorrules是Cursor的**"项目级System Prompt"**。

每次AI生成代码或回答问题时，Cursor都会自动加载这个文件作为底层约束。它就像是给AI立了一部"宪法"------所有生成的内容都不能违背这部宪法。

不配置它 ：AI按通用互联网代码风格生成，可能完全不符合你的技术栈和编码规范。比如你的项目用的是Kotlin协程，它可能给你生成Thread.sleep()；你用的是Compose，它可能给你生成XML布局。

配置它 ：AI生成的代码天然遵循你的命名规范、架构模式、安全红线。你不需要每次对话都重复一遍"请使用Kotlin协程"、"请遵循MVI架构"------这些都已经写在规则文件里了。

关键认知 ：.cursorrules是投入产出比最高的配置，花30分钟写好，收益会贯穿整个项目的生命周期。

2.2 .cursorrules 文件结构解析

文件位置 ：项目根目录下创建 .cursorrules 文件（纯文本，可被Git追踪，团队共享）

核心组成模块：

模块	作用	示例内容
技术栈声明	告诉AI项目用的语言、框架、版本	"Kotlin 1.9.20 + Jetpack Compose + Room + Hilt"
编码规范	命名风格、代码格式、禁止项	"禁止使用!!操作符，统一使用?.或requireNotNull()"
架构约束	分层结构、依赖方向、设计模式	"严格遵循MVI模式，UI层不包含业务逻辑"
常用库/API	AI优先推荐的项目内部工具类或封装	"网络请求统一使用NetworkClient.request()"
安全红线	绝对禁止AI生成或建议的代码模式	"日志中禁止打印Token/密码等敏感信息"

2.3 Android/Kotlin 项目可复用的 .cursorrules 模板

下面这份模板可直接复制到你的Android项目根目录使用：

markdown

# Android/Kotlin 项目 Cursor Rules
# 适用于 Jetpack Compose + MVI + Hilt 架构

## 技术栈
- 语言：Kotlin 1.9.20
- UI框架：Jetpack Compose (Material 3)
- 架构模式：MVI (Model-View-Intent)
- 依赖注入：Hilt (Dagger Hilt)
- 数据库：Room
- 网络：Retrofit + OkHttp + Moshi
- 异步：Kotlin Coroutines + Flow
- 日志：Timber

## 命名规范
- 页面/Composable：XxxScreen
- ViewModel：XxxViewModel
- Repository：XxxRepository
- 数据类：XxxUiState / XxxData
- 密封类：XxxEvent / XxxEffect
- 接口：IXxxService (以 I 开头)
- 常量：全部大写，下划线分隔

## 编码约束（硬规则）
- 禁止使用 `!!` 操作符，统一使用 `?.` + `?:` 或 `requireNotNull()`
- 所有 Composable 函数必须有 `@Composable` 注解
- 状态提升原则：State 向下传递，Event 向上传递
- 协程作用域：使用 `viewModelScope` 或 `lifecycleScope`，禁止使用 `GlobalScope`
- Flow 收集：使用 `repeatOnLifecycle` 或 `collectAsStateWithLifecycle`
- 日志：统一使用 `Timber.d/e/i/w`，禁止直接使用 `Log.d()`
- 数据类：必须使用 `data class`，并启用 `@Parcelize`（如需要）
- 异常处理：Repository层捕获并转换为密封类结果返回

## 安全红线（AI 绝对禁止生成）
- 禁止在日志中打印 Token、密码、手机号、身份证等敏感信息
- 禁止将敏感信息硬编码在代码中（必须通过 BuildConfig 或配置文件注入）
- 禁止在 SharedPreferences 中存储明文敏感数据
- 禁止生成含有 `System.out.println()` 的代码

## 常用库推荐（AI 优先使用）
- 图片加载：Coil (优先) / Glide
- 序列化：Moshi (优先) / Gson
- 网络请求：统一使用 Retrofit 服务接口，禁止直接调用 OkHttp
- 权限请求：Accompanist Permission (优先)
- 导航：Navigation Compose

2.4 模板使用说明与团队共享建议

使用步骤：

1. 在项目根目录新建 .cursorrules 文件
2. 复制上述模板内容
3. 根据项目实际情况调整（如删除未使用的库、修改命名前缀）
4. 重启Cursor或重新加载窗口（Cmd+Shift+P -> Reload Window）

团队共享建议：

• 将 .cursorrules 提交到Git仓库，团队成员自动同步
• 建议每季度Review和更新一次（如引入新库、架构升级时）
• 不同项目可以有独立的Rules（后端/Android/前端各不相同）
• 新人入职时，阅读 .cursorrules 就能快速了解项目的技术栈和编码规范------它本身就是一份"代码化的开发规范文档"

三、@-mention：精准投喂上下文，让AI真正"懂你"

3.1 @-mention 是什么？

在Cursor的Chat（Cmd+I）或Composer（Cmd+Shift+I）中，输入@可以引用项目中的特定资源作为上下文。

这是Cursor区别于Copilot的核心能力之一：你不是在问一个通用AI，而是在问一个"已经看过你项目文件"的AI。

Copilot的上下文主要依赖当前打开的文件和部分语义索引，而Cursor的@-mention让你可以手动、精确地告诉AI"看这个文件、理解这个模块、参考这个设计"。

3.2 支持的引用类型与最佳场景

引用类型	语法示例	最佳使用场景
文件	@UserRepository.kt	针对特定文件提问或修改
文件夹	@/src/main/java/com/xxx/ui	批量理解某个模块的所有文件
代码块	选中代码后 Cmd+Shift+L	针对选中代码进行重构/解释
文档	@docs/API_DESIGN.md	让AI按设计文档生成代码
Web	@https://developer.android.com/...	让AI参考最新官方文档
Git提交	@git diff / @git commit	分析本次改动或历史提交

3.3 实战组合拳：多@引用协同

示例场景：

"帮我新增一个 UserProfileScreen，UI风格参考 @ProfileCard.kt，数据从 @UserRepository.kt 获取，设计规范见 @docs/UI_GUIDELINE.md"

一次对话引用了3个资源：

• 1个参考UI文件（ProfileCard.kt）→ 风格保持一致
• 1个数据源文件（UserRepository.kt）→ API调用方式正确
• 1份设计文档（UI_GUIDELINE.md）→ 字体、颜色、间距符合规范

效果 ：AI生成的代码同时满足UI风格、数据来源、设计规范三重约束，编译通过率极高，几乎不需要二次调整。

3.4 高级技巧：创建"上下文预设"

如果你经常做同一类任务（如"新增一个列表页"、"新增一个表单页"），可以提前整理好每次都需要引用的文件清单：

列表页上下文预设（保存为备忘录）：

text

@BaseListScreen.kt @BaseViewModel.kt @BaseRepository.kt @docs/API_LIST.md

每次新建列表页时，直接粘贴这串@引用，再输入具体需求即可。省去了每次手动找文件的繁琐操作。

四、Composer/Agent模式：从"对话"到"执行"的质变

4.1 Composer是什么？和普通Chat有什么区别？

普通Chat只负责"回答问题"和"生成代码文本"，而Composer直接"动手改代码"。

维度	普通Chat	Composer模式
输出方式	只输出代码文本，需手动复制粘贴	直接写入文件，可批量修改多个文件
上下文范围	当前对话窗口	可跨文件、跨目录理解项目结构
操作粒度	生成新代码为主	新增 + 修改 + 删除 + 重构，全操作覆盖
确认机制	生成后人工检查	支持逐文件Diff预览，确认后才写入
适用场景	简单问答、单文件生成	复杂重构、多文件联动、架构调整

一句话总结：Chat是"我问你答"，Composer是"我描述需求，你直接动手干"。

4.2 Composer实战演示：完整工作流

场景 ：把现有的MainActivity（臃肿的Fragment容器，代码超过800行）重构为MVI架构，拆解为：

• MainScreen.kt（Compose UI）
• MainViewModel.kt（业务逻辑）
• MainUiState.kt（状态定义）
• MainEvent.kt（事件定义）

Step 1：打开Composer，描述需求

• 快捷键：Cmd+Shift+I
• Prompt："我要重构MainActivity，目前它是Fragment容器，代码非常臃肿。请帮我改为MVI架构，使用Compose实现UI。拆分出MainScreen、MainViewModel、MainUiState、MainEvent四个文件。UI风格参考@/ui/common/BaseScreen.kt，数据管理参考@UserRepository.kt。"

Step 2：Cursor自动分析，生成改动方案

• Cursor会自动识别涉及的依赖关系，列出需要新建和修改的文件清单：
  • ✅ 新建 MainUiState.kt
  • ✅ 新建 MainEvent.kt
  • ✅ 新建 MainViewModel.kt
  • ✅ 新建 MainScreen.kt
  • ✅ 修改 MainActivity.kt（改为Compose + 注入ViewModel）
  • ⚠️ 识别出3个已废弃的旧Fragment，建议清理

Step 3：逐文件Diff审查

• Cursor会展示每个文件的改动对比（新增/修改/删除高亮）
• 逐个文件确认，重点关注：
  • 删除部分：AI是否误删了重要逻辑
  • 依赖注入：Hilt的注入是否正确
  • State定义：是否包含了所有UI状态

Step 4：确认无误后Apply All，编译验证

• 如果编译报错，直接告诉Cursor："编译报错：xxx，帮我修复"
• Cursor会自动读取报错信息，修正问题

Step 5：提交代码

• 确认所有功能正常后，提交Git

4.3 Composer使用铁律（血泪教训）

基于我和Cursor长达半年的"相爱相杀"，总结出三条铁律：

1. 改前必须提交Git或备份 。虽然Composer支持回滚，但以防万一，提交一份保险永远没错。特别是涉及删除操作时，绝对要先提交。
2. 逐文件Review Diff，不要无脑点Apply All 。AI有时会误删你觉得"没用"但实际关键的代码（比如初始化逻辑、埋点代码）。关注删除的每一行，而不是新增的。
3. 大型改动分步执行 。不要一次性让AI改动超过10个文件------改动越多，出错面越大，排错越困难。建议每次3-5个文件，改完验证通过后再继续下一批。

五、Spec-Driven开发：让AI先写文档，再写代码

5.1 什么是Spec-Driven Development？

核心理念 ：先让AI生成技术规格文档（Spec），人工确认架构方向后，再让AI基于Spec生成代码。

很多开发者用AI的方式是：提需求 → AI直接写代码 → 方向偏了 → 推翻重来。来回折腾几次，效率反而不如自己写。

传统模式的死循环：

text

需求模糊 → AI写代码 → 偏差 → 返工 → 再提需求 → 再偏差 → 再返工

Spec-Driven模式的正循环：

text

需求 → AI写Spec → 人工Review确认 → AI基于Spec写代码 → 一次成型

关键在于：在"文档阶段"把方向对齐，而不是在"代码阶段"推倒重来。

5.2 完整工作流演示

场景：新增一个用户个人资料页，需求如下：

• 展示用户头像、昵称、个性签名
• 支持修改昵称和签名
• 修改后点击保存调用API更新
• 保存过程中显示Loading状态
• 成功或失败给出Toast提示

第一轮对话（生成Spec） ：

Prompt："我要新增一个用户个人资料页，需求如上。请先不要写代码，帮我输出一份技术设计Spec，包含：功能列表、UI结构、数据流（MVI）、API接口定义、状态管理方案、错误处理方案。"

AI输出Spec预览（约500字）：

text

# 用户个人资料页 - 技术设计Spec

## 1. 功能清单
- 展示用户头像（从网络加载）
- 展示用户昵称（可编辑）
- 展示用户个性签名（可编辑）
- 点击保存按钮提交修改
- 保存中显示Loading状态
- 保存成功/失败Toast提示

## 2. UI结构（Compose）
Column {
    AsyncImage(url = avatarUrl) // 头像
    TextField(value = nickname, onValueChange) // 昵称输入
    TextField(value = signature, onValueChange) // 签名输入
    Button(onClick = saveProfile) // 保存按钮
}

## 3. MVI数据流
- UiState: UserProfileUiState (Loading / Success(data) / Error(message))
- Event: UpdateNickname(nickname) / UpdateSignature(signature) / SaveProfile
- Effect: ShowToast(message) / NavigateBack

## 4. API接口
- 获取: GET /api/user/profile -> UserProfileResponse
- 更新: POST /api/user/profile -> UpdateProfileRequest

## 5. 错误处理
- 网络异常 -> UiState.Error("网络异常，请稍后重试")
- 昵称为空 -> 前端校验，Toast提示"昵称不能为空"
- 保存失败 -> UiState.Error(具体错误信息)

人工Review确认：

• 检查架构方向是否合理 ✅
• 调整API字段命名（userAvatar → avatarUrl）✅
• 增加"昵称不能为空"的前端校验 ✅
• 确认无误后，进入第二轮

第二轮对话（基于Spec生成代码） ：

Prompt："请按照上面的Spec，生成完整的代码实现：UserProfileScreen.kt、UserProfileViewModel.kt、UserProfileUiState.kt、UserProfileEvent.kt、UserProfileEffect.kt。"

效果 ：AI严格按照已确认的Spec生成代码，方向偏差大幅降低，5个文件的命名、状态定义、API调用完全一致，零冲突。

5.3 Spec-Driven的优势总结

优势	说明
减少返工	方向在"文档阶段"对齐，不在"代码阶段"推倒重来
代码一致性	多个文件遵循统一的状态定义和命名规范，无冲突
可追溯性	Spec本身就是技术设计文档，可直接归档供团队Review
降低认知负担	开发者只需要Review Spec，不需要在代码阶段边写边想架构
新人友好	新人可以通过Spec快速理解模块的设计思路

六、Cursor高频踩坑与避坑指南

以下是我在实际使用中踩过的真实坑位：

坑点	表现	解决方案
索引未完成就开干	回答时遗漏关键文件，生成质量差，甚至忽略最新的代码改动	查看底部状态栏，确认索引100%后再提问。大型项目首次索引可能需要5-10分钟
.cursorrules 太啰嗦	AI过载，生成变慢，甚至忽略部分规则	保持精炼，每条规则一句话，不超过30条。把最重要（安全红线、核心架构）的放在最前面
Composer一次性改太多文件	编译报错一堆，难以定位问题根源	分批次执行，每次3-5个文件，改完编译通过后再继续下一批
过度信任Composer的Diff	Apply后才发现误删了重要代码	改前先提交Git；逐文件Diff时重点看删除了什么，而不是新增了什么
网络波动时强行使用Composer	Composer超时、上下文丢失、回答断断续续	网络不稳定时切回普通Chat模式单文件处理，或暂停使用
忘记@引用关键文件	AI生成的代码风格不一致，或调用不存在的API	提问前先想清楚："AI需要看哪些文件才能正确回答？"然后把它们都@进来

七、结语：Cursor是"画布"，规则是"画笔"

回到本专栏的核心命题------AI编程的本质是人机协同。

Cursor是目前最接近"结对编程搭档"形态的工具，但它不会自动变强。它的强大程度，取决于你给它定义的规则和输入的上下文。

• .cursorrules 是你"意图"的显式表达------告诉AI"我的项目长什么样"
• @-mention 是你"意图"的精准传递------告诉AI"我要改的是哪个部分"
• Composer是你"意图"的高效执行------告诉AI"按这个方向批量干"

关键认知 ：用好Cursor，核心不是"问问题的能力"，而是 "定义规则的能力" 。花时间写好一份.cursorrules，收益会贯穿整个项目的生命周期------无论是你自己还是团队其他成员，每次使用Cursor时都会受益。

今天就去项目根目录创建一个.cursorrules文件，把上面的模板填进去，感受一下AI突然"更懂你"的体验。

下篇预告 ：下一期进入避坑系列------《AI工具避坑指南：我在Cursor、Copilot、通义灵码上踩过的10个坑》，全是血泪教训，帮你提前避开我踩过的所有雷。

📎 附：本篇文章配套资源

资源1：可复用的 .cursorrules 完整模板

（见上文第2.3节，可直接复制使用）

资源2：Spec-Driven Prompt模板（可直接复用）

新增页面通用模板：

text

我要新增一个[功能名]页面，需求如下：
[粘贴需求]

请先不要写代码，帮我输出一份技术设计Spec，包含：
1. 功能清单
2. UI结构（用伪代码描述布局）
3. MVI数据流（UiState / Event / Effect定义）
4. API接口定义（请求/响应格式）
5. 错误处理方案

确认Spec后我再让你生成代码。

代码重构通用模板：

text

我要重构[模块名]，目前的问题是[描述痛点]。
目标架构：[如MVI / Clean Architecture]

请帮我做两件事：
1. 先输出一份重构方案Spec，列出需要新建和修改的文件清单
2. 确认方案后，分批次帮我执行代码改动

资源3：Cursor常用快捷键速查表

操作	快捷键
打开Chat（对话）	Cmd + I
打开Composer（多文件编辑）	Cmd + Shift + I
行内编辑（选中代码后）	Cmd + K
将选中代码加入上下文	Cmd + Shift + L
采纳补全建议	Tab
拒绝补全建议	Esc

---

📌 互动时间

你已经在用Cursor了吗？有没有自己写的.cursorrules配置想分享？或者在使用中遇到了什么奇葩问题？

欢迎在评论区交流