iOS Xcode & Tooling Best Practices

Comprehensive guide for Xcode project configuration, SwiftData persistence, testing, debugging, profiling, and app distribution. Contains 19 rules across 6 categories.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Setting up Xcode projects with AppStorage, ScenePhase, or widgets
• Implementing SwiftData models, queries, and CRUD operations
• Writing tests with Swift Testing framework
• Debugging with breakpoints and console output
• Profiling performance with Instruments
• Distributing apps via TestFlight
• Building for visionOS or integrating ML features

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	SwiftData & Persistence	CRITICAL	data-
2	Project & Platform	HIGH	platform-
3	Testing	HIGH	test-
4	Debugging & Profiling	MEDIUM-HIGH	debug-, perf-
5	Distribution	MEDIUM	dist-
6	Specialty Platforms	MEDIUM	ml-, spatial-

Quick Reference

1. Project & Platform (HIGH)

• platform-app-storage - Use AppStorage for user preferences
• platform-scene-phase - Respond to app lifecycle with ScenePhase
• platform-widget-integration - Design for widget and Live Activity integration
• platform-system-features - Integrate system features natively

2. SwiftData & Persistence (CRITICAL)

• data-model-macro - Define models with @Model macro
• data-query-for-fetching - Use @Query for fetching data
• data-model-container - Configure model containers
• data-relationships - Define model relationships
• data-crud-operations - Implement CRUD operations

3. Testing (HIGH)

• test-swift-testing - Use Swift Testing framework
• test-preview-sample-data - Create preview sample data
• test-preview-macro - Use #Preview macro for rapid iteration

4. Debugging & Profiling (MEDIUM-HIGH)

• debug-breakpoints - Use breakpoints for debugging
• debug-console-output - Use console output for debugging
• perf-instruments-profiling - Profile SwiftUI with Instruments

5. Distribution (MEDIUM)

• dist-testflight - Distribute via TestFlight
• dist-app-icons - Design app icons for distribution

6. Specialty Platforms (MEDIUM)

• ml-natural-language - Integrate Natural Language ML
• spatial-visionos-windows - Build for visionOS spatial computing

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules