swift-architecture-skill

Swift 架构技能

概述

使用此技能，为 SwiftUI/UIKit 代码库选择最合适的 Swift 架构实践指南，并将其应用到用户的任务中。

快速路径

选择架构之前，务必先了解：

• 任务类型（新功能、重构、PR 审查、调试）
• UI 技术栈（SwiftUI、UIKit 或混合使用）
• 最低部署目标（iOS 17+ 支持 @Observable；iOS 16 需要 ObservableObject）
• 范围（单个屏幕、多个屏幕、整个应用）
• 状态与副作用的复杂程度
• 团队熟悉程度和对依赖项的接受度
• 需要保留的现有约定

然后：

• 如果用户明确指定了某种架构，先将其作为候选方案，并检查是否适用
• 如果用户没有指定架构，加载 references/selection-guide.md，根据已说明的约束推断最合适的方案
• 如果最合适的方案需要组合多种模式，为功能边界指定一个主要实践指南，并为辅助关注点指定一个次要实践指南
• 对于约束明确的单功能指导，选择快速推荐模式
• 对于迁移、混合架构或模块边界变更，选择深度重构模式

快速推荐模式

适用于以下情况：

• 范围仅限一个功能或屏幕
• 约束足够明确，可以推荐一种主要模式
• 用户主要需要建议、脚手架或审查清单

交付内容：

• 适用性结论（fit 或 mismatch）
• 1-2 个基于请求的理由
• 所选参考文件
• 针对该功能的具体结构、状态、依赖、异步处理和测试建议

深度重构模式

适用于以下情况：

• 请求涉及多个模块或屏幕
• 代码库已经混用了多种架构
• 用户正在从一种模式迁移到另一种模式

交付内容：

• 当前状态评估
• 目标架构建议及适用或不适用的结论
• 渐进式迁移路径，并指出边界变更
• 迁移期间的风险、权衡和验证要点

架构路由器

如果用户明确指定了某种架构，先将其作为候选方案，并在采用之前检查是否适用：

• 根据 UI 技术栈（SwiftUI/UIKit/混合使用）、最低部署目标、状态复杂度、副作用编排需求、团队熟悉程度和现有代码库约定进行验证
• 如果适用，则采用用户指定的架构
• 如果与关键约束不符，明确说明不匹配之处，并从 references/selection-guide.md 中推荐最接近的替代方案
• 如果用户仍坚持使用不匹配的架构，则制定降低风险的方案，并提前说明风险

架构参考映射：

• MVVM（屏幕级状态与轻量绑定） → references/mvvm.md
• MVI（无需框架依赖的 reducer 风格状态机） → references/mvi.md
• TCA（可组合功能与严格的副作用编排） → references/tca.md
• Clean Architecture（严格分层与可替换的基础设施） → references/clean-architecture.md
• VIPER（大型 UIKit 模块与明确的角色分离） → references/viper.md
• Reactive（以 Combine/RxSwift 流为主的功能） → references/reactive.md
• MVP（由 presenter 驱动渲染的 UIKit 被动视图） → references/mvp.md
• Coordinator（导航流程与深度链接） → references/coordinator.md

共享参考（相关时与所选实践指南一同加载）：

• references/concurrency.md：取消、过期响应保护，以及实践指南代码片段中使用的 userMessage(for:) 错误映射约定；编写或审查异步代码时加载
• references/observation.md：根据部署目标选择 @Observable 或 ObservableObject；配置 SwiftUI 状态时加载

如果最合适的方案需要组合多种模式，请遵循 references/selection-guide.md 中的组合架构，阅读两种实践指南，并在提供文件结构或代码之前说明每种模式负责的边界。

分析现有代码库（适用时）

当代码已存在时：

• 检测当前架构和依赖注入（DI）风格
• 记录并发模型（async/await、Combine、GCD 或混合模式）
• 让建议符合本地约定

防护原则

• 当当前本地模式仍然适用时，不要为了一个小功能强行切换架构。
• 除非不一致严重到足以证明变更的合理性，否则应保留现有约定。
• 除非用户明确接受这种权衡，或代码库已经在使用，否则不要引入 TCA 等新的框架依赖。
• 优先采用能够妥善解决需求的最小架构变更。
• 指导应针对特定架构；除非模式之间的边界明确，否则不要混用不同的实践指南。
• 对于组合模式，避免混合职责：先确定主要边界，再仅针对其关注点应用次要实践指南。

提供具体交付内容

阅读选定的架构参考资料，并将其中的指导转化为符合用户需求的交付内容：

• 文件和模块结构：提供包含该功能专属文件名的目录布局
• 状态和依赖边界：提供具体类型、协议和注入点
• 异步策略：涵盖取消、Actor 隔离和错误路径
• 测试策略：说明测试内容、依赖的替身方式，以及示例测试结构
• 迁移路径（针对重构）：说明从当前架构逐步迁移到目标架构的步骤
• UI 技术栈适配：说明所选架构下 SwiftUI 和 UIKit 指导的差异

输出要求

• 将建议限制在用户请求的功能或审查任务范围内。
• 优先采用基于协议的依赖注入和明确的状态建模。
• 指出在现有代码中发现的反模式，并提供直接的修复方案。
• 所有异步流程都要包含取消和错误处理。
• 对于明确提出的架构请求，需简要给出适配结果（匹配或不匹配），并说明 1-2 个原因。
• 对于不匹配的情况，提供一个最接近的适配方案，说明它为何更符合所述限制，并指出一项权衡。
• 编写代码时，只包含与任务相关的模式，不要整篇照搬实践指南。
• 默认将参考代码片段视为示例；仅当用户要求提供可运行代码时，才添加完整的编译脚手架。
• 只询问最少的阻塞性问题；否则基于明确列出的假设继续。
• 审查 PR 时，使用特定架构的检查清单，并指出具体违规之处及对应的行级修复方案。

验证检查清单

完成前：

1. 确认所选模式符合用户的限制和技术栈
2. 确认已涵盖依赖注入、状态归属、副作用和测试策略
3. 建议进行架构变更时，明确指出迁移风险
4. 结尾附上针对用户功能调整后的所选架构 PR 审查检查清单

文档 QA 检查清单

更新参考资料时，验证：

1. 章节结构保持一致（默认路径、高级变体、迁移说明、含最低要求的测试章节、PR 审查检查清单）
2. 代码片段内部一致且看起来可以编译
3. 跨实践指南链接指向正确的参考文件
4. 选型指南和实践指南中的术语保持一致