Imported from yelog/SnapTraTranslator (
AGENTS.md). Install upstream withnpx skills add yelog/SnapTraTranslator. Copyright stays with the author.
AGENTS.md
Scope
- Applies to the entire repository at
/Users/yelog/workspace/swift/SnapTra Translator. - This file is intended for agentic coding assistants.
Project Overview
- Xcode project:
SnapTra Translator.xcodeproj - SwiftUI macOS app: Menu bar (accessory) app for instant OCR translation
- Target:
SnapTra Translator(single app target, no test targets) - Minimum macOS: 14.0 (translation features require macOS 15.0+)
Build / Run / Test Commands
Build (CLI)
# Debug build
xcodebuild -project "SnapTra Translator.xcodeproj" -scheme "SnapTra Translator" -configuration Debug build
# Release build
xcodebuild -project "SnapTra Translator.xcodeproj" -scheme "SnapTra Translator" -configuration Release build
Run
Preferred: Open in Xcode and run (⌘R):
open "SnapTra Translator.xcodeproj"
Clean
xcodebuild -project "SnapTra Translator.xcodeproj" -scheme "SnapTra Translator" clean
Tests
- No test target currently exists.
- When added, run all tests:
xcodebuild -project "SnapTra Translator.xcodeproj" -scheme "SnapTra Translator" test - Run a single test:
xcodebuild -project "SnapTra Translator.xcodeproj" -scheme "SnapTra Translator" test \ -only-testing:<TestTarget>/<TestCase>/<testMethod>
Lint / Format
- No
SwiftLint,SwiftFormat, or.editorconfigcurrently configured. - Follow Xcode default formatting (4 spaces, no tabs).
Code Style Guidelines
Formatting
- Indentation: 4 spaces (Xcode default).
- Use trailing commas for multiline collections and parameter lists.
- Keep
bodyand view builders vertically aligned and indented consistently. - Prefer line breaks for view modifier chains once they exceed one line.
- Avoid trailing whitespace and excessive vertical spacing.
Imports
- One
importper line. - Keep
SwiftUIat the top when it is used. - Avoid unused imports.
Naming
- Types and protocols:
UpperCamelCase. - Variables, functions, and properties:
lowerCamelCase. - Boolean properties: affirmative names (
isEnabled,hasFocus). - SwiftUI views: suffix with
Viewonly when it clarifies intent. - File names should match the primary type when practical.
Types and APIs
- Prefer explicit types at public boundaries.
- Use type inference for local values when it improves readability.
- Avoid force unwraps (
!); useguard,if let, orthrows. - Avoid
as!; use safe casts withas?and handle nil.
Error Handling
- Use
throwsfor recoverable failures. - Convert errors to user-visible messages at the UI boundary.
- Prefer
Resultonly when you need to store or pass outcomes. - Do not swallow errors; log or surface them.
SwiftUI Patterns
- Keep
bodysmall; extract subviews for complex layouts. - Use
@Statefor local UI state and@ObservedObject/@StateObjectfor model state. - Prefer view modifiers for styling over wrapper views.
- Use
@MainActorwhen interacting with UI state from async code.
View Composition
- Favor small, reusable views over deeply nested stacks.
- Use
ViewBuilderhelpers for conditional composition. - Group modifier chains by purpose (layout, style, behavior).
- Use
Spacer()intentionally to express layout intent. - Prefer
Labelfor icon + text pairs when possible.
State and Data Flow
- Keep a single source of truth for view state.
- Use
@Statefor view-owned state and@StateObjectfor owned models. - Use
@ObservedObjector@EnvironmentObjectfor injected models. - Avoid mutating state directly inside
body. - Trigger side effects from
task,onAppear, or explicit actions.
Accessibility
- Provide accessibility labels for non-text buttons and images.
- Avoid embedding critical text inside images.
- Use system colors and dynamic type where possible.
- Ensure tappable areas meet minimum size expectations.
Previews
- Keep previews lightweight and deterministic.
- Supply sample data for empty and populated states.
- Avoid network calls in previews.
File Organization
- One primary type per file when practical.
- Group extensions below the main type definition.
- Keep related types close to their primary view or model.
Logging and Diagnostics
- Use
Loggerif structured logging is introduced. - Avoid leaving debug
printstatements in production code.
Dependencies
- Avoid adding dependencies without explicit approval.
- If a dependency is added, document it in this file.
Testing Guidance
- Add a test target before writing unit tests.
- Prefer XCTest for native Swift tests.
- Keep tests deterministic and fast.
- Avoid network calls in unit tests; use stubs.
Concurrency
- Use Swift Concurrency (
async/await) for asynchronous work. - Avoid blocking the main thread; offload work to tasks.
- Wrap UI updates in
MainActor.runif called off-main.
Localization
- Use
LocalizedStringKey/Text("...")for user-facing strings. - Prefer string catalogs if localization is added.
Assets
- Put image and color assets in
Assets.xcassets. - Reference assets by name via
Image("name")orColor("name").
Repository Conventions (Observed)
- Minimal project with a single SwiftUI app target.
- File headers include Xcode template comments.
Editor / Assistant Rules
- No
.cursor/rules/,.cursorrules, or.github/copilot-instructions.mdfound. - If any are added later, mirror them here.
Change Discipline
- Keep changes minimal and focused.
- Avoid refactors unless they are required for the task.
- Do not add new dependencies without explicit request.
