Android 开发中 Cursor AI 配置与实践技巧

使用方法： 在 Cursor 中新建文件时，通过 Ctrl+K 触发指令，输入： 参考项目规则文档（内容如下），生成 [具体功能，如登录界面的 Compose 代码]：[粘贴 project_rules.md 内容]

AI 会优先遵循文档中的规则生成代码，避免出现技术栈冲突（如突然生成 XML 布局）或风格混乱。

2. 自定义指令（Command）：快速复用规则

Cursor 支持将常用指令保存为'自定义指令'，避免重复输入规则。通过 Settings > Commands > Add Command 创建，调用时直接输入指令名称。

示例 1：生成 Compose 界面的指令

• 指令名称：生成 Compose 界面
• 使用：输入 生成 Compose 界面，再补充需求（如'登录界面，包含用户名输入框、密码输入框、登录按钮'），AI 会自动套用规则。

指令内容：

按照以下规则生成 Jetpack Compose 界面代码：
1. 技术栈：仅用 Compose 1.4.3，使用 Material3 组件；
2. 结构：函数名以 [Screen] 结尾（如 LoginScreen），参数仅包含 ViewModel 和导航回调；
3. 风格：使用 Column/Row 布局，添加适当 padding（8.dp 倍数），支持深色模式；
4. 关联：使用 core.theme.MyAppTheme，引用对应功能的字符串资源（如 R.string.login_title）。
需求：[用户输入的具体界面需求]

示例 2：生成 Repository 的指令

• 指令名称：生成 Repository

指令内容：

按照以下规则生成 Repository 实现类：
1. 技术栈：实现对应 Domain 层的 Repository 接口，使用 Hilt 的@Singleton 注解；
2. 依赖：通过构造函数注入 RemoteDataSource 和 LocalDataSource；
3. 逻辑：优先从本地获取数据，本地无则从网络请求，通过 Flow 返回结果；
4. 错误处理：使用 core.network.ApiException 处理网络错误，统一封装。
需求：[用户输入的具体 Repository 功能，如'用户信息 Repository，包含 getUserById 方法']

3. 上下文管理：让 AI'看到'项目已有代码

Cursor 的 AI 生成质量依赖于'上下文窗口'（即 AI 能获取的项目已有代码），上下文越完整，生成的代码关联性越强。

方法 1：上传项目文件到 Cursor

• 打开 Cursor 后，通过 File > Open Folder 导入整个 Android 项目；
• 生成代码前，通过 Ctrl+K 指令明确引用已有文件，例如： 参考 com.example.myapp.core.viewmodel.BaseViewModel 的代码，实现 LoginViewModel，包含登录逻辑和状态管理
• AI 会自动读取 BaseViewModel 的结构（如状态变量、事件处理方式），生成兼容的代码。

方法 2：嵌入代码片段到指令 若项目文件较多，可手动复制关键代码片段到指令中，让 AI 聚焦核心逻辑：

已知项目中 BaseViewModel 的代码如下：
class BaseViewModel : ViewModel() {
    protected val _loading = MutableStateFlow(false)
    val loading: StateFlow<Boolean> = _loading.asStateFlow()
    protected val _error = MutableStateFlow<String?>(null)
    val error: StateFlow<String?> = _error.asStateFlow()
    protected fun launchSafe(block: suspend () -> Unit) {
        viewModelScope.launch {
            _loading.value = true
            try {
                block()
            } catch (e: Exception) {
                _error.value = e.message
            } finally {
                _loading.value = false
            }
        }
    }
}
请基于此类，实现 LoginViewModel，包含 login(username: String, password: String) 方法，调用 LoginUseCase，更新状态。

4. 技术栈约束：精确到版本和替代方案

为避免 AI 使用过时或未指定的技术，需在规则中明确'允许/禁止'的库，并指定替代方案。

示例指令片段：

技术栈约束：
- 禁止使用：
  - 禁止用 AsyncTask（已过时），必须用 Coroutines 替代；
  - 禁止用 findViewById，必须用 Compose 的 remember 或 ViewBinding（若用 XML）；
  - 禁止用 Gson 手动解析 JSON，必须用 Retrofit 的 MoshiConverter；
- 强制版本：
  - Kotlin：1.8.22；
  - Jetpack Compose：1.4.3（禁止使用 1.5.0+ 的新 API，避免兼容问题）；
  - Hilt：2.44（必须使用@HiltViewModel 注解 ViewModel）。

5. 代码风格统一：通过'示例 + 规则'双重约束

AI 对'示例'的理解优于抽象规则，可在指令中嵌入一段符合风格的代码作为'模板'，让 AI 模仿。

示例：约束 Kotlin 函数风格

代码风格要求：
- 函数参数过多时，使用换行和缩进；
- 优先使用命名参数调用函数；
- 复杂逻辑拆分到私有函数，主函数保持简洁。
示例（正确风格）：
private fun showLoginDialog(
    onConfirm: (username: String, password: String) -> Unit,
    onCancel: () -> Unit
) {
    AlertDialog(
        title = { Text(text = stringResource(R.string.login_title)) },
        text = { LoginInputContent() },
        confirmButton = {
            Button(onClick = {
                val (user, pwd) = getInputValues()
                onConfirm(user, pwd)
            }) {
                Text(text = stringResource(R.string.confirm))
            }
        },
        dismissButton = {
            Button(onClick = onCancel) {
                Text(text = stringResource(R.string.cancel))
            }
        }
    ).show()
}
请按照此风格，实现注册对话框的 Compose 函数。

6. 项目结构固定：强制文件路径和命名

通过规则明确'什么功能的代码必须放在什么位置'，避免 AI 生成的文件'乱放'。

示例指令片段：

项目结构规则：
- 所有 Compose 界面文件必须放在：[模块]/src/main/java/com/example/myapp/[feature]/ui/compose/，文件名以 [功能]Screen.kt 结尾（如 LoginScreen.kt）；
- ViewModel 必须放在：[模块]/src/main/java/com/example/myapp/[feature]/ui/viewmodel/，类名以 [功能]ViewModel.kt 结尾，且添加@HiltViewModel 注解；
- API 接口（Retrofit）必须放在：[模块]/src/main/java/com/example/myapp/[feature]/data/remote/service/，类名以 [功能]Service.kt 结尾，使用@GET/@POST 注解；
- 字符串资源必须按功能拆分到 res/values/strings_[feature].xml（如 strings_login.xml），键名格式：[feature]_[功能]（如 login_username_hint）。
请生成登录功能的 API 接口，遵循上述路径和命名规则。

三、高级技巧：迭代优化规则

1. 从'宽松'到'严格'逐步收紧 初期可只定义核心规则（如技术栈和大致结构），生成代码后发现问题（如命名不统一），再补充细化规则（如'变量名必须包含业务含义，禁止用 tmp、data1 等'）。
2. 保存'失败案例'，反推规则 若 AI 生成不符合预期的代码（如误用 XML 布局），记录案例并在规则中明确禁止：错误案例：之前生成了 activity_login.xml，禁止使用 XML，必须用 Compose 的 LoginScreen.kt。
3. 结合 Cursor 的'编辑建议'功能 生成代码后，选中代码块，用 Ctrl+K 指令：检查这段代码是否符合项目规则（[粘贴规则]），并修复不符合的地方，AI 会自动修正风格或技术栈问题。

四、注意事项

1. 规则不宜过度冗余：只定义核心约束（技术栈、结构、关键风格），避免限制过细（如'每行必须有一个空格'），否则 AI 可能因规则冲突生成错误代码。
2. 适配项目迭代：当项目技术栈升级（如 Compose 从 1.4.3 升到 1.5.0）或结构调整时，及时更新 project_rules.md，避免 AI 使用旧规则。
3. 验证兼容性：AI 可能生成'符合规则但存在版本兼容问题'的代码（如使用 Compose 1.5.0 的 API 但项目用 1.4.3），需结合 Android Studio 的 Lint 检查验证。

总结

通过预设项目规则模板、自定义指令、管理上下文和迭代优化，可让 Cursor 的 AI 生成代码高度贴合项目需求。核心是'让 AI 明确边界'——知道该用什么技术、遵循什么风格、放在什么位置，从而从'生成可用代码'提升到'生成可直接集成的代码'，大幅减少后期修改成本。