---
type: guidance
project: fidelity
status: active
updated: 2026-04-16
tags:
  - ios
  - fidelity
---
# Current iOS And Swift Practices

## Goal

Keep Swift/iOS answers modern without turning the workspace into stale API documentation.

---

## Currentness Rule

For version-sensitive recommendations, verify against official sources before presenting as current best practice.

Prefer:

- Apple Developer Documentation
- Swift.org / docs.swift.org
- official WWDC materials when API behavior or migration guidance matters

Avoid relying only on memory for:

- newest SwiftUI APIs
- Observation / data-flow migration guidance
- Swift Testing availability or migration advice
- Swift concurrency behavior
- Xcode or iOS version-specific recommendations
- CocoaPods, podspec, private specs repo, trunk/CDN, or dependency-resolution behavior
- Swift Package Manager migration or package-resolution behavior
- CI/build tooling behavior that may depend on current toolchain versions
- claims that something is a "bad practice" when the answer depends on ecosystem status, migration cost, or project constraints

---

## Technical Verification Rule

For programming concepts tied to project decisions, the agent should behave like a senior engineer:

- distinguish stable engineering principles from ecosystem-specific guidance
- verify current tool behavior with primary documentation when the topic is version-sensitive
- separate general best practice from project-safe recommendation
- avoid blanket statements such as "CocoaPods is bad practice" without context
- explain tradeoffs: maintenance status, migration cost, consumer integration risk, release propagation, and validation path
- suggest workspace improvements when a recurring answer-quality gap appears

For Fidelity, dependency tooling is project-relevant because XFlowSDK, XFlowViewMaker, FTFrameworks, and Fid4 integration can depend on published versions, podspec repos, release propagation, and consumer validation.

---

## Stable Defaults

- Prefer simple, testable Swift over clever abstractions.
- Prefer structured concurrency over ad-hoc callback or detached-task patterns when the deployment target and codebase support it.
- Keep UI state changes on the main actor.
- Avoid recommending new APIs until deployment target and project constraints are known.
- For SwiftUI, separate pure view composition from side effects and navigation/workflow coordination.
- For testing, use the framework already adopted by the codebase unless the user explicitly asks about migration.

---

## Testing Guidance

- Apple positions Swift Testing as a modern option for unit tests in Xcode 16 and later.
- XCTest remains relevant, especially for UI tests, performance tests, and existing test suites.
- Do not recommend wholesale migration from XCTest unless the project constraints support it.

---

## SwiftUI Guidance

- Observation can be adopted incrementally; do not assume a project can immediately replace all `ObservableObject` usage.
- In SwiftUI code review, focus on data ownership, lifecycle, invalidation scope, navigation boundaries, and side effects.
- Avoid introducing `@StateObject`, `@ObservedObject`, `@State`, or `@Observable` recommendations without first identifying ownership and deployment constraints.

---

## Source Anchors

- SwiftUI documentation: `https://developer.apple.com/documentation/swiftui`
- Observation migration: `https://developer.apple.com/documentation/swiftui/migrating-from-the-observable-object-protocol-to-the-observable-macro`
- Swift Testing: `https://developer.apple.com/documentation/testing`
- XCTest: `https://developer.apple.com/documentation/xctest`
- Swift language: `https://developer.apple.com/swift/`
- CocoaPods Build with CocoaPods: `https://guides.cocoapods.org/making/`
- CocoaPods Specs and Specs Repo: `https://guides.cocoapods.org/making/specs-and-specs-repo.html`
- CocoaPods Private Pods: `https://guides.cocoapods.org/making/private-cocoapods`
- CocoaPods trunk read-only plan: `https://blog.cocoapods.org/CocoaPods-Specs-Repo/`