ios-dev-playbook

name

ios-dev-playbook

description

Use when writing, refactoring, or debugging iOS app code (Swift, SwiftUI, Swift Concurrency, Xcode) — before adding a feature, choosing state ownership (@State / @Observable / @Environment), touching MainActor/actor/Sendable, preparing a TestFlight/App Store build, or when facing App Store review rejection, provisioning profile errors, missing dSYM / unsymbolicated crashes, data races, or continuation misuse.

🌐 繁體中文（canonical） · English mirror

iOS Development Judgment Handbook

Core Principles

1. A green simulator proves nothing: signing, provisioning, release optimization, assert being stripped, background modes, memory pressure — these are only real on device/release. Changes on the shipping path must be verified on a real device + at release level.
2. State has exactly one owner; data flows down, events flow up: a View is a function of state, and body must be cheap and side-effect-free.
3. UI state always on MainActor: not by remembering to call DispatchQueue.main, but by using @MainActor so the type system guarantees it for you.
4. A continuation must resume exactly once: when bridging an old API, zero times = permanent hang, twice = crash — this is a red line, not a style preference.
5. Cancellation is cooperative: a Task does not stop itself; long work must actively call Task.checkCancellation(). Only the .task modifier binds to the lifecycle automatically.

Kickoff Routing

Situation	Path	Read first
New screen/feature	Define state owner and data flow first, then write the View	references/architecture-state.md
Whether to build a ViewModel, where state lives	Decide MV vs MVVM first; don't reflexively reach for MVVM	references/architecture-state.md §2
Navigation, deep links, back stack	Drive NavigationStack path from state	references/architecture-state.md §5
async/await, Task, actor, data races	Check scope and the level of MainActor annotation	references/concurrency.md
Bridging an old completion handler / delegate	continuation resumes exactly once	references/concurrency.md §6
Swift 6 strict concurrency reports a Sendable error	Don't slap on @unchecked; look at data ownership first	references/concurrency.md §4
Shipping to TestFlight / App Store / changing signing	Run the checklist item by item	references/release-checklist.md
Fine in the simulator, blows up only on device/at ship time	Suspect signing/optimization/background modes first	references/release-checklist.md

Red Lines (Absolutely Forbidden)

• Never declare a ship-related change done based on simulator verification alone — signing, entitlement, background mode, release optimization are all unreal in the simulator.
• Never let a continuation resume twice or zero times — twice crashes outright, zero hangs forever; every path must resume exactly once.
• Never write a lazy or empty App Store purpose string (NSCameraUsageDescription etc.) — Apple rejects under Guideline 5.1.1 directly; a missing usage description crashes or gets rejected.
• Never push UI state updates off MainActor — a data race plus updating the screen on a background thread is undefined behavior; annotate with @MainActor rather than hand-switching queues.
• Never do networking/IO/state writes inside body — body may recompute multiple times per frame, so side effects run explosively; use .task/.onChange or push down into the model.
• Never put a reference type in @State, or rebuild an @ObservedObject every time — the former means SwiftUI doesn't track changes; the latter loses state on every refresh.
• Never edit a test assertion to make CI go green — two red runs in a row is a signal you're going the wrong way; back up to the last decision point.

Failure Signals (Back Up, Don't Retry)

Symptom	Usually means	Back up to
Screen data changed but UI doesn't update	Value in the wrong property wrapper (reference type in @State / forgot @Observable)	State ownership design
Sprinkling DispatchQueue.main.async everywhere to stop crashes/warnings	Wrong level of MainActor annotation — should annotate the type, not scattered call sites	concurrency §2
Swapped .task for Task {} and now leaks / duplicate requests appear	Lifecycle not bound to the View; a hand-written Task isn't cancelled	concurrency §1
Suppressing Sendable warnings one by one with @unchecked	Mutable state has no clear ownership	concurrency §4
Fine in simulator, fails only on device Archive	Signing/provisioning/optimization differences	release-checklist decision tree
Rejected at review, changed one purpose string, rejected again	Lazy string, or missed another guideline	release-checklist review list
Production crashes are all 0x... with no symbols	dSYM not uploaded	release-checklist §dSYM

references Index

• references/architecture-state.md — SwiftUI state ownership decision table, MV vs MVVM, unidirectional data flow, body cost, NavigationStack modeling. Read before touching architecture or adding a feature.
• references/concurrency.md — Task lifecycle, level of @MainActor annotation, actor, Sendable/Swift 6, cancellation, continuation bridging. Read whenever you touch async.
• references/release-checklist.md — signing/provisioning decision tree, high-frequency App Store rejection reasons, dSYM, release-only differences, TestFlight, versioning. Required reading before shipping.
• references/test-scenarios.md — judgment quiz set, to verify whether a receiving model actually follows this. Do not give it to a running model to read.