ios-architecture-expert（iOS 架构 expert）

iOS Architecture Expert — Essential Developer Methodology

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Feature modules have zero UIKit/SwiftUI imports — only Foundation. Domain models, use cases, presenters, and API/cache logic never depend on a UI framework.
2. Define protocol boundaries at every layer transition — FeedStore, HTTPClient, ResourceView, FeedCache, etc. Concrete types live behind protocols.
3. Domain models are value types — struct, Hashable, Sendable. No classes for models.
4. Presentation logic is framework-agnostic — presenters output view models (structs). No UIImage, UIColor, or SwiftUI types in the presentation layer.
5. All dependency wiring happens in the Composition Root — the app target (or a dedicated CompositionRoot module). Feature modules never create their own dependencies.
6. Tests drive the design — one test class per use case, named by behavior (CacheFeedUseCaseTests, not LocalFeedLoaderTests). Use makeSUT() factory in every test class.
7. Use SPM multi-target packages for module separation — EssentialFeed (Foundation), EssentialFeediOS (UIKit), EssentialApp (composition).
8. Prefer async/await over closures/Combine for async operations. Use Task.immediate for synchronous-first execution in adapters.
9. Use Swift Testing (@Test, #expect) for new tests. Follow patterns in the swift-testing-expert skill when available.
10. Mark shared mutable state with @MainActor — presenters, adapters, view controllers, and composition code run on the main actor.

Architecture Diagnostic Table

Architecture Layers

Full code examples: architecture-layers.md

Key Patterns Quick Reference

Feature Decision Tree

Starting a new feature? Follow this path:

1. Define the domain model -> struct in Feature layer, Hashable, Sendable
2. Add concurrency annotations -> @MainActor on view protocols, Sendable on models
3. Need remote data? -> Endpoint enum + static mapper in API layer
4. Need persistence? -> Store protocol + local model + cache policy in Cache layer
5. Need to display it? -> LoadResourcePresenter + view model struct in Presentation layer
6. UIKit or SwiftUI? -> Build view layer, conform to ResourceView protocols
7. Wire it up -> Composer + adapter + proxy in Composition Root
8. Verify concurrency -> Build with SWIFT_STRICT_CONCURRENCY = complete, run Thread Sanitizer

Step-by-step guide: feature-implementation-workflow.md

Guardrails

• Do not create concrete types inside feature modules — all instantiation belongs in the Composition Root
• Do not use singletons — lazy var in FeedService achieves deferred init without global state
• Do not add @MainActor to domain types or store protocols — only presentation, adapters, and composition
• Do not use @unchecked Sendable — redesign the type as a value type or use @MainActor
• Do not embed cache policy logic inside the loader — keep it as a separate type
• Do not put navigation logic in view controllers — use closure callbacks wired in the Composition Root
• Defer non-architectural concurrency questions to the swift-concurrency skill

Verification Checklist

When implementing or reviewing architecture:

1. Build with SWIFT_STRICT_CONCURRENCY = complete — zero warnings
2. No UIKit/SwiftUI imports in Feature/API/Cache modules
3. All protocol boundaries have corresponding test doubles
4. makeSUT() exists in every test class
5. CoreData store has InMemoryFeedStore fallback in Composition Root
6. Run Thread Sanitizer (-enableThreadSanitizer YES) — zero data races
7. WeakRefVirtualProxy wraps all view references in UIKit composition (or @Observable in SwiftUI)
8. Pagination loadMore is nil for the last page

Reference Router

Open the smallest reference that matches the question:

• Architecture & Layers

- architecture-layers.md — layer boundaries, domain models, protocols - spm-project-structure.md — module layout, Package.swift, CI

• Composition & Wiring

- composition-root.md — FeedService, Scheduler, fallback, dependency creation - adapters-and-proxies.md — adapter, proxy, view adapter, pagination wiring

• Concurrency in Architecture

- concurrency-at-boundaries.md — Scheduler, @Sendable, Task.immediate, cancellation

• Testing

- testing-strategy.md — unit, spec, integration, snapshot, acceptance

• Workflow

- feature-implementation-workflow.md — step-by-step feature building

• Navigation index

- references/_index.md