Skip to content

existential-birds/beagle / plugins/beagle-ios/skills/cloudkit-code-review

cloudkit-code-review

Verified

Reviews CloudKit code for container setup, record handling, subscriptions, and sharing patterns. Use when reviewing code with import CloudKit, CKContainer, CKRecord, CKShare, or CKSubscription.

FileKindSize
SKILL.mdskill md3.8 KB
references/container-setup.mdmarkdown3.8 KB
references/records.mdmarkdown4.6 KB
references/sharing.mdmarkdown5.8 KB
references/subscriptions.mdmarkdown5.5 KB

references/records.md

View on GitHub
# CloudKit Records

## CKRecord Basics

**Supported field types:**
- `String`, `NSNumber`, `Data`, `Date`, `CLLocation`
- `CKRecord.Reference` - links to other records
- `CKAsset` - binary files (images, audio, documents)
- Arrays of any above type (same-type elements only)

**Size limits:**
| Constraint | Limit |
|------------|-------|
| Single record (excluding assets) | 1 MB |
| Single asset | 250 MB (native) |
| Batch operations per request | ~400 records |

## CKRecord.Reference

```swift
// Child points to parent with cascade delete
let parentRef = CKRecord.Reference(recordID: parentRecord.recordID, action: .deleteSelf)
childRecord["parentRef"] = parentRef
```

**Actions:**
- `.deleteSelf` - Child deleted when parent deleted
- `.none` - Child becomes orphan when parent deleted

## CKAsset

```swift
let fileURL = getLocalFileURL()
let asset = CKAsset(fileURL: fileURL)
record["attachment"] = asset
```

Assets stored separately, don't count toward 1MB record limit.

## Critical Anti-Patterns

### 1. Storing Child Arrays in Parent

```swift
// BAD: Causes conflict resolution nightmares
let parentRecord = CKRecord(recordType: "Album")
parentRecord["photoIDs"] = photoIDs as CKRecordValue

// GOOD: Child references parent
let photoRecord = CKRecord(recordType: "Photo")
let albumRef = CKRecord.Reference(recordID: albumRecord.recordID, action: .deleteSelf)
photoRecord["album"] = albumRef
```

### 2. Ignoring Errors

```swift
// BAD
database.save(record) { _, error in
    self.updateUI()  // Ignores error!
}

// GOOD
database.save(record) { _, error in
    if let error = error as? CKError {
        switch error.code {
        case .serverRecordChanged:
            self.resolveConflict(error: error)
        case .networkUnavailable, .networkFailure:
            if let retry = error.userInfo[CKErrorRetryAfterKey] as? Double {
                DispatchQueue.main.asyncAfter(deadline: .now() + retry) {
                    self.retrySave(record)
                }
            }
        default:
            self.handleError(error)
        }
        return
    }
    DispatchQueue.main.async { self.updateUI() }
}
```

### 3. String Literals for Keys

```swift
// BAD: Typos won't be caught
record["titel"] = title

// GOOD: Type-safe keys
enum RecordKeys: String {
    case title, createdAt, category
}
record[RecordKeys.title.rawValue] = title
```

### 4. Individual Saves Instead of Batch

```swift
// BAD: Separate network call for each record
for record in records {
    database.save(record) { _, _ in }
}

// GOOD: Single batch operation
let operation = CKModifyRecordsOperation(recordsToSave: records, recordIDsToDelete: nil)
operation.modifyRecordsResultBlock = { result in }
database.add(operation)
```

### 5. Exceeding Record Size

```swift
// BAD: May exceed 1MB limit
record["imageData"] = largeImageData as CKRecordValue

// GOOD: Use CKAsset for binary data
let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("temp.jpg")
try imageData.write(to: tempURL)
record["image"] = CKAsset(fileURL: tempURL)
```

### 6. UI Updates on Background Thread

```swift
// BAD: CloudKit callbacks are on background thread
database.fetch(withRecordID: recordID) { record, error in
    self.titleLabel.text = record?["title"] as? String  // Crash!
}

// GOOD
database.fetch(withRecordID: recordID) { record, error in
    DispatchQueue.main.async {
        self.titleLabel.text = record?["title"] as? String
    }
}
```

### 7. Downloading All Fields

```swift
// BAD: Downloads everything including large assets
let query = CKQuery(recordType: "Photo", predicate: predicate)
database.perform(query, inZoneWith: nil) { records, error in }

// GOOD: Only fetch needed fields
let operation = CKQueryOperation(query: query)
operation.desiredKeys = ["title", "timestamp"]
database.add(operation)
```

## Error Handling Table

| Error Code | Common Mistake | Correct Handling |
|------------|----------------|------------------|
| `partialFailure` | Treat as complete failure | Parse `partialErrorsByItemID` |
| `serverRecordChanged` | Retry with client record | Merge using server record from error |
| `requestRateLimited` | Immediate retry | Use `retryAfterSeconds` |
| `limitExceeded` | Fail operation | Split batch and retry |
| `quotaExceeded` | Silent failure | Alert user |

## Review Questions

1. Are custom record IDs used that match local storage identifiers?
2. Is record data under 1MB with large files as CKAssets?
3. Are relationships using back-references (child->parent) not arrays?
4. Is `.deleteSelf` used appropriately for cascade delete needs?
5. Are all CloudKit callbacks dispatching UI updates to main thread?
6. Is `desiredKeys` specified to avoid downloading unnecessary data?
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall