iOS开发AI助手规则集：提升Swift代码质量与工程效率

1. 项目概述：为Swift/iOS开发者量身定制的Cursor规则集

如果你是一名iOS开发者，并且正在使用Cursor这款AI编程助手，那么你很可能经历过这样的时刻：你向它描述一个需求，比如“帮我创建一个遵循MVVM模式的用户列表视图”，结果它生成的代码虽然能用，但在命名规范、架构分层或者内存管理上，总感觉差了那么点“iOS味儿”，不是你团队或你个人习惯的风格。或者，在涉及到测试、发布流程等更复杂的工程化问题时，你需要反复解释背景和约束，沟通成本很高。这正是ios-cursor-rules这个项目要解决的核心痛点。

简单来说，ios-cursor-rules是开发者Bruno Gama整理并开源的一套针对Swift和iOS开发的、高度定制化的Cursor规则（.mdc文件）集合。它不是一个独立的工具或框架，而是作用于Cursor AI的“上下文指令集”。你可以把它理解为给Cursor这位“实习生”配备的一本详尽的《iOS开发内部工作手册》。这本手册里写满了你们团队的编码规范、架构偏好、测试策略、发布流程等等。当Cursor在处理你的Swift代码时，它会自动参考这本手册，从而生成更符合Swift最佳实践、更贴近你项目实际需求的代码和建议，极大地提升“人机协作”的效率和代码质量。

这套规则覆盖了从日常编码、测试、架构设计到项目管理和发布的全流程。无论你是想确保Swift API设计指南被严格遵守，还是想推行Clean Architecture，或是统一团队的Commit信息格式，都能在这里找到对应的规则。它的价值在于将个人或团队的隐性知识（Tacit Knowledge）——那些存在于老手脑子里、文档里可能没写的经验和偏好——显性化、标准化，并注入到AI助手中，让AI的输出从一开始就站在一个更高的、更专业的起点上。

2. 核心规则集深度解析与设计理念

这套规则集的组织结构非常清晰，基本遵循了一个功能完整的iOS应用项目的生命周期和关注点分离原则。理解每个规则文件的设计意图，能帮助你更好地决定如何引入和适配到自己的项目中。

2.1 编码与架构基石：with-swift.mdc与with-ios.mdc

这是最基础也是最重要的两个规则文件，它们定义了语言和平台层面的“宪法”。

with-swift.mdc聚焦于Swift语言本身。它不仅仅检查语法，更重要的是贯彻Swift API设计指南的精神。例如，它会强调使用“清晰优于简洁”的命名原则，鼓励多使用值类型（struct,enum），正确使用guard语句进行提前返回，以及采用Result类型或async/await进行现代化的错误处理和并发编程。它还会关注内存管理，比如确保在闭包中正确使用[weak self]或[unowned self]来避免循环引用。这个规则的目标是让生成的代码看起来就像出自一个经验丰富的Swift开发者之手，充满地道的“Swift味”。

注意：仅仅启用这个规则，AI可能会写出非常“教科书式”的Swift代码。对于iOS开发来说，这还不够，因为很多平台特有的模式和陷阱它可能覆盖不到。

with-ios.mdc则在此基础上，添加了iOS平台的上下文。这是区分一个通用Swift程序员和iOS专家的关键。它会引导AI在以下方面做出更合理的决策：

• 框架选择：何时使用UIKit（需要精细控制、支持更低版本），何时转向SwiftUI（声明式UI、更快迭代）。规则会包含一些启发式判断，比如“如果项目最低支持iOS 13，且UI交互逻辑不复杂，优先考虑SwiftUI组件”。
• 生命周期感知：确保代码正确处理viewDidLoad,viewWillAppear等生命周期事件，以及在SceneDelegate和AppDelegate中的恰当操作。
• 平台特性：处理设备旋转、深色模式适配、动态字体、后台任务执行（BackgroundTasks）、状态恢复等。例如，它会提醒AI在保存用户状态时使用UserDefaults或钥匙串，并考虑数据安全。
• 内存警告：在适当的地方添加didReceiveMemoryWarning的处理逻辑，或指导使用缓存策略。

设计理念：这两个规则是分层递进的。with-swift.mdc确保代码在语言层面是健壮和优雅的；with-ios.mdc则确保这些代码在iOS生态中能正确、高效地运行。在实际使用中，它们通常需要同时启用。

2.2 高级架构模式：with-ddd-swift.mdc与clean-architecture-swift.mdc

当项目从简单的单页面应用成长为复杂业务系统时，这两个规则的价值就凸显出来了。它们不是互斥的，而是可以从不同维度指导架构设计。

with-ddd-swift.mdc（领域驱动设计）的核心是统一语言和聚焦业务逻辑。它指导AI如何用Swift代码来建模复杂的业务领域。例如：

• 实体与值对象：它会区分哪些模型应该是class（实体，有唯一标识和生命周期），哪些应该是struct（值对象，通过属性值相等）。比如，User可能是一个实体（有ID），而Money（包含金额和货币）就是一个典型的值对象。
• 聚合根：指导AI识别聚合根，并确保所有对聚合内对象的修改都通过聚合根进行，保持业务不变量的完整性。
• 领域事件：建议使用一个轻量级的领域事件系统（如NotificationCenter的定制使用或更专门的EventBus）来解耦领域状态变化触发的后续操作。

clean-architecture-swift.mdc（整洁架构）的核心是依赖关系和可测试性。它强制实行依赖规则：内层（领域层）不依赖任何外层（接口层、基础设施层）。它会引导AI：

• 定义协议：为数据库访问、网络请求、用户界面等定义清晰的协议（protocol）。
• 依赖注入：使用构造器注入或属性注入，将具体的实现（如AlamofireNetworkService）传递给业务逻辑类，而不是让业务逻辑类直接实例化它们。
• 用例：将每个具体的用户操作（如“登录用户”、“创建订单”）封装成独立的UseCase类，这些类只包含业务规则和协调流程。

实操心得：在实际项目中，我常常结合使用。用DDD来分析和建模核心业务领域，划分限界上下文；然后用Clean Architecture来组织每个限界上下文内部的代码结构，确保其独立性和可测试性。你可以让AI先根据DDD规则分析需求并生成领域模型，再根据Clean Architecture规则去实现具体的用例和接口适配器。

2.3 质量保障体系：测试相关规则

create-tests-swift.mdc和swift-testing-policy.mdc共同构成了项目的自动化测试规范。前者是“战术手册”，后者是“战略方针”。

create-tests-swift.mdc提供了具体的测试编写模板和最佳实践。例如：

• 它会为ViewModel生成包含XCTest的单元测试，并自动模拟（mock）掉Repository或Service。
• 对于SwiftUI视图，它可能更倾向于生成基于视图状态的快照测试（Snapshot Testing）或使用XCTest的UI测试框架来测试交互逻辑，而非直接测试View结构体。
• 它包含异步测试的现代写法（async/await），以及如何使用XCTestExpectation处理更复杂的异步回调。
• 它会建议合理的测试数据构造方式，比如使用工厂方法或测试构建器（Test Builder）来避免测试代码重复。

swift-testing-policy.mdc则从项目管理的角度设定标准。比如：

• 覆盖率要求：可能规定核心业务逻辑的单元测试覆盖率必须达到80%以上，UI测试覆盖关键用户流程。
• 命名规范：测试类名应为被测类名+Tests，测试方法名应遵循test_When[条件]_Should[预期结果]的模式，极大提升测试报告的可读性。
• 组织方式：规定测试目标（Test Target）如何与主工程模块对应，资源文件如何管理。

常见问题：AI有时会生成过于庞大或琐碎的测试。一个技巧是在规则中强调“测试行为，而非实现”。即，让AI专注于测试公开的API和预期的业务输出，而不是去测试每个私有方法或内部状态的变化，这样测试会更稳定，重构代码时也不易被破坏。

2.4 工程与协作流程：发布、提交与重构规则

这部分规则将开发工作流标准化，特别适合团队协作。

create-ios-release.mdc和create-release.mdc是发布工程师的利器。它们不仅包含技术步骤（代码签名、构建归档），还集成了Fastlane自动化脚本。规则会指导AI如何编写或调用Fastfile中的lane，来自动化完成增加构建号、打标签、上传到TestFlight或App Store Connect、生成截屏、提交审核等一系列繁琐操作。它还会考虑管理证书和描述文件的最佳实践，比如使用match进行同步。

create-commit-message.mdc推行约定式提交。它会强制AI在生成Commit信息时，使用feat:、fix:、docs:、chore:、refactor:等类型前缀，并关联Jira或GitHub的Issue编号。这带来的好处是：自动化生成语义化的版本号（通过semantic-release等工具）、自动生成美观的变更日志（CHANGELOG）、让代码历史清晰可查。

main-refactoring-rules.mdc和finalize.mdc作用于开发周期的末尾。前者像一个经验丰富的代码审查员，能识别出“过大的类”、“过长的方法”、“重复代码”等坏味道，并建议具体的重构策略，如提取方法、提炼类、用多态替换条件表达式等。后者则是在功能开发完成后，进行“收尾检查”，包括删除调试打印语句、移除未使用的import、补充遗漏的文档注释（DocC）、检查是否有循环引用等，确保代码在提交前是整洁的。

3. 规则集的部署与集成实战

了解了规则是什么，下一步就是如何将它们用起来。官方提供了快速安装脚本，但对于企业级或深度定制，手动集成和配置是更可靠的方式。

3.1 安装与环境配置

最快捷的方式是使用项目提供的安装脚本。在你的终端中执行以下命令：

curl -o- https://raw.githubusercontent.com/brunogama/ios-cursor-rules/main/install.sh | bash

这个脚本通常会做以下几件事：

1. 将仓库克隆到本地一个标准目录（如~/.cursor/rules）。
2. 将所有的.mdc规则文件链接或复制到 Cursor 的规则目录下。
3. 可能会尝试在 Cursor 设置中注册这些规则路径。

如果你希望更可控，或者网络环境受限，可以采用手动安装：

# 1. 克隆仓库到本地你喜欢的任何位置 git clone https://github.com/brunogama/ios-cursor-rules.git cd ios-cursor-rules # 2. 关键步骤：将规则文件链接或复制到 Cursor 的规则目录 # Cursor的规则目录通常位于： # - macOS: ~/Library/Application Support/Cursor/User/globalStorage/continue.rules # - Windows: %APPDATA%\Cursor\User\globalStorage\continue.rules # - Linux: ~/.config/Cursor/User/globalStorage/continue.rules # 例如，在macOS上创建符号链接（推荐，便于更新）： ln -s $(pwd)/*.mdc ~/Library/Application\ Support/Cursor/User/globalStorage/continue.rules/ # 或者直接复制： cp *.mdc ~/Library/Application\ Support/Cursor/User/globalStorage/continue.rules/

重要提示：安装后，你需要重启 Cursor 以使新规则生效。然后，你可以在 Cursor 的设置中（通常是Settings -> Rules）看到并管理这些规则，可以选择全局启用，或按工作区（Workspace）启用。

3.2 规则的选择性启用与优先级管理

你很可能不需要一次性启用所有规则。盲目全部启用可能会导致规则冲突或AI响应迟缓。正确的做法是根据项目阶段和当前任务进行动态组合。

1. 基础开发组合：在编写日常业务代码时，启用with-swift.mdc+with-ios.mdc+main-refactoring-rules.mdc。这保证了代码质量和平台规范性。
2. 架构设计阶段：当在规划新模块或重构旧代码时，启用with-ddd-swift.mdc和/或clean-architecture-swift.mdc，让AI帮助进行领域建模和分层设计。
3. 测试驱动开发：在编写功能前或之后，启用create-tests-swift.mdc和swift-testing-policy.mdc，快速生成测试骨架。
4. 发布准备：在需要打包发布时，启用create-ios-release.mdc，让AI帮你检查发布清单或生成Fastlane脚本。

Cursor 允许你为规则设置优先级。通常，更具体的规则应该比通用规则有更高的优先级。例如，clean-architecture-swift.mdc中关于“依赖注入”的指令，应该覆盖掉可能存在的更泛泛的“创建类”的指令。你可以在规则文件内部通过注释或特定的语法（如果Cursor支持）来设置，或者在Cursor的规则管理界面进行调整。

3.3 个性化定制：打造你自己的规则

开源规则集是一个绝佳的起点，但每个团队都有自己的特殊约定和技术栈。定制化是发挥其最大威力的关键。

如何定制：

1. Fork 仓库：首先 Forkbrunogama/ios-cursor-rules到自己的GitHub账户下。
2. 按需修改：直接编辑.mdc文件。这些文件本质上是文本文件，包含了给AI的指令。例如，如果你的团队强制使用Combine进行响应式编程，你可以在with-ios.mdc中添加：“当处理异步数据流时，优先考虑使用Combine框架的Publisher和Subscriber，而不是嵌套的回调或NotificationCenter。”
3. 添加新规则：你可以模仿现有规则的结构，创建全新的.mdc文件。比如，如果你的项目使用了GraphQL（通过 Apollo iOS），你可以创建一个with-graphql-ios.mdc，里面包含生成GraphQL查询代码、处理响应模型、配置Apollo Client的最佳实践。
4. 集成内部工具：在create-ios-release.mdc中，将通用的Fastlane命令替换成你们公司内部CI/CD系统的具体API调用或脚本路径。

一个定制化示例：假设你的团队规定所有网络请求层必须使用一个内部封装的NetworkKit，并且错误类型必须统一为AppError枚举。你可以在with-ios.mdc或新建的internal-networking.mdc中这样写：

## 网络层规范 - 所有远程数据请求必须通过 `NetworkKit.shared` 的单例实例发起。 - 禁止直接使用 `URLSession` 或第三方库如 `Alamofire` 进行网络调用。 - 请求方法必须包裹在 `NetworkKit.shared.request(_:completion:)` 中。 - 所有可能的错误都必须映射到 `AppError` 枚举的相应 case。例如，HTTP 404 错误应映射为 `AppError.resourceNotFound`。 - 生成的模型必须实现 `Codable` 协议，并且解码时应使用 `NetworkKit` 提供的 `decode` 方法，该方法内置了统一的日期解码策略。

这样，当你让AI“获取用户列表”时，它生成的代码就会自动符合你们内部的标准，而不是一个通用的URLSession示例。

4. 实战场景：从需求到代码的AI协作全流程

让我们通过一个具体的场景，看看这些规则如何串联起来工作。假设我们有一个需求：“在用户个人资料页面，添加一个编辑用户名和头像的功能，数据需要保存到后端，并更新本地缓存。”

第1步：规划与设计（启用prepare.mdc和propose.mdc）你可以在Cursor中输入：“根据prepare.mdc规则，为‘编辑用户资料’功能做一个技术方案设计。” AI可能会输出一个包含以下要点的文档：

• 领域模型：识别出User聚合根，包含userId、username、avatarUrl等属性。
• 用例：定义一个UpdateUserProfileUseCase，接受新的用户名和头像数据。
• 接口层：需要一个ProfileEditView（SwiftUI）或ProfileEditViewController（UIKit），以及对应的ViewModel。
• 数据层：需要UserRepository协议，以及对应的远程（RemoteUserDataSource）和本地（LocalUserDataSource）实现。
• 风险：头像上传的网络失败处理、图片压缩、编辑过程中的状态管理。

第2步：实现领域层与数据层（启用with-ddd-swift.mdc和clean-architecture-swift.mdc）你接着输入：“根据上述设计和with-ddd-swift.mdc规则，用Swift代码实现User实体和UpdateUserProfileUseCase。” AI会生成类似下面的代码，其中已经包含了值对象、依赖注入等元素：

// User 实体 struct User: Entity { let id: UserId // 值对象，封装UUID字符串 var username: Username // 值对象，封装命名规则验证 var avatarUrl: URL? // ... 其他属性和领域方法 } // 用例 final class UpdateUserProfileUseCase { private let repository: UserRepositoryProtocol init(repository: UserRepositoryProtocol) { // 依赖注入 self.repository = repository } func execute(userId: UserId, newUsername: Username?, newAvatar: Data?) async throws -> User { // 1. 可能的业务验证（如用户名是否已被占用） // 2. 调用仓库更新 let updatedUser = try await repository.updateUserProfile(id: userId, username: newUsername, avatar: newAvatar) // 3. 可能发布领域事件，如 `UserProfileUpdatedEvent` return updatedUser } }

第3步：实现UI与ViewModel（启用with-ios.mdc，假设用SwiftUI）输入：“根据Clean Architecture和SwiftUI，实现ProfileEditViewModel和ProfileEditView。” AI会生成一个遵循ObservableObject的ViewModel，并使用@Published属性包装器来管理状态，同时注入UseCase：

@MainActor final class ProfileEditViewModel: ObservableObject { @Published var username: String = "" @Published var avatarImage: UIImage? @Published var isSaving = false @Published var errorMessage: String? private let updateProfileUseCase: UpdateUserProfileUseCase private let currentUser: User init(currentUser: User, updateProfileUseCase: UpdateUserProfileUseCase) { self.currentUser = currentUser self.updateProfileUseCase = updateProfileUseCase self.username = currentUser.username.value // 从值对象中提取 } func saveChanges() async { isSaving = true errorMessage = nil do { let newUsername = Username(username) // 使用值对象构造器验证 _ = try await updateProfileUseCase.execute( userId: currentUser.id, newUsername: newUsername, newAvatar: avatarImage?.jpegData(compressionQuality: 0.8) ) // 保存成功，可能导航返回或显示成功提示 } catch { errorMessage = error.localizedDescription } isSaving = false } }

第4步：编写测试（启用create-tests-swift.mdc）输入：“为上面的UpdateUserProfileUseCase生成单元测试。” AI会生成使用Mock对象的测试：

import XCTest @testable import YourApp final class UpdateUserProfileUseCaseTests: XCTestCase { private var sut: UpdateUserProfileUseCase! // System Under Test private var mockRepository: MockUserRepository! override func setUp() { super.setUp() mockRepository = MockUserRepository() sut = UpdateUserProfileUseCase(repository: mockRepository) } func test_execute_WhenSuccess_ReturnsUpdatedUser() async throws { // Arrange let expectedUser = User(id: .init(), username: .init("newName")) mockRepository.updateUserProfileResult = .success(expectedUser) // Act let result = try await sut.execute(userId: .init(), newUsername: .init("newName"), newAvatar: nil) // Assert XCTAssertEqual(result.username.value, "newName") XCTAssertTrue(mockRepository.didCallUpdateProfile) } func test_execute_WhenRepositoryFails_ThrowsError() async { // Arrange mockRepository.updateUserProfileResult = .failure(NetworkError.timeout) // Act & Assert do { _ = try await sut.execute(userId: .init(), newUsername: .init("newName"), newAvatar: nil) XCTFail("Expected error to be thrown") } catch { XCTAssertTrue(error is NetworkError) } } }

第5步：收尾与提交（启用finalize.mdc和create-commit-message.mdc）功能完成后，你可以让AI检查代码：“运行finalize.mdc规则检查当前改动的代码。” AI可能会提示“ProfileEditViewModel中未处理头像图片的内存警告”，或者“UpdateUserProfileUseCase的文档注释不完整”。 最后，当你提交代码时，可以问AI：“根据create-commit-message.mdc，为刚才的改动生成一条符合约定式提交规范的Commit信息。” 它会生成类似：feat(profile): add edit username and avatar functionality with offline support [PROJ-123]。

通过这个流程，AI从一个被动的代码补全工具，转变为一个理解你项目上下文、遵循既定规范的主动协作伙伴，极大地提升了复杂功能开发的效率和质量一致性。

5. 常见问题、排查与效能提升技巧

即使有了完善的规则，在实际使用中也可能遇到一些问题。以下是一些常见情况及解决思路。

5.1 规则冲突与优先级混乱

问题：同时启用多个规则时，AI的回复可能变得矛盾或低效。例如，一个规则说“多用协议”，另一个规则说“为简单场景直接用具体类”。排查：

1. 隔离测试：一次只启用一个你怀疑有问题的规则，观察AI的行为。
2. 检查规则内容：打开相关的.mdc文件，查看是否有相互覆盖的指令。规则文件的开头部分有时会有优先级声明。
3. 利用Cursor设置：在Cursor的规则管理界面，尝试调整规则的上下顺序，通常上方的规则优先级更高。

解决：最好的办法是定制和合并规则。如果with-swift.mdc和clean-architecture-swift.mdc在某个点上冲突，你应该创建一个本项目的project-rules.mdc，在其中明确写出你们团队的最终决定（例如：“在数据层，定义Repository协议；在领域层，依赖协议。但在表示层，对于简单的ViewModel，可以直接使用具体类，除非需要单元测试。”），并确保这个项目级规则的优先级最高。

5.2 AI生成代码过于通用或不符合具体业务

问题：规则让代码更规范了，但AI生成的业务逻辑可能还是太模板化，缺乏对具体业务细节的深入理解。解决：

1. 提供更丰富的上下文：在向AI提问时，除了描述功能，最好附上相关的领域模型、接口文档或已有的类似代码片段。Cursor的“引用代码”功能（@符号）在这里非常有用。
2. 在规则中嵌入业务术语：在你们的定制化规则文件里，直接定义核心的业务概念、领域服务名称和关键业务流程。例如，在with-ddd-swift.mdc的末尾加上：“本项目核心领域包括：订单（Order）、支付（Payment）、库存（Inventory）。订单有‘待支付’、‘已发货’、‘已完成’等状态。支付服务通过PaymentGateway抽象与第三方交互。”
3. 迭代式生成：不要期望AI一次生成完美代码。先让它生成一个符合规则的骨架，然后你在此基础上提出更具体的修改要求，如“将这里的硬编码字符串换成从Localizable.strings文件中读取”，“这个计算属性需要考虑到用户会员等级折扣”。

5.3 性能与响应延迟

问题：启用的规则文件过多、过大，可能导致Cursor AI响应变慢。排查与优化：

1. 精简规则：定期回顾规则，删除那些很少使用或已被更通用规则覆盖的条目。保持每个.mdc文件聚焦于一个特定主题。
2. 按需加载：不要全局启用所有规则。利用Cursor的工作区（Workspace）功能，为不同的项目配置不同的规则集。例如，一个纯SwiftUI的新项目可能不需要with-ios.mdc中关于UIKit的详细指导。
3. 优化指令表述：规则指令应清晰、简洁、无歧义。避免冗长的散文式描述，多用列表和关键词。AI解析起来更快，理解也更准确。

5.4 规则维护与团队同步

问题：团队多人使用，如何保证大家使用的规则版本一致？规则更新了如何同步？解决：

1. 版本化仓库：将你们定制后的规则仓库作为项目的一个子模块（Git Submodule）或通过Swift Package Manager的资源引入方式（如果将来支持）进行管理。这样，规则就可以像代码依赖一样进行版本控制。
2. 文档化变更：在规则仓库中维护一个CHANGELOG.md，记录每次规则修改的内容和原因。团队成员更新规则时，需要阅读变更日志以了解影响。
3. 共享配置：除了规则文件，团队还可以共享Cursor的settings.json配置片段，其中包含规则路径和启用状态的设置，进一步统一开发环境。

一个高效的技巧：建立一个“规则沙箱”项目。这是一个简单的、用于测试的iOS项目。每当你修改或新增了一条规则，先在这个沙箱项目中用一些典型任务（如“创建一个列表视图”、“写一个网络请求”）进行测试，验证AI的输出是否符合预期，然后再合并到主规则库中。这能有效避免有问题的规则影响实际的生产项目。

最终，ios-cursor-rules项目的精髓不在于它提供了多少条现成的规则，而在于它展示了一种将AI编程助手深度融入专业化、规范化开发流程的方法论。它启发了我们，通过精心设计的上下文和指令，我们可以将AI从“一个什么都懂但都不精的实习生”，培养成“一个深刻理解我们项目文化和技术栈的资深搭档”。这个过程本身，也是对团队工程实践和知识沉淀的一次极佳梳理。