1. 项目概述为iOS开发者量身定制的AI编码规则集如果你是一名iOS开发者并且正在使用Cursor或类似的AI编程助手那么你很可能经历过这样的场景你向AI描述一个功能需求比如“帮我创建一个用户登录的ViewModel”结果AI生成的代码虽然能跑但命名风格混乱、没有遵循Swift的API设计指南、甚至忽略了SwiftUI的StateObject和ObservedObject的正确使用场景。你不得不花费大量时间进行代码审查和重构这反而降低了AI辅助编程的效率。这正是brunogama/ios-cursor-rules这个项目要解决的核心痛点。简单来说这是一个专门为Swift和iOS开发定制的、高度“有主见”的Cursor规则集合。它不是一个简单的代码片段库而是一套完整的、内置于你AI助手“大脑”中的开发规范与最佳实践指南。当你启用这些规则后AI在为你生成代码、编写测试、规划架构甚至撰写提交信息时都会自动遵循一套经过精心设计的标准。这就像为你团队里最聪明但有时会天马行空的新人配备了一位经验丰富的架构师导师确保其输出的每一行代码都符合项目的质量要求和技术栈特点。项目的核心价值在于将“一致性”和“最佳实践”自动化让开发者能更专注于业务逻辑和创新而非反复纠正AI在语法糖和设计模式上的偏差。2. 核心规则集深度解析与设计哲学这套规则集覆盖了iOS开发生命周期的方方面面其设计哲学可以概括为“全栈规范内化”。它不是零散的提示词而是按照现代软件工程的分层思想组织的系统性规则。理解其结构有助于你更好地利用和定制它。2.1 基础开发层编码规范与平台特性这一层是规则的基石确保了代码的“基因”是健康的。with-swift.mdc与with-ios.mdc语言与平台的“宪法”这两个规则文件是重中之重。with-swift.mdc扮演了Swift语言规范的角色。它不仅仅检查命名如使用camelCase而非snake_case更重要的是内化了Swift的设计哲学。例如它会引导AI优先使用值类型struct,enum而非引用类型class除非确需引用语义它会确保错误处理采用Result类型或throws关键字而非通过可选值隐式传递它会推行协议优先的设计鼓励组合而非继承。我曾在项目中启用此规则后让AI生成一个网络层它自动产出了一个基于protocol的、泛型良好的NetworkService并正确使用了async/await进行异步封装完全避免了回调地狱代码风格与团队内部规范高度一致。而with-ios.mdc则专注于平台特性。它教会AI理解iOS生态的约束与最佳实践。一个典型的例子是内存管理与生命周期。在SwiftUI中AI可能会混淆State、StateObject、ObservedObject和EnvironmentObject的使用场景。在此规则下AI会明确知道对于视图私有的简单值用State对于遵循ObservableObject的引用类型模型若为视图创建和持有用StateObject若由父视图传入则用ObservedObject。这从根本上避免了因生命周期管理不当导致的视图状态丢失或内存泄漏问题。2.2 架构与设计层从战术代码到战略设计当项目规模增长时一致的架构比聪明的代码更重要。这一层规则将高阶设计模式“灌输”给AI。with-ddd-swift.mdc与clean-architecture-swift.mdc领域驱动与整洁架构这两个规则是将DDD领域驱动设计和Clean Architecture思想具体化为Swift实践的操作手册。with-ddd-swift.mdc会指导AI如何识别和建模领域实体Entity、值对象Value Object和聚合根Aggregate Root。例如当你要求AI“设计一个电商应用的购物车模块”时在规则约束下AI会首先识别出Cart聚合根、CartItem实体、Money或SKU值对象等核心领域概念并围绕Cart设计仓储接口CartRepository确保领域逻辑的纯粹性。clean-architecture-swift.mdc则进一步强化了依赖关系规则依赖指向内部核心业务不依赖外部框架。它会引导AI构建清晰的层次Domain实体、用例接口、Application用例实现、服务协调、InterfaceUI、Presenter/ViewModel、Infrastructure网络、数据库。AI生成的代码会自然地将网络请求逻辑放在Infrastructure层的APIClient中并通过协议注入到Application层的用例里使得单元测试可以轻松替换为MockAPIClient。这种强制性的关注点分离对于维护大型、长期演进的项目至关重要。实操心得初次引入架构层规则时AI生成的代码可能会显得“过度设计”尤其是对于小型功能或原型。我的经验是可以根据项目的成熟度选择性启用。在项目初期或验证想法的阶段可以暂时放宽架构约束优先使用基础开发层规则保证代码质量。当项目进入稳定迭代期再全面启用架构规则此时AI会基于已有代码库的结构进行延续性设计效果更佳。2.3 质量保障层让测试与重构成为习惯高质量的代码离不开严格的测试和持续的重构。这一层规则旨在提升AI在质量保障方面的输出水平。create-tests-swift.mdc与swift-testing-policy.mdc从会写到写好测试很多开发者包括AI编写测试时容易陷入“为覆盖率而测试”的陷阱。create-tests-swift.mdc规则详细规定了如何编写有价值的测试。它不仅要求使用XCTest更强调了测试的“行为驱动”特性。例如测试方法名应遵循test_Given[状态]_When[操作]_Then[结果]的格式如test_GivenUserIsNotLoggedIn_WhenLoginButtonTapped_ThenShowsLoginScreen这迫使AI在生成测试时先思考场景和行为而不仅仅是调用方法并断言。swift-testing-policy.mdc则是项目级的测试策略。你可以在这里定义团队的标准比如“单元测试覆盖率不低于80%”、“UI测试需覆盖核心用户流程”、“所有异步操作必须使用XCTestExpectation或async/await进行测试”。当AI为你的新功能生成代码后你可以直接指令“为此功能添加单元测试”AI会依据此策略文件生成符合项目标准的、完整的测试套件包括必要的setUp、tearDown和Mock对象。object-calisthenics-swift.mdc代码健身操这是一套有趣的、通过设定严格约束来提升代码质量的规则灵感源于面向对象健身操。例如“每个方法缩进不超过一层”、“不使用else关键字”、“封装所有集合操作”。当AI遵循这些规则时它会产出大量短小精悍的方法通过提前返回guard语句来避免深层嵌套并使用map、filter、reduce等高阶函数处理集合。虽然最初可能觉得代码被“拆”得太碎但长期来看这极大地提升了代码的可读性和可维护性。我曾让AI重构一个复杂的表单验证逻辑在规则约束下它生成了一系列职责单一的验证函数并通过组合的方式构建最终验证器逻辑清晰得像阅读一篇说明文。3. 实战部署与工作流集成指南拥有强大的规则集只是第一步如何将其无缝集成到你和团队的工作流中才是发挥其威力的关键。以下是我在多个项目中实践总结的部署与集成方案。3.1 环境准备与规则安装项目的安装非常简便提供了脚本化的一键安装。但为了适应不同的团队环境我建议理解其原理并进行定制化配置。基础安装与验证官方提供的安装命令是curl -o- https://raw.githubusercontent.com/brunogama/ios-cursor-rules/main/install.sh | bash这条命令会下载并执行安装脚本。脚本的核心工作是1在用户主目录下创建或定位Cursor的规则目录通常为~/.cursor/rules2将本项目中的所有.mdc规则文件复制到该目录3可选地备份已存在的同名规则。执行完成后你需要重启Cursor或VSCode以使新规则生效。验证是否安装成功可以在Cursor中打开一个Swift文件尝试输入一个简单的指令如“创建一个遵循ObservableObject的用户模型”。观察AI生成的代码是否遵循了Swift的命名规范如class UserProfile: ObservableObject并且属性是否正确使用了Published包装器。如果符合说明基础规则已生效。高级定制创建团队专属规则集对于团队项目直接使用原始规则可能不够。我推荐采用“派生覆盖”的策略。Fork项目仓库将brunogama/ios-cursor-rulesfork到你的团队GitHub组织下。定制全局规则在团队仓库中你可以修改with-swift.mdc加入你们团队特有的编码规范。例如规定所有网络请求的URLSession必须通过一个统一的NetworkManager发起或者强制使用特定的日志库格式。创建项目特定规则在具体的iOS项目根目录下可以创建一个.cursor/rules文件夹并放置优先级更高的规则文件。Cursor会优先加载项目目录下的规则其次才是全局规则。这样你可以为某个特定项目启用更严格的架构规则如Clean Architecture而其他个人项目则使用较宽松的全局规则。编写安装脚本为团队编写一个内部安装脚本除了复制规则还可以自动配置Cursor的settings.json例如设置默认启用的规则、或与项目特定的代码片段库关联。3.2 核心开发工作流实战安装好规则后你的日常开发流程将被显著优化。以下是一个从需求到上线的典型工作流示例展示了规则如何介入每个环节。阶段一规划与设计 (prepare.mdc,propose.mdc)当你接到一个“为用户增加推送通知设置页面”的需求时不要直接开始编码。首先在项目中创建一个新的FeatureSpec.md文件然后对AI说“根据prepare.mdc和propose.mdc规则为‘推送通知设置功能’起草一份技术方案。” AI会基于规则生成一份结构化的提案包括需求分析明确功能范围开关控制、分类订阅、静默时段等。技术选型建议使用SwiftUI的Toggle、Section以及UserDefaults或AppStorage进行持久化。架构影响分析该功能属于Settings模块应遵循现有的MVVM或Clean Architecture模式并建议创建NotificationSettingsViewModel。风险评估提醒需要处理用户首次请求通知权限的流程并考虑iOS系统设置同步问题。 这份提案可以作为技术评审的基础确保团队对实现方案达成共识。阶段二编码与测试 (with-swift.mdc,with-ios.mdc,create-tests-swift.mdc)方案确定后开始编码。你可以对AI说“在Settings模块下按照Clean Architecture和MVVM模式实现上述推送通知设置的View和ViewModel。需包含开关状态持久化、权限状态检查逻辑。” 在规则约束下AI会生成高度规范的代码View层使用StateObject持有ViewModelUI代码清晰分块包含适当的无障碍标识accessibilityLabel。ViewModel层遵循ObservableObject使用Published暴露状态将权限请求等副作用逻辑封装在方法中便于测试。依赖注入通过构造函数注入UserDefaults和UNUserNotificationCenter的协议抽象而不是直接使用单例。紧接着你可以命令“为刚才生成的NotificationSettingsViewModel编写完整的单元测试。” AI会根据create-tests-swift.mdc规则生成测试类模拟UNUserNotificationCenter并测试开关状态变化、权限请求成功/失败等多种场景。阶段三重构与优化 (main-refactoring-rules.mdc,finalize.mdc)功能开发完成后运行finalize.mdc规则进行收尾工作。你可以指令“运行代码最终检查。” AI会模拟执行该规则建议你移除未使用的import语句、检查是否有遗留的print调试语句、确保所有公开API都有文档注释///并提示运行Analyze静态分析。 如果代码复杂度上升可以使用main-refactoring-rules.mdc。指令“分析当前ViewModel的toggleNotification方法并提供重构建议。” AI可能会指出方法过长、承担了过多职责检查状态、请求权限、更新存储并建议将其拆分为多个私有方法遵循单一职责原则。3.3 发布与协作流程自动化项目后期发布和协作的规范性同样重要。标准化提交与发布 (create-commit-message.mdc,create-ios-release.mdc)在完成一个功能分支并准备合并时让AI帮助你生成规范的提交信息。指令“基于当前的改动新增了推送设置页面和测试生成符合Conventional Commits规范的提交消息。” AI会输出类似feat(settings): add notification preferences screen with unit tests的消息并自动关联相关的Issue编号如果存在。 对于发布create-ios-release.mdc规则是一个宝典。当你准备提交App Store时可以要求AI“根据create-ios-release.mdc列出本次版本1.2.0发布到TestFlight的检查清单。” AI会生成一个详尽的列表包括更新CFBundleShortVersionString和CFBundleVersion、确保所有新的本地化字符串已添加、更新Fastlane的Deliverfile配置、生成并归档dSYM文件、编写本次更新的发布说明等。这极大地减少了人为疏忽。团队知识管理与可视化 (knowledge-management-rule.mdc,visualization-rule.mdc)随着规则的使用团队会积累大量与AI协作的经验。knowledge-management-rule.mdc可以用来维护一个活的“提示词库”。例如你可以创建一个AI_PROMPTS.md文件记录下针对你项目特定架构比如使用了The Composable Architecture最有效的指令模板。visualization-rule.mdc则能辅助文档工作。你可以要求AI“根据当前项目的Package.swift和主要模块目录生成一个Mermaid格式的模块依赖图。” 虽然输出的是文本描述但你可以轻松地将其粘贴到支持Mermaid的工具中生成可视化的架构图这对于新成员 onboarding 或技术文档编写非常有帮助。4. 常见问题、排查技巧与效能提升在实际使用中你可能会遇到一些挑战。以下是我和社区成员遇到的一些典型问题及其解决方案。4.1 规则冲突与优先级问题问题描述当同时启用多个规则时AI的响应可能变得矛盾或混乱。例如object-calisthenics-swift.mdc要求“不用else”但with-swift.mdc强调代码清晰有时if-else结构反而更易读。排查与解决理解规则加载顺序Cursor规则没有显式的优先级设置但通常后加载的或更具体的规则可能产生更大影响。检查你的规则目录确保没有重复或矛盾的规则文件。精细化指令在指令中明确指定主要遵循的规则。例如你可以说“遵循with-swift.mdc和clean-architecture-swift.mdc规则实现一个用户登录的UseCase。在代码风格上可以适当忽略object-calisthenics中关于‘不用else’的约束以逻辑清晰为首要目标。”定制合并规则最好的方法是创建你自己的“聚合规则”。新建一个如my-team-swift.mdc的文件在其中融合或裁决不同规则间的冲突。例如你可以写明“优先遵循Swift API设计指南。在方法逻辑简单时鼓励使用guard提前返回来避免else但在处理复杂的状态机或清晰的二元逻辑时允许使用if-else以提升可读性。”4.2 AI生成代码不符合预期问题描述即使启用了规则AI生成的代码有时仍会偏离预期比如使用了未导入的第三方库或采用了与项目不同的架构模式。排查与解决提供上下文AI的能力严重依赖于上下文。在开启新对话或新文件时先花一两句话描述项目背景。例如“这是一个采用SwiftUI和The Composable Architecture (TCA) 的iOS项目。请遵循with-swift.mdc规则并参考TCA的模式进行开发。”使用“引用”功能Cursor允许你引用项目中的其他文件。在指令中可以引用一个典型的、写得很好的文件作为范例。例如“请参考Features/Authentication/LoginView.swift的代码结构和架构模式实现一个类似的注册页面。”迭代式生成不要期望AI一次就生成完美代码。采用“分步指令”策略。先让它生成接口或协议定义审查无误后再让它基于这些接口生成具体实现。例如先指令“定义UserRepository协议包含fetchUser(byId:)和saveUser(_:)方法。” 审核后再指令“实现一个符合UserRepository协议的CoreDataUserRepository类。”4.3 规则维护与更新问题描述Swift语言和iOS生态在快速演进项目的最佳实践也可能变化如何让规则集保持同步排查与解决订阅原仓库更新关注brunogama/ios-cursor-rules原仓库的更新。开发者可能会为新的Swift版本或框架如Swift Concurrency的深入应用添加规则。定期将更新合并到你的团队fork中。建立内部评审机制将规则文件视为团队的重要资产。当团队引入一项新技术如SwiftData或形成一条新的最佳实践时例如“所有网络请求必须使用结构化并发”应通过代码评审流程更新对应的.mdc规则文件。规则效能评估定期如每季度回顾规则的使用效果。可以收集团队的反馈哪些规则最有用哪些规则导致了不必要的麻烦是否有新的常见问题需要被规则化根据反馈对规则进行增删改使其始终服务于提升团队效率和代码质量的核心目标。4.4 效能提升超越基础规则的高级用法当你熟练使用基础规则后可以尝试以下高级技巧进一步释放AI编程的潜力。创建场景化复合指令将一系列常用的指令和规则组合成一个“超级指令”。例如你可以创建一个名为“实现新功能模块”的指令模板请遵循以下规则和步骤操作 1. 参考 propose.mdc为功能「[在此填写功能名]」起草简要技术方案。 2. 根据方案遵循 clean-architecture-swift.mdc 和 with-swift.mdc在 Features/ 目录下创建对应的 Domain Entity、UseCase、ViewModel 和 View 文件骨架。 3. 遵循 create-tests-swift.mdc为上述生成的 UseCase 和 ViewModel 编写单元测试。 4. 最后遵循 create-commit-message.mdc生成本次工作的提交信息。将这个模板保存在你的笔记或Cursor的Custom Instructions中可以极大提升启动新功能的效率。利用规则进行代码审查你可以将一段已有的代码粘贴给AI并指令“以with-swift.mdc和main-refactoring-rules.mdc为标准审查这段代码指出不符合规范的地方和改进建议。” AI会像一个严格的审查员指出命名问题、潜在的强制解包、过长的函数以及架构上的改进点。这可以作为人工代码审查的有力补充。训练项目专属知识knowledge-management-rule.mdc的深层用法是构建项目的“领域语言”。将项目特有的业务术语、核心领域模型的定义、以及内部共享库的API文档摘要以结构化的方式写入一个规则文件。当AI理解了你的业务语言比如“订单”、“履约单”、“库存SKU”之间的关系它生成的业务逻辑代码将更加精准减少沟通成本。经过一段时间的深度使用这套规则集将不再是一堆冰冷的配置文件而会内化为你和团队开发DNA的一部分。它带来的最大改变是让AI从一个需要详细指令的“实习生”转变为一个深刻理解你团队技术栈和工程文化的“资深搭档”。代码的一致性、架构的清晰度、开发流程的规范性这些在长期项目中难以维护的软性资产通过规则得到了自动化的保障。最终你和你的团队可以将更多精力投入到创造性的问题解决和产品创新之中这才是工具解放生产力的真谛。