Covers all five SOLID principles with dedicated references (SRP, OCP, LSP, ISP, DIP), concurrency patterns (actors, @MainActor, Sendable), an anti-pattern catalog, and code templates for views, view models, services, protocols, and models.
Requires grepping the codebase for reusable protocols/services before writing new code, and checking shared locations (Core/Extensions/, Core/Utilities/, Core/Protocols/) before duplicating logic used by 2+ features.
SOLID Swift - Apple Best Practices 2026Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing architecture
- fuse-ai-pilot:research-expert - Verify Swift/Apple docs via Apple Docs MCP + Context7
- XcodeBuildMCP - Build validation after code changes. Then run fuse-ai-pilot:sniper.
DRY - Reuse Before Creating (MANDATORY)
Before writing ANY new code:
- Grep the codebase for similar protocols, services, or logic
- Check shared locations:
Core/Extensions/,Core/Utilities/,Core/Protocols/ - If similar code exists -> extend/reuse instead of duplicate
- If code will be used by 2+ features -> create it in
Core/directly
Architecture (Features Modular MANDATORY)
| Layer | Location |
|---|---|
| Views | Features/[Feature]/Views/ |
| ViewModels | Features/[Feature]/ViewModels/ |
| Services | Features/[Feature]/Services/ |
| Protocols | Features/[Feature]/Protocols/ |
| Shared | Core/{Models,Protocols,Services,Extensions,Utilities}/ |
File size: the only line limit is the hook ceiling (FUSE_SOLID_MAX_LINES). Split by responsibility well before it; if a legitimate fix cannot fit, report it - never bypass the hook.
NEVER use flat Sources/ structure - always Features/[Feature]/
Critical Rules (MANDATORY)
| Rule | Value |
|---|---|
| File limit | Hook ceiling FUSE_SOLID_MAX_LINES only; one responsibility per file |
| ViewModels | @MainActor @Observable |
| Protocols | Features/[Feature]/Protocols/ or Core/Protocols/ ONLY |
| Models | Sendable structs |
| Documentation | /// on all public APIs |
| Previews | Every View MUST have #Preview |
Reference Guide
Concepts
| Topic | Reference | When to consult |
|---|---|---|
| SOLID Overview | solid-principles.md | Quick reference all principles |
| SRP | single-responsibility.md | Fat views/VMs, splitting files |
| OCP | open-closed.md | Adding providers, extensibility |
| LSP | liskov-substitution.md | Protocol contracts, testing |
| ISP | interface-segregation.md | Fat protocols, splitting |
| DIP | dependency-inversion.md | Injection, testing, mocking |
| Concurrency | concurrency-patterns.md | Actors, @MainActor, Sendable |
| Anti-Patterns | anti-patterns.md | Code smells detection |
Templates
| Template | When to use |
|---|---|
| view.md | SwiftUI View with subviews and #Preview |
| viewmodel.md | @Observable ViewModel with @MainActor |
| service.md | API Service, Mock, Cache actor |
| protocol.md | Service protocol, CQRS, Auth |
| model.md | Model, DTO, Error, Enum |
Forbidden
| Anti-Pattern | Fix |
|---|---|
| File with several responsibilities, or blocked by the hook ceiling | Split by responsibility |
| Protocols in impl files | Move to Protocols/ directory |
ObservableObject |
Use @Observable |
| Completion handlers | Use async/await |
Missing #Preview |
Add preview for every View |
| Non-Sendable in async | Use struct with let |
Flat Sources/ structure |
Use Features/[Feature]/ |