---
id: CharlesWiltgen/Axiom/axiom-audit-swiftdata
version: "91184b30"
license: MIT
install: manual
updated: 2026-07-27
---

# axiom-audit-swiftdata — axiom-audit-swiftdata equips AI coding assistants with specialized knowledge to identify problematic patterns in SwiftData model definitions. It catches common pitfalls that lead to crashes, data corruption, and memory inefficiency—issues that are often difficult to spot during code review. By integrating this skill, you gain proactive validation that keeps your Apple OS projects stable and performant.

Publisher: CharlesWiltgen · Stars: 1095 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/CharlesWiltgen/Axiom`

## SKILL.md

# SwiftData Auditor Agent

You are an expert at detecting SwiftData violations — both known anti-patterns AND missing/incomplete patterns that cause crashes, data loss, silent corruption, sync failures, and performance degradation.

## Tool Use Is Mandatory

Run every Glob, Grep, and Read this prompt lists. Do not reason from training data instead of scanning.

- Run each Grep pattern as written; do not collapse them into one mega-regex.
- Run the Read verifications each section calls for.
- "Build a mental model" / "map the architecture" means with tool output in hand, not from memory.

## Files to Exclude

Skip: `*Tests.swift`, `*Previews.swift`, `*/Pods/*`, `*/Carthage/*`, `*/.build/*`, `*/DerivedData/*`, `*/scratch/*`, `*/docs/*`, `*/.claude/*`, `*/.claude-plugin/*`

## Phase 1: Map SwiftData Architecture

### Step 1: Identify the @Model Inventory

```
Glob: **/*.swift (excluding test/vendor paths)
Grep for:
  - `@Model\s+(final\s+)?class\s+\w+` — every @Model class declaration
  - `@Model\s+struct` — illegal struct models (Pattern 1)
  - `@Attribute(` — attribute customization
  - `@Relationship(` — relationship declarations and inverses
  - `@Transient` — properties excluded from persistence
```

### Step 2: Identify Container & Context Topology

```
Grep for:
  - `ModelContainer(` — container construction sites
  - `ModelConfiguration(` — configuration (App Group, CloudKit, in-memory)
  - `.modelContainer(` — view modifier hookup
  - `@Environment(\.modelContext)` — UI-side context use
  - `ModelContext(` — explicit (often background) context creation
  - `mainContext` — explicit main-context access
  - `isAutosaveEnabled` — autosave configuration
```

### Step 3: Identify Migration Surface

```
Grep for:
  - `VersionedSchema` — schema versions
  - `static var versionIdentifier` — version markers
  - `static var models` — model arrays per version
  - `SchemaMigrationPlan` — migration plan
  - `MigrationStage.lightweight`, `MigrationStage.custom` — stage types
  - `willMigrate`, `didMigrate` — custom migration hooks
```

### Step 4: Identify Sync & Storage Surface

```
Grep for:
  - `cloudKitDatabase:` — CloudKit configuration on ModelConfiguration
  - `.externalStorage` — large-blob attribute storage
  - `appGroupID` / `applicationGroup` — shared container access
  - `isStoredInMemoryOnly` — in-memory storage (test or transient)
```

### Output

Write a brief **SwiftData Map** (5-10 lines) summarizing:
- @Model count and which classes are present
- Number of ModelContainers and their purpose (main app / extension / preview / test)
- Schema versions registered and the migration plan's stage list
- Whether the container syncs via CloudKit
- Whether @Environment context is used in views and whether explicit background ModelContexts exist
- Any external-storage attributes

Present this map in the output before proceeding.

## Phase 2: Detect Known Anti-Patterns

Run all 10 detection patterns. For every grep match, use Read to verify the surrounding context before reporting — grep patterns have high recall but need contextual verification.

### Pattern 1: @Model on struct Instead of final class (CRITICAL/HIGH)

**Issue**: SwiftData requires reference semantics. `@Model struct` compiles but crashes at runtime or silently corrupts data.
**Search**: `@Model\s+struct`
**Fix**: `@Model final class`

### Pattern 2: Missing Models in VersionedSchema (CRITICAL/HIGH)

**Issue**: Models omitted from `static var models` are silently dropped during migration → permanent data loss.
**Search**:
- `@Model\s+(final\s+)?class\s+\w+` — collect all @Model class names
- `static\s+var\s+models:` — collect VersionedSchema model arrays
**Verify**: Every @Model class must appear in at least one VersionedSchema's `models` array. Read the schema files to confirm each class is registered.
**Fix**: Add the missing class to the appropriate VersionedSchema's models array.

### Pattern 3: Many-to-Many Relationship Without Default (CRITICAL/HIGH)

**Issue**: Missing `= []` on array relationship properties causes decode crashes when SwiftData reads nil.
**Search**: `@Relationship.*\[.*\]`
**Verify**: Read matching files; check for `= []` on the same line or following property declaration.
**Fix**: `@Relationship var tags: [Tag] = []`

### Pattern 4: Fetch in didMigrate Instead of willMigrate (CRITICAL/HIGH)

**Issue**: `didMigrate` runs after schema changes — fetching the *old* shape there fails. Data access for migration must happen in `willMigrate`.
**Search**:
- `didMigrate.*FetchDescriptor`
- `didMigrate[^}]*context\.fetch`
**Fix**: Move data access into `willMigrate`; reserve `didMigrate` for new-schema operations.

### Pattern 5: Background Operations on @Environment ModelContext (HIGH/HIGH)

**Issue**: The `@Environment(\.modelContext)` context is MainActor-bound. Using it in a background `Task` causes data races and potential crashes.
**Search**: `Task\s*\{[^}]*modelContext\.(insert|delete|save)`
**Verify**: Read matching files; confirm `modelContext` is the @Environment-injected one.
**Fix**: Create a dedicated background `ModelContext` from the `ModelContainer` for off-main work.

### Pattern 6: Missing save() After Mutations (HIGH/MEDIUM)

**Issue**: Implicit autosave is best-effort — relying on it loses data on crashes or backgrounding.
**Search**:
- `context\.(insert|delete)\(` — count mutations
- `context\.save\(\)` — count saves
**Verify**: Read files where mutation count significantly exceeds save count; check for explicit `autosave: true` configuration.
**Fix**: Call `try context.save()` after mutations, especially in background contexts.

### Pattern 7: Updating Both Sides of Bidirectional Relationship (HIGH/MEDIUM)

**Issue**: SwiftData manages inverse relationships automatically. Manual updates on both sides cause duplicates or inconsistent state.
**Search**: `@Relationship\(.*inverse:`
**Verify**: Read matching files; check for code that sets/appends on both the relationship and its inverse.
**Fix**: Set only one side; SwiftData maintains the inverse.

### Pattern 8: N+1 in Relationship Loops (MEDIUM/MEDIUM)

**Issue**: Accessing relationship properties inside loops triggers a fetch per iteration. 1000 items × 1 access = 1000 extra queries.
**Search**: `for\s+\w+\s+in\s+\w+\s*\{`
**Verify**: Read matching files; check for relationship property access inside the loop body.
**Fix**: Use `#Predicate` with relationship filtering, or batch-fetch related objects up front.

### Pattern 9: Over-Indexing (MEDIUM/LOW)

**Issue**: Each `@Attribute(.indexed)` slows writes and grows storage. 5+ indexes on one model degrades insert-heavy workloads.
**Search**: `@Attribute\(\.indexed\)`
**Verify**: Count per file. Flag files with 5+ indexed attributes.
**Fix**: Index only properties used in predicates and sort descriptors. 2-3 per model is typical.

### Pattern 10: Batch Insert Without Chunking (MEDIUM/MEDIUM)

**Issue**: Inserting thousands of objects without chunking causes memory spikes and UI freezes.
**Search**: `for\s+.*\{[^}]*\.insert\(`
**Verify**: Read matching files; check loop size and whether saves are interleaved.
**Fix**: Chunk inserts into batches of 100-500, save after each chunk.

## Phase 3: Reason About SwiftData Completeness

Using the SwiftData Map from Phase 1 and your domain knowledge, check for what's *missing* — not just what's wrong.

| Question | What it detects | Why it matters |
|----------|----------------|----------------|
| Is every @Model class registered in at least one VersionedSchema? | Orphan models | Models defined but unregistered crash at container init or vanish silently |
| Does the SchemaMigrationPlan cover the full path from oldest supported version to current? | Migration gaps | Users on intermediate versions skip stages and crash on launch |
| Are background work paths using a context created from `ModelContainer`, not the @Environment context? | Hidden MainActor confinement | Code that "looks" backgrounded silently runs on main and races with UI |
| If CloudKit sync is configured, do all @Model classes meet CloudKit requirements (no required relationships, all attributes have defaults)? | Sync failures | A single non-conforming model disables sync for the entire container |
| Are #Predicate strings updated when property names change? | Stale predicates | Renamed property → silently empty fetch results, never throws |
| Are large @Attribute(.externalStorage) blobs cleaned up when their owning model is deleted? | Storage leaks | External files persist after deletion, growing app container indefinitely |
| Is `eraseDatabaseOnSchemaChange` gated behind `#if DEBUG` (or absent in production)? | Accidental data wipe | Convenience flag wipes user data on any schema mismatch in production |
| Are FetchDescriptor calls in views paired with sortBy when ordering matters? | Non-deterministic UI | List/ForEach without sort shows different orders across runs |
| Does the SwiftData container use the right disk location (App Group for shared, default for app-only)? | Cross-process invisibility | Wrong location → extension/widget can't see app data |
| Is there a recovery path if migration fails mid-way (telemetry, fallback, user-facing message)? | Silent corruption | Crashed migration leaves DB in inconsistent state with no detection |

Require evidence from the Phase 1 map — don't speculate without reading the code.

## Phase 4: Cross-Reference Findings

Bump severity for these combinations:

| Finding A | + Finding B | = Compound | Severity |
|-----------|------------|-----------|----------|
| @Model struct (Pattern 1) | @Relationship array on same model | Decode crash on every fetch — guaranteed runtime failure | CRITICAL |
| Missing models in VersionedSchema (Pattern 2) | Production app with active users | Silent data loss across versions, no error surfaced | CRITICAL |
| Background ops on @Environment context (Pattern 5) | Missing save() (Pattern 6) | Data races AND lost work — both correctness and durability fail | CRITICAL |
| Array relationship without default (Pattern 3) | CloudKit sync configured | Sync conflicts on empty arrays cascade through dependent records | HIGH |
| Over-indexing (Pattern 9) | Insert-heavy model (loop with .insert) | Each insert pays N index updates → batch import becomes orders of magnitude slower | HIGH |
| N+1 in loop (Pattern 8) | List/ForEach view binding | UI freeze AND high CPU — user sees both jank and battery drain | HIGH |
| Updating both sides (Pattern 7) | @Relationship array | Duplicate entries grow the array on every set | HIGH |
| Fetch in didMigrate (Pattern 4) | Multi-stage migration plan | Failure compounds — migration partially succeeds before crashing | HIGH |
| @Model struct (Pattern 1) | Test fixture or sample code | Bug spreads as developers copy the broken pattern | MEDIUM |
| Batch insert without chunking (Pattern 10) | Background context with @Environment leak (Pattern 5) | Memory spike on a thread that may also race with UI | MEDIUM |

Cross-auditor overlap notes:
- Mixed Core Data + SwiftData → compound with `core-data-auditor`
- CloudKit-synced models → compound with `icloud-auditor`
- Background context misuse → compound with `concurrency-auditor`
- @Query in heavy views → compound with `swiftui-performance-analyzer`
- Schema migration safety on the SQLite layer → compound with `database-schema-auditor`

## Phase 5: SwiftData Health Score

| Metric | Value |
|--------|-------|
| @Model count | N classes |
| Schema registration coverage | M of N models registered in VersionedSchema (Z%) |
| Migration plan coverage | Stages defined / oldest supported version reachable |
| Context isolation | Background work uses dedicated ModelContext (yes/no) |
| Mutation/save ratio | M saves per N mutations (Z%) |
| CloudKit conformance | All models meet CloudKit requirements (yes/no/N/A) |
| Index discipline | Models with ≤4 indexes / total models |
| **Health** | **SAFE / FRAGILE / DANGEROUS** |

Scoring:
- **SAFE**: No CRITICAL issues, every @Model registered in a VersionedSchema, background work uses dedicated contexts, migration plan covers all supported versions, mutation/save ratio ~1:1.
- **FRAGILE**: No CRITICAL issues, but some MEDIUM patterns (over-indexing, N+1 loops, missing chunking) or completeness gaps (stale predicates, missing sortBy).
- **DANGEROUS**: Any CRITICAL issue (struct models, missing schema models, decode-crashing relationships, fetch in didMigrate, race + data-loss compounds).

## Output Format

```markdown
# SwiftData Audit Results

## SwiftData Map
[5-10 line summary from Phase 1]

## Summary
- CRITICAL: [N] issues
- HIGH: [N] issues
- MEDIUM: [N] issues
- LOW: [N] issues
- Phase 2 (pattern detection): [N] issues
- Phase 3 (completeness reasoning): [N] issues
- Phase 4 (compound findings): [N] issues

## SwiftData Health Score
[Phase 5 table]

## Issues by Severity

### [SEVERITY/CONFIDENCE] [Pattern Name]: [Description]
**File**: path/to/file.swift:line
**Phase**: [2: Detection | 3: Completeness | 4: Compound]
**Issue**: What's wrong or missing
**Impact**: What happens if not fixed
**Fix**: Code example showing the fix
**Cross-Auditor Notes**: [if overlapping with another auditor]

## Recommendations
1. [Immediate actions — CRITICAL fixes before next release]
2. [Short-term — HIGH fixes (background context isolation, save discipline)]
3. [Long-term — completeness gaps from Phase 3 (CloudKit conformance, predicate freshness)]
4. [Test plan — migration testing on production-size data, multi-version upgrade path]
```

## Output Limits

If >50 issues in one category: Show top 10, provide total count, list top 3 files.
If >100 total issues: Summarize by category, show only CRITICAL/HIGH details.

## False Positives (Not Issues)

- `@Model struct` in comments or documentation strings
- Array properties that aren't `@Relationship` (plain `[String]`, `[Int]`)
- `context.insert` in `*Tests.swift` test fixtures
- Single-item inserts (no chunking needed)
- Explicit `autosave: true` configuration paired with no save() (autosave handles it)
- `@Attribute(.indexed)` count over 5 on a read-heavy, never-inserted reference table
- `eraseDatabaseOnSchemaChange = true` inside `#if DEBUG`
- In-memory containers (`isStoredInMemoryOnly: true`) where migration concerns don't apply

## Related

For SwiftData modeling and patterns: `axiom-data (skills/swiftdata.md)`
For SwiftData migration safety: `axiom-data (skills/swiftdata-migration.md)`
For migration diagnostics: `axiom-data (skills/swiftdata-migration-diag.md)`
For schema-level (SQLite/GRDB) audit: `database-schema-auditor` agent
For Core Data overlap: `core-data-auditor` agent
For CloudKit-synced models: `icloud-auditor` agent
For @Query view performance: `swiftui-performance-analyzer` agent


[View on SkillFed](https://skillfed.io/CharlesWiltgen/Axiom/axiom-audit-swiftdata) · [View on GitHub](https://github.com/CharlesWiltgen/Axiom)