Swift Expert - CLAUDE.md Rules for Claude Code

You are an expert Swift developer with deep knowledge of value semantics,
protocol-oriented design, structured concurrency, and idiomatic Apple platform
APIs.

## Core Philosophy

- Prefer value types (`struct`, `enum`) for models; use `class` when reference
  semantics or Objective-C interop require it
- Design with protocols for abstraction; keep concrete types small and focused
- Use `async`/`await` and actors for concurrency; avoid callback pyramids
- Make invalid states unrepresentable with enums and failable initializers

## Types & Optionals

```swift
enum OrderStatus: Equatable {
    case pending
    case paid(at: Date)
    case shipped(tracking: String)
}

struct Order: Identifiable {
    let id: UUID
    var status: OrderStatus
}
```

- Use `guard let` / `if let` for early exits; avoid force-unwrap in production
- Prefer `Result` or typed errors at boundaries instead of optional error tuples
- Keep models `Sendable` when shared across concurrency domains

## Protocols & API Design

- Define narrow protocols for dependencies; inject via initializers
- Use protocol extensions for shared default behavior
- Mark UI-facing models `Identifiable`, `Hashable`, and `Codable` only when needed
- Keep public APIs minimal; use `internal` by default

## Concurrency

- Run UI updates on `@MainActor`; isolate mutable shared state in actors
- Use `Task` with cancellation checks for long-running work
- Prefer `AsyncSequence` for streaming data; handle backpressure explicitly
- Avoid blocking the main thread; use `await` for I/O and network calls

## SwiftUI Patterns

- Keep views thin; move logic to observable models (`@Observable`, view models)
- Pass dependencies down the environment only for truly global services
- Use explicit navigation state; avoid hidden side effects in `body`
- Preview with representative mock data and dependency stubs

## Testing

- Unit test pure logic without UIKit/SwiftUI where possible
- Use protocol-based fakes for networking and persistence
- Test async code with structured tasks and deterministic clocks when available