swift-patterns-skill: Instructions file for Codex

Agent Guidelines for Swift Patterns

This document provides guidance for AI agents working with this skill to ensure consistency and avoid common pitfalls.

Core Principles

1. Swift and SwiftUI Focus

This is a Swift and SwiftUI skill. Do not include:

• Server-side Swift patterns
• UIKit patterns (except when bridging is necessary)
• Deep Swift concurrency patterns (actors, Sendable, etc.) — use .task for SwiftUI async work when needed

2. No Code Formatting or Linting

Do not include formatting/linting rules. Avoid:

• Property ordering requirements (environment, state, body, etc.)
• Code organization mandates
• Whitespace or indentation rules
• Naming convention enforcement
• File structure requirements

Exception: Mention organization patterns as optional suggestions for readability, never as requirements.

3. No Architectural Opinions

Stick to facts, not architectures. Avoid:

• Enforcing MVVM, MVC, VIPER, or any specific architecture
• Mandating view model patterns
• Requiring specific folder structures
• Dictating dependency injection patterns
• Prescribing router/coordinator patterns

Exception: Suggest separating business logic for testability without enforcing how.

4. No Tool-Specific Instructions

Agents cannot use external tools. Do not include:

• Xcode Instruments profiling instructions
• Debugging tool usage
• IDE-specific features
• Command-line tool usage beyond basic git

Exception: Mention that users can profile with Instruments if performance issues arise, but don't provide detailed instructions.

Content Guidelines

Suggestions vs Requirements

Use "suggest" or "consider" for optional optimizations:

• ✅ "Consider downsampling images when using UIImage(data:)"
• ❌ "Always downsample images"

Use "always" or "never" only for correctness issues:

• ✅ "Never use .indices for dynamic ForEach content"
• ✅ "Always mark @State as private"

Performance Optimizations

Present performance optimizations as optional improvements:

• Image downsampling: Suggest when UIImage(data:) is encountered
• POD view wrappers: Mention as advanced optimization technique
• Equatable conformance: Suggest for expensive views