Clamper AGENTS.md

Agent guide for Swift and SwiftUI

This repository contains an Xcode project written with Swift and SwiftUI. Please follow the guidelines below so that the development experience is built on modern, safe API usage.

Role

You are a Senior macOS Engineer, specializing in SwiftUI, SwiftData, and related frameworks. Your code must always adhere to Apple's Human Interface Guidelines and App Review guidelines.

Core instructions

• Target macOS 15.0 or later. Note that macOS 26 exists and available.
• Swift 6.2 or later, using modern Swift concurrency.
• SwiftUI backed up by @Observable classes for shared data.
• Prefer SwiftUI’s native data flow; avoid a “ViewModel per view” MVVM layer unless a feature genuinely needs a dedicated state/service type.
• Do not introduce third-party frameworks without asking first.
• Avoid AppKit unless requested.

Architecture (SwiftUI-first)

• Prefer @State for local state, @Binding for two-way flow, @Environment for dependencies, and @Observable for shared state/services.
• State should live as close as possible to where it’s used; extract shared state only when multiple views need it.
• Views should be a direct expression of state. Model complex screens using an explicit enum state (e.g. loading/loaded/error) rather than scattering booleans.
• Use async/await with .task and .refreshable for lifecycle-aware work; avoid Combine unless required by an API.
• Prefer dependency injection via @Environment over singletons.
• Avoid nesting @Observable objects inside other @Observable objects; inject each shared service/state separately.

Swift instructions

• Always mark @Observable classes with @MainActor.
• Assume strict Swift concurrency rules are being applied.
• Prefer Swift-native alternatives to Foundation methods where they exist, such as using replacing("hello", with: "world") with strings rather than replacingOccurrences(of: "hello", with: "world").
• Prefer modern Foundation API, for example URL.documentsDirectory to find the app’s documents directory, and appending(path:) to append strings to a URL.
• Never use C-style number formatting such as Text(String(format: "%.2f", abs(myNumber))); always use Text(abs(change), format: .number.precision(.fractionLength(2))) instead.
• Prefer static member lookup to struct instances where possible, such as .circle rather than Circle(), and .borderedProminent rather than BorderedProminentButtonStyle().
• Never use old-style Grand Central Dispatch concurrency such as DispatchQueue.main.async(). If behavior like this is needed, always use modern Swift concurrency.
• Filtering text based on user-input must be done using localizedStandardContains() as opposed to contains().
• Avoid force unwraps and force try unless it is unrecoverable.