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这个脚本通常会做以下几件事将仓库克隆到本地一个标准目录如~/.cursor/rules。将所有的.mdc规则文件链接或复制到 Cursor 的规则目录下。可能会尝试在 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响应迟缓。正确的做法是根据项目阶段和当前任务进行动态组合。基础开发组合在编写日常业务代码时启用with-swift.mdcwith-ios.mdcmain-refactoring-rules.mdc。这保证了代码质量和平台规范性。架构设计阶段当在规划新模块或重构旧代码时启用with-ddd-swift.mdc和/或clean-architecture-swift.mdc让AI帮助进行领域建模和分层设计。测试驱动开发在编写功能前或之后启用create-tests-swift.mdc和swift-testing-policy.mdc快速生成测试骨架。发布准备在需要打包发布时启用create-ios-release.mdc让AI帮你检查发布清单或生成Fastlane脚本。Cursor 允许你为规则设置优先级。通常更具体的规则应该比通用规则有更高的优先级。例如clean-architecture-swift.mdc中关于“依赖注入”的指令应该覆盖掉可能存在的更泛泛的“创建类”的指令。你可以在规则文件内部通过注释或特定的语法如果Cursor支持来设置或者在Cursor的规则管理界面进行调整。3.3 个性化定制打造你自己的规则开源规则集是一个绝佳的起点但每个团队都有自己的特殊约定和技术栈。定制化是发挥其最大威力的关键。如何定制Fork 仓库首先 Forkbrunogama/ios-cursor-rules到自己的GitHub账户下。按需修改直接编辑.mdc文件。这些文件本质上是文本文件包含了给AI的指令。例如如果你的团队强制使用Combine进行响应式编程你可以在with-ios.mdc中添加“当处理异步数据流时优先考虑使用Combine框架的Publisher和Subscriber而不是嵌套的回调或NotificationCenter。”添加新规则你可以模仿现有规则的结构创建全新的.mdc文件。比如如果你的项目使用了GraphQL通过 Apollo iOS你可以创建一个with-graphql-ios.mdc里面包含生成GraphQL查询代码、处理响应模型、配置Apollo Client的最佳实践。集成内部工具在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接受新的用户名和头像数据。接口层需要一个ProfileEditViewSwiftUI或ProfileEditViewControllerUIKit以及对应的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属性包装器来管理状态同时注入UseCaseMainActor 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的回复可能变得矛盾或低效。例如一个规则说“多用协议”另一个规则说“为简单场景直接用具体类”。排查隔离测试一次只启用一个你怀疑有问题的规则观察AI的行为。检查规则内容打开相关的.mdc文件查看是否有相互覆盖的指令。规则文件的开头部分有时会有优先级声明。利用Cursor设置在Cursor的规则管理界面尝试调整规则的上下顺序通常上方的规则优先级更高。解决最好的办法是定制和合并规则。如果with-swift.mdc和clean-architecture-swift.mdc在某个点上冲突你应该创建一个本项目的project-rules.mdc在其中明确写出你们团队的最终决定例如“在数据层定义Repository协议在领域层依赖协议。但在表示层对于简单的ViewModel可以直接使用具体类除非需要单元测试。”并确保这个项目级规则的优先级最高。5.2 AI生成代码过于通用或不符合具体业务问题规则让代码更规范了但AI生成的业务逻辑可能还是太模板化缺乏对具体业务细节的深入理解。解决提供更丰富的上下文在向AI提问时除了描述功能最好附上相关的领域模型、接口文档或已有的类似代码片段。Cursor的“引用代码”功能符号在这里非常有用。在规则中嵌入业务术语在你们的定制化规则文件里直接定义核心的业务概念、领域服务名称和关键业务流程。例如在with-ddd-swift.mdc的末尾加上“本项目核心领域包括订单Order、支付Payment、库存Inventory。订单有‘待支付’、‘已发货’、‘已完成’等状态。支付服务通过PaymentGateway抽象与第三方交互。”迭代式生成不要期望AI一次生成完美代码。先让它生成一个符合规则的骨架然后你在此基础上提出更具体的修改要求如“将这里的硬编码字符串换成从Localizable.strings文件中读取”“这个计算属性需要考虑到用户会员等级折扣”。5.3 性能与响应延迟问题启用的规则文件过多、过大可能导致Cursor AI响应变慢。排查与优化精简规则定期回顾规则删除那些很少使用或已被更通用规则覆盖的条目。保持每个.mdc文件聚焦于一个特定主题。按需加载不要全局启用所有规则。利用Cursor的工作区Workspace功能为不同的项目配置不同的规则集。例如一个纯SwiftUI的新项目可能不需要with-ios.mdc中关于UIKit的详细指导。优化指令表述规则指令应清晰、简洁、无歧义。避免冗长的散文式描述多用列表和关键词。AI解析起来更快理解也更准确。5.4 规则维护与团队同步问题团队多人使用如何保证大家使用的规则版本一致规则更新了如何同步解决版本化仓库将你们定制后的规则仓库作为项目的一个子模块Git Submodule或通过Swift Package Manager的资源引入方式如果将来支持进行管理。这样规则就可以像代码依赖一样进行版本控制。文档化变更在规则仓库中维护一个CHANGELOG.md记录每次规则修改的内容和原因。团队成员更新规则时需要阅读变更日志以了解影响。共享配置除了规则文件团队还可以共享Cursor的settings.json配置片段其中包含规则路径和启用状态的设置进一步统一开发环境。一个高效的技巧建立一个“规则沙箱”项目。这是一个简单的、用于测试的iOS项目。每当你修改或新增了一条规则先在这个沙箱项目中用一些典型任务如“创建一个列表视图”、“写一个网络请求”进行测试验证AI的输出是否符合预期然后再合并到主规则库中。这能有效避免有问题的规则影响实际的生产项目。最终ios-cursor-rules项目的精髓不在于它提供了多少条现成的规则而在于它展示了一种将AI编程助手深度融入专业化、规范化开发流程的方法论。它启发了我们通过精心设计的上下文和指令我们可以将AI从“一个什么都懂但都不精的实习生”培养成“一个深刻理解我们项目文化和技术栈的资深搭档”。这个过程本身也是对团队工程实践和知识沉淀的一次极佳梳理。