ai-docs/assets/instructions/swift.instructions.md

description	applyTo
Swift coding style, formatting, and syntax rules for Toyota OneApp iOS	**/*.swift, **/Package.swift, **/Package.resolved

Swift Coding Style Instructions

These rules auto-apply when editing Swift files. For full architectural guidance, project structure, GraphQL networking, Clean Architecture patterns, and planning — use the Swift iOS Engineer agent.

Code Style and Formatting

SwiftLint and swift-format Compliance

You MUST follow SwiftLint and swift-format configurations defined in .swiftlint.yml and .swift-format.

Key Requirements:

• You WILL use 4-space indentation
• You WILL limit line length to 120 characters, but try to keep all expressions to 1 line when possible
• You WILL include trailing commas in multiline collections (swift-format handles this)
• You WILL use private access level for file-scoped declarations
• You WILL avoid force unwrapping (!) and force try (try!) except in tests

Naming Conventions

You MUST follow Swift API Design Guidelines:

• Types: UpperCamelCase (e.g., ClimateScheduleRepo, Vehicle)
• Variables/Functions: lowerCamelCase (e.g., fetchClimateStatus, reservationId)
• Constants: lowerCamelCase (e.g., maxTemperature, defaultTimeout)
• Protocols: Descriptive names ending in -able, -ing, or role-based (e.g., ClimateScheduleRepo, Codable)
• State management classes: Use "StateNotifier" — NEVER "ViewModel"

File Headers

You MUST include copyright headers in all Swift files. You WILL use the current year in copyright headers.

// Copyright © 2026 Toyota. All rights reserved.

Code Organization

You WILL organize code with MARK comments for major sections only. You WILL use MARK comments to separate significant logical groupings within a file.

// ✅ CORRECT: MARK for major sections
// MARK: - Climate Schedule Use Cases

// ❌ AVOID: Excessive MARK comments for every section
// MARK: Properties          // Too granular
// MARK: Initialization       // Too granular

Swift Language Rules

Concurrency

You MUST use async/await for all asynchronous operations. You WILL NEVER introduce RxSwift or Combine in new code.

// ✅ CORRECT
func fetchClimateStatus(vehicle: Vehicle) async -> Result<Bool, RequestFailure> {
    do {
        let status = try await apiClient.fetchStatus(vehicle)
        return .success(status.isEnabled)
    } catch {
        return .failure(.networkError(error))
    }
}

// ❌ AVOID: Combine or RxSwift

SwiftUI

You MUST use SwiftUI for all new UI features. You WILL use @StateObject, @ObservedObject, and @Published for state management. MANDATORY: You MUST provide #Preview for every SwiftUI view using mock implementations.

Dependency Management

CRITICAL: Do NOT add CocoaPods dependencies. Use Swift Package Manager only.

• Local packages: .package(path: "../{PackageName}")
• External packages: .package(url:...) with version constraints
• Minimum platform: .iOS(.v17) for new packages

Error Handling

You WILL use Swift's Result type for operations that can fail. You WILL define custom error types conforming to Error protocol.

Comments

Comment the "why", never the "what". Do not write comments that restate what code does.