> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI-Assisted Development

> Build faster with Claude Code, Xcode Coding Intelligence, Cursor AI, and Bolt AI. Pre-configured CLAUDE.md, .cursor rules, and .bolt chat modes included.

SwiftAI Boilerplate Pro ships with configurations for Claude-powered iOS development across **Claude Code**, **Xcode Coding Intelligence**, **Cursor AI**, and **Bolt AI**. Each setup points the assistant at the same project architecture so generated code fits the boilerplate instead of guessing.

No setup required. Open the project and start building.

<Note>
  Building a separate app from this template? The **App Generator** is a standalone macOS product (coming soon) that drives your own coding-agent CLI to scaffold a differentiated, App Store Guideline 4.3-safe app from the boilerplate. See [Pricing & License](/pages/reference/license) for details and the waitlist.
</Note>

***

## Recommended Setup

For most SwiftAI Boilerplate Pro projects, start here:

<Steps>
  <Step title="Open the repository root">
    Open the folder that contains `AGENTS.md`, `SwiftAIBoilerplatePro.xcodeproj`, `Packages/`, and `docs/`. The root `AGENTS.md` is the shared entry point that points every agent at `docs/CLAUDE.md` and `docs/INDEX.md`.
  </Step>

  <Step title="Use Xcode Coding Intelligence for build-aware work">
    Xcode Coding Intelligence with Claude Agent is a strong fit for Swift apps because it can stay close to Xcode's project, build, simulator, and diagnostics workflow.
  </Step>

  <Step title="Use Claude Code for larger agentic changes">
    Claude Code is best when you want the agent to inspect many files, implement a full feature, run commands, and iterate until the project builds.
  </Step>

  <Step title="Use Cursor for focused editing">
    Cursor is useful for inline edits, local refactors, and reviewing generated code while you are already working in the editor.
  </Step>
</Steps>

<Tip>
  If Claude says it does not see the project instructions, ask it to summarize `docs/CLAUDE.md`. If it cannot, restart the agent from the repository root rather than from a subdirectory or a single file.
</Tip>

## Tool Comparison

| Tool                          | Best For                                                             | Project Context                                                              |
| ----------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Xcode Coding Intelligence** | Swift app work inside Xcode, build issues, simulator-aware iteration | Reads root `AGENTS.md` → `docs/CLAUDE.md` when started from the project root |
| **Claude Code**               | Larger autonomous coding tasks and verification loops                | Reads root `AGENTS.md`, which points to `docs/CLAUDE.md`                     |
| **Cursor AI**                 | Inline edits, refactors, and code review while editing               | Reads `.cursor/rules/*.mdc` (plus `AGENTS.md`)                               |
| **Bolt AI chat modes**        | Specialized chat personas and prompt-driven workflows                | Uses `.bolt/chat-modes.json` and project files you provide as context        |

***

## Claude Code and Claude Agent (`CLAUDE.md`)

The boilerplate includes a production-tested `docs/CLAUDE.md` that gives [Claude Code](https://claude.ai/code) full project context. A root `AGENTS.md` is the shared entry point all agents read first; it points Claude Code, Cursor, Codex, and others at `docs/CLAUDE.md` and `docs/INDEX.md`, so generated code fits the boilerplate from the first message.

### What CLAUDE.md Covers

* **Architecture:** MVVM patterns, module boundaries, which abstractions to use
* **Build commands:** Environment-aware instructions for Xcode MCP vs Claude Code CLI
* **Anti-patterns:** No UIKit, no ObservableObject, no raw URLSession
* **File conventions:** Naming patterns, organization, where new code belongs
* **Integration specifics:** Supabase, RevenueCat, OpenRouter configuration

### How Agentic Development Works

1. Open Claude Code in your project directory
2. Describe the feature you want
3. Claude reads your codebase, generates code following your patterns, builds it, and iterates until it works

Claude understands the module boundaries, uses the right abstractions, and writes code that looks like the rest of your project.

### Example Workflow

```text theme={null}
You: "Add a favorites feature. Users should be able to bookmark conversations
     and see them in a dedicated tab."

Claude Code:
  - Reads AGENTS.md / docs/CLAUDE.md and the existing module structure
  - Creates SwiftData model in Storage package
  - Adds FavoritesRepository with protocol
  - Builds FavoritesViewModel (@Observable) following MVVM pattern
  - Creates FavoritesView using DesignSystem tokens
  - Wires dependencies through CompositionRoot
  - Runs build to verify compilation
```

### Community Skills

You can extend Claude's iOS knowledge with community skills. These teach Claude about platform conventions, Xcode tooling, and SwiftUI best practices.

<CardGroup cols={2}>
  <Card title="Apple Platform Skills" icon="apple">
    Apple platform conventions, Xcode project structure, SwiftUI, and App Store review awareness.

    ```bash theme={null}
    git clone https://github.com/rshankras/claude-code-apple-skills.git
    mkdir -p .claude/skills
    cp -R claude-code-apple-skills/skills/* .claude/skills/
    ```

    Source: [rshankras/claude-code-apple-skills](https://github.com/rshankras/claude-code-apple-skills)
  </Card>

  <Card title="iOS Simulator" icon="mobile">
    Lets Claude boot, build, install, and interact with the iOS Simulator directly.

    ```text theme={null}
    /plugin marketplace add conorluddy/ios-simulator-skill
    /plugin install ios-simulator-skill@conorluddy
    ```

    Source: [conorluddy/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
  </Card>
</CardGroup>

Run `/plugin ...` commands inside Claude Code or Claude Agent chat. Run `git`, `cp`, and `npx` commands in your terminal. For the full list of recommended skills and module mappings, see the [Agentic Development Setup guide](/pages/guides/skills-setup).

***

## Cursor AI Rules (`.cursor/rules/`)

[Cursor AI](https://cursor.sh) reads `.mdc` (Markdown Code) files from your project to understand patterns and constraints. Six rule files are included.

### Included Rule Files

<CardGroup cols={2}>
  <Card title="core.mdc" icon="cube">
    **Applied to:** All Swift files

    File size limits (max 400 lines), MVVM patterns, dependency injection, error handling, Swift Concurrency, testing requirements.
  </Card>

  <Card title="swiftui-views.mdc" icon="mobile">
    **Applied to:** View files (`*View.swift`)

    View composition, state management, list optimization, navigation, form handling, accessibility.
  </Card>

  <Card title="architecture.mdc" icon="sitemap">
    **Applied to:** Repositories, Clients, Packages

    Modular package boundaries, protocol-based APIs, repository pattern, CompositionRoot, structured logging, test doubles.
  </Card>

  <Card title="design-system.mdc" icon="palette">
    **Applied to:** DesignSystem, AppShell

    DSColors tokens, DSTypography type scale, DSSpacing tokens, component library usage, theme consistency.
  </Card>

  <Card title="app-store-differentiation.mdc" icon="shield">
    **Applied to:** Swift, config, and Markdown files

    Guideline 4.3(a) differentiation (binary, metadata, concept), the `APP_STORE_4_3_HARDENING.md` checklist, and the FeatureChat to AI coupling when removing chat.
  </Card>

  <Card title="ios-platform-safety.mdc" icon="lock">
    **Applied to:** Swift, `Info.plist`, `PrivacyInfo.xcprivacy`

    Public APIs only, Swift 6 concurrency, permission strings and privacy manifests, StoreKit/IAP for digital goods, accessibility baselines, and secrets via the existing `HTTPClient` + xcconfig.
  </Card>
</CardGroup>

### How It Works

Open the project in Cursor. The rules load automatically. Ask Cursor to build something, and it follows your architecture.

```text theme={null}
You: "Create a new chat settings view"

Cursor generates code with:
  - DSColors, DSTypography, DSSpacing (DesignSystem tokens)   ✅
  - Protocol-based dependencies (testable)                    ✅
  - Under 400 lines (properly composed)                       ✅
  - Loading and error states                                  ✅
  - Accessibility labels                                       ✅
```

### Example Prompts

<AccordionGroup>
  <Accordion title="Creating Views">
    ```text theme={null}
    "Create a new settings view using DesignSystem components"
    "Add a profile page with avatar, name, email, and sign-out"
    "Build a subscription paywall with three tiers"
    ```

    Cursor will use DSColors for colors, DSTypography for type, DSSpacing for layout, and create a proper `@Observable` ViewModel with loading and error states.
  </Accordion>

  <Accordion title="Creating ViewModels">
    ```text theme={null}
    "Add a ProfileViewModel with user info and sign-out"
    "Create SettingsViewModel with theme switching"
    "Build ChatViewModel with message streaming"
    ```

    Cursor will mark ViewModels as `@MainActor @Observable`, inject dependencies via initializer, use protocol types, and add structured logging.
  </Accordion>

  <Accordion title="Creating Feature Packages">
    ```text theme={null}
    "Create a new feature package for Notifications"
    "Add a feature package for User Profile"
    ```

    Cursor will create proper Package.swift, define protocol-based public APIs, keep implementation internal, and add tests.
  </Accordion>

  <Accordion title="Refactoring">
    ```text theme={null}
    "Refactor this to use repository pattern"
    "Extract this logic to a separate package"
    "Convert this to use DesignSystem components"
    ```
  </Accordion>
</AccordionGroup>

***

## Bolt AI Chat Modes (`.bolt/`)

[Bolt AI](https://bolt.new) provides **12 specialized AI assistants** for different development tasks. Each mode loads relevant context and uses a domain-specific system prompt.

### Available Chat Modes

<CardGroup cols={3}>
  <Card title="iOS Developer" icon="code">
    `/dev` (default). General iOS/SwiftUI development with MVVM and async/await.
  </Card>

  <Card title="Architecture Advisor" icon="sitemap">
    `/arch`. Package boundaries, protocol-based APIs, clean architecture.
  </Card>

  <Card title="SwiftUI" icon="mobile">
    `/ui`. View composition, DesignSystem usage, state management, accessibility.
  </Card>

  <Card title="Feature Dev" icon="puzzle">
    `/feature`. Self-contained feature modules with protocol APIs and tests.
  </Card>

  <Card title="Integration" icon="plug">
    `/integration`. Supabase, RevenueCat, Firebase setup and troubleshooting.
  </Card>

  <Card title="Testing" icon="flask">
    `/test`. Unit tests, mock protocols, test doubles, async testing.
  </Card>

  <Card title="Debug" icon="bug">
    `/debug`. Bug diagnosis, crash analysis, memory leaks, performance.
  </Card>

  <Card title="Performance" icon="gauge">
    `/perf`. Memory management, lazy loading, rendering optimization.
  </Card>

  <Card title="Package Dev" icon="box">
    `/package`. Swift Package Manager, API design, dependencies.
  </Card>

  <Card title="Deploy" icon="rocket">
    `/deploy`. App Store submission, TestFlight, provisioning, CI/CD.
  </Card>

  <Card title="Accessibility" icon="universal-access">
    `/a11y`. VoiceOver, Dynamic Type, inclusive design, WCAG compliance.
  </Card>

  <Card title="Documentation" icon="book">
    `/doc`. Technical writing, API docs, integration guides.
  </Card>
</CardGroup>

***

## Before and After

Without configurations, AI generates code with hardcoded colors, no ViewModel, direct singleton dependencies, and no error handling. With configurations, the same prompt produces code that follows your architecture.

### Without Configurations

**Prompt:** "Create a user profile view with avatar and sign-out"

```swift theme={null}
struct ProfileView: View {
  @State var user: User?

  var body: some View {
    VStack {
      Image(systemName: "person.circle")
        .font(.system(size: 80))
        .foregroundColor(.blue)  // ❌ Hardcoded color

      Text(user?.name ?? "")
        .font(.title)  // ❌ Not from DesignSystem

      Button("Sign Out") {  // ❌ No error handling
        AuthManager.shared.signOut()  // ❌ Direct dependency
      }
      .padding()
      .background(Color.red)  // ❌ Hardcoded color
    }
  }
}
```

### With Configurations

**Same prompt**, same AI tool:

```swift theme={null}
import SwiftUI
import DesignSystem
import Auth
import Core

struct ProfileView: View {
  @State private var viewModel: ProfileViewModel

  var body: some View {
    ScrollView {
      VStack(spacing: DSSpacing.lg) {
        Circle()
          .fill(DSColors.primary)
          .frame(width: 80, height: 80)
          .overlay {
            Text(viewModel.user?.name?.prefix(1).uppercased() ?? "")
              .font(DSTypography.titleL)
              .foregroundStyle(.white)
          }

        VStack(spacing: DSSpacing.sm) {
          Text(viewModel.user?.name ?? "Loading...")
            .font(DSTypography.titleM)

          if let email = viewModel.user?.email {
            Text(email)
              .font(DSTypography.body)
              .foregroundStyle(DSColors.textSecondary)
          }
        }

        SAIButton("Sign Out", style: .secondary, layout: .block) {
          Task { await viewModel.signOut() }
        }
        .padding(.top, DSSpacing.lg)
      }
      .padding(DSSpacing.lg)
    }
    .navigationTitle("Profile")
    .alert("Error", isPresented: Binding(
      get: { viewModel.errorMessage != nil },
      set: { if !$0 { viewModel.errorMessage = nil } }
    )) {
      Button("OK") { viewModel.errorMessage = nil }
    } message: {
      Text(viewModel.errorMessage ?? "")
    }
    .task { await viewModel.load() }
  }
}

@MainActor
@Observable
final class ProfileViewModel {
  var user: AuthUser?
  var isLoading = false
  var errorMessage: String?

  private let authClient: any AuthClient

  init(authClient: any AuthClient) {
    self.authClient = authClient
  }

  func load() async {
    isLoading = true
    defer { isLoading = false }
    user = await authClient.currentUser()
  }

  func signOut() async {
    isLoading = true
    errorMessage = nil
    defer { isLoading = false }

    do {
      try await authClient.signOut()
      AppLogger.info("User signed out", category: AppLogger.auth)
    } catch {
      errorMessage = AppError.from(error).localizedUserMessage
      AppLogger.error("Sign out failed: \(error)", category: AppLogger.auth)
    }
  }
}
```

DesignSystem tokens, protocol-based dependencies, proper MVVM with `@Observable`, localized error handling, loading state, structured logging, `@MainActor`, async/await. All from the same one-line prompt.

***

## Customization

### Modifying Cursor Rules

Edit `.mdc` files in `.cursor/rules/`. Each file has YAML frontmatter (`description`, `globs`, `alwaysApply`) followed by markdown sections with good/bad code examples. Changes take effect when you save.

### Modifying CLAUDE.md

Edit `docs/CLAUDE.md` (or the root `AGENTS.md` entry point). Add your own patterns, anti-patterns, or module-specific instructions. Claude picks up changes on the next conversation.

### Adding Bolt Chat Modes

Edit `.bolt/chat-modes.json` to add custom modes:

```json theme={null}
{
  "chatModes": {
    "my-mode": {
      "name": "My Mode",
      "description": "What this mode does",
      "systemPrompt": "Instructions for AI",
      "context": ["paths/to/focus/on"],
      "tools": ["codeGeneration", "fileManagement"]
    }
  }
}
```

***

## Documentation

<CardGroup cols={2}>
  <Card title="Agentic Development Setup" icon="wand-magic-sparkles" href="/pages/guides/skills-setup">
    CLAUDE.md details and community skills
  </Card>

  <Card title="Cursor Rules README" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/.cursor/README.md">
    Detailed guide on Cursor AI rules
  </Card>

  <Card title="Architecture Guide" icon="sitemap" href="/pages/architecture">
    The patterns AI follows
  </Card>

  <Card title="DesignSystem Guide" icon="palette" href="/pages/modules/design-system">
    Design tokens reference
  </Card>
</CardGroup>

***

## Questions

<AccordionGroup>
  <Accordion title="Do I need Claude Code, Xcode Coding Intelligence, Cursor, or Bolt?">
    None of them are required. All are supported. **Xcode Coding Intelligence** is a great default for Swift work inside Xcode. **Claude Code** works best for agentic development, such as building full features from a description. **Cursor** works best for inline code generation while you edit. **Bolt** works best for chat-based task switching. Use whichever fits your workflow, or combine them.
  </Accordion>

  <Accordion title="Can I use other AI assistants?">
    Yes. The root `AGENTS.md` is read by most coding agents, and the patterns in `docs/CLAUDE.md` and the `.mdc` files work as reference for any AI tool. You can paste relevant sections into ChatGPT, Copilot, or any assistant that accepts context.
  </Accordion>

  <Accordion title="Will this slow down my development?">
    The opposite. AI configurations make code generation faster and more accurate because the AI gets it right the first time. Less time fixing, more time shipping.
  </Accordion>

  <Accordion title="Can I modify the configurations?">
    Yes. Edit `docs/CLAUDE.md` (or root `AGENTS.md`), `.cursor/rules/*.mdc`, or `.bolt/chat-modes.json` to match your preferences. Changes take effect immediately (Cursor, Bolt) or on the next conversation (Claude Code).
  </Accordion>

  <Accordion title="Do the rules apply to my manually-written code?">
    No. These configurations only guide AI code generation. They don't lint or enforce anything on code you write by hand.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Build Your First Feature" icon="hammer" href="/pages/guides/building-your-app">
    Use AI to build a feature with your project's patterns
  </Card>

  <Card title="Architecture Overview" icon="sitemap" href="/pages/architecture">
    Understand the patterns AI follows
  </Card>

  <Card title="Testing Guide" icon="flask" href="/pages/guides/testing">
    Let AI write tests for your features
  </Card>
</CardGroup>