Cursor Rules for iOS: Swift, Xcode Projects, and Tests

Cursor rules for an iOS project tell the assistant how your app is structured, which Swift patterns are approved, how to handle Xcode project changes, and which test targets and commands to use. iOS development has strong platform conventions, but every app adds its own decisions on top: which navigation pattern to use, whether to write SwiftUI or UIKit, how to handle async operations, and which third-party libraries are in the project. Without rules, the assistant draws from the full range of iOS patterns it has seen. fenbs helps teams record the product constraints and implementation decisions that make those rules specific to their app, so every session starts from the same agreed foundation.

The templates below are starting points. Replace the target names, bundle identifiers, and framework names with your actual project values. Test each rule on a real file before adding it to your project rules, and remove any rule that conflicts with how your codebase actually works.

App structure and navigation

Whether your app uses UIKit, SwiftUI, or a mix of both is the first thing a rule should clarify. An assistant that mixes UIKit and SwiftUI navigation patterns in the same flow creates inconsistency that is difficult to untangle. A structure rule establishes the foundation before the assistant writes a single line.

This app uses SwiftUI throughout. Do not introduce UIKit components unless
working in files that already use UIKit.

Navigation:
- Use NavigationStack for all navigation (iOS 16+)
- Do not use NavigationView (deprecated)
- Scenes go in Features/; shared components in Components/
- View models go alongside their views in the same folder

Xcode project and build rules

Xcode project files are notoriously difficult to merge. An assistant that adds files to the wrong target or modifies the project.pbxproj incorrectly can break the build for everyone on the team. A rule that names which targets exist and how new files should be added prevents the most common mistakes.

Targets:
- YourApp: the main app target
- YourAppTests: unit tests
- YourAppUITests: UI tests

When adding a new file, add it to the correct target in Xcode — do not
modify project.pbxproj by hand unless there is no other way.
Minimum deployment target: iOS 16.0.
Do not add Swift packages without team approval.

Swift concurrency and async patterns

Swift's structured concurrency (async/await and actors) changed best practices significantly from the older completion handler and DispatchQueue patterns. A project may still have legacy code using the old patterns, or may have deliberately stayed on them for compatibility reasons. A rule about which approach to use prevents the assistant from mixing patterns in a way that creates retain cycles or callback nesting.

Concurrency:
- Use async/await for new code; do not introduce DispatchQueue.async for new functions
- Network calls go through NetworkService in Services/NetworkService.swift
- @MainActor for UI updates; avoid DispatchQueue.main.async in new code
- Existing completion handler code: do not rewrite unless it is in scope for the task

Platform API and permission rules

iOS platform APIs require explicit permission requests, and using them without the right entitlement or plist key causes a crash. A rule naming which permissions your app already has, and which ones are not approved, prevents the assistant from adding a feature that requires a permission you have not requested.

Permissions already declared in Info.plist:
- Camera: NSCameraUsageDescription
- Photo library: NSPhotoLibraryUsageDescription

Do not use: location, contacts, microphone, or any other permission
not listed above without explicit approval.
Do not add new keys to Info.plist without a task that authorizes it.

Test conventions

iOS testing has two distinct layers: unit tests for logic and UI tests for user flows. A rule that names your test targets, the frameworks in use, and the preferred test runner command keeps new test files consistent with existing ones.

Unit tests: YourAppTests target, XCTest framework
- Test class names: match the subject with Tests suffix (e.g., UserServiceTests)
- Use @testable import YourApp at the top of each test file

UI tests: YourAppUITests target
- Cover critical user flows only; keep UI tests minimal and maintainable

Run tests: xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'

How to do this with fenbs

1. Create a free account and add a project for your iOS app.
2. Add a skill or prompt for each rule area: app structure, Xcode conventions, concurrency, permissions, and tests. Keep them short and specific to your actual setup.
3. Record product constraints in Decisions and rules: the minimum iOS version and why, which permissions are approved and by whom, which third-party frameworks are in the project and which are not allowed.
4. When the team debates changing a pattern — moving from UIKit to SwiftUI, for example — record the open decision in fenbs and wait for sign-off before updating the rule files.
5. Connect your AI tools from Integrations so they read the current rules and decisions before starting work on the app.

What to leave out of a rule file

Rules handle coding conventions, not feature requirements. The fact that the app must support offline mode, or that a particular screen needs to meet accessibility guidelines, belongs in a task or project note, not in a rule file. Rule files should stay focused enough that an assistant can read them quickly and apply them consistently.

fenbs does not run xcodebuild or manage the Xcode project file. If the assistant changes something that affects the project structure, run the build yourself to verify it. The cursor rules for AI projects article has more on combining coding rules with project-level context.

A rule that mentions the Swift language version helps the assistant avoid suggesting syntax not available in your toolchain. Swift evolves rapidly, and features from a recent version look valid to the assistant even if your project's deployment target and Xcode version do not support them. If the project uses strict concurrency from Swift 6, or macros from Swift 5.9, naming the version in the rule gives the assistant the context it needs to generate compatible code.

When the team raises the minimum iOS version, review your rules for any conventions that existed to support older versions. A rule that says "avoid a certain API because it requires iOS 16" becomes misleading once the minimum is iOS 17. Outdated compatibility notes are worth removing promptly because they prevent the assistant from using APIs that are now safe to use unconditionally. A short review after each deployment target change keeps the rules accurate.