Agent Rules & Engineering Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• AGENTS.md
• GEMINI.md
• README.md
• Features/TagsFeature/Tests/TagsFeatureTests/Views/TagForm/TagFormViewModelTests.swift
• Features/CategoriesFeature/Tests/CategoriesFeatureTests/Views/CategoryForm/CategoryFormViewModelTests.swift

The Agent Rules and Engineering Guidelines define the collaborative framework for AI agents acting as senior Swift collaborators on the Trackurr project. These rules ensure consistency in code style, architectural integrity, and development workflows, emphasizing concise communication and adherence to project-specific patterns.

The scope covers everything from repository structure and dependency management to testing strategies and CI/CD operations. By following these guidelines, agents maintain a high standard of code quality and architectural coherence across the main app target and its various feature modules.

Sources: CLAUDE.md:1-6, AGENTS.md:1-6, README.md:14-20

Core Development Workflow

Agents are expected to act as senior collaborators, which involves clarifying requirements before implementation and following a structured set of rules loaded dynamically.

Interaction Protocol

• Conciseness: Keep responses technical and direct.
• Clarification: Ask questions when requirements or UX designs are ambiguous.
• Rule Loading: Always load .agent/rules/rule-loading.md to determine active rules for the current session.
• Incremental Changes: Favor small, incremental PRs with clear testing notes.

Sources: CLAUDE.md:3-36, AGENTS.md:3-36, GEMINI.md:3-36

Architectural Structure

The project utilizes a modular architecture built with Swift Packages and centralized Dependency Injection (DI).

Engineering Standards

Code Style & UI Patterns

• Language: Swift 5.9+, iOS 17+.
• Formatting: SwiftFormat is mandatory (4-space indent, 120 character limit). A build script is typically used to enforce this.
• UI Framework: Modern SwiftUI using the @Observable framework.
• View Models: Keep them focused on state and side effects; avoid complex logic inside views.
• Dependency Injection: Use Factory; avoid singletons in new code to maintain testability.

Sources: CLAUDE.md:27-31, README.md:104-110, README.md:118-124

Data Persistence

The application uses SwiftData for local persistence with CloudKit synchronization for private user data.

Component	Responsibility	Location
Models	SwiftData entity definitions	Trackurr/Dependencies/Persistence/
Stores	Data access logic and CRUD operations	Trackurr/Dependencies/Persistence/Store/
Migrations	Schema evolution plans	Trackurr/Dependencies/Persistence/
Seeding	Debug data for testing	Trackurr/Dependencies/Persistence/Seeding/

Sources: CLAUDE.md:14-15, README.md:50-55, README.md:157-170

Implementation Guidelines

Validation Logic

Feature modules follow consistent validation patterns, particularly for user input in forms. For example, both TagForm and CategoryForm implement specific constraints:

• Empty Check: Names cannot be empty or consist only of whitespace.
• Character Limit: Names are generally limited to 30 characters.
• Trimming: Leading and trailing whitespace must be trimmed before saving.

Sources: Features/TagsFeature/Tests/TagsFeatureTests/Views/TagForm/TagFormViewModelTests.swift:65-100, Features/CategoriesFeature/Tests/CategoriesFeatureTests/Views/CategoryForm/CategoryFormViewModelTests.swift:75-120

Analytics Strategy

Agents must integrate analytics tracking in view models following a standard naming convention.

Testing & Automation

Testing Framework

The project has migrated to Swift Testing.

• Location: Tests should be kept near the owning module (e.g., Features/<Name>/Tests/).
• Mocks: Utilize the Packages/Mocks package for test doubles.
• Suite/Test: Use @Suite and @Test macros for organizing and defining test cases.

Sources: CLAUDE.md:41-43, README.md:173-178, Features/TagsFeature/Tests/TagsFeatureTests/Views/TagForm/TagFormViewModelTests.swift:9-12

Essential Commands

Action	Command
Build	xcodebuild -scheme Trackurr -destination 'platform=iOS Simulator,name=iPhone 15' build
Test	xcodebuild -scheme Trackurr -destination 'platform=iOS Simulator,name=iPhone 15' test
Format	swiftformat --config .swiftformat .
Deploy Beta	bundle exec fastlane beta

Sources: CLAUDE.md:18-24, README.md:110-115

Conclusion

The Agent Rules & Engineering Guidelines provide a rigorous structure for AI-driven development. By emphasizing modularity through Swift Packages, compile-safe DI with Factory, and strict input validation/testing, the project maintains a high level of stability and maintainability. Agents must strictly adhere to these patterns to ensure that new features integrate seamlessly with existing persistence and analytics systems.