swift-code-reviewer

Category: Development & Coding | Uploader: Viniciuscarvalho | Downloads: 0 | Version: v1.0（Latest）
Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, security, and adherence to Swift 6+ best practices, SwiftUI patterns, navigation architecture, sheet routing, theming, async state, iOS/macOS platform guidelines, and project-specific coding standards from .claude/CLAUDE.md. Use when reviewing code changes, performing quality audits, or providing structured feedback on Swift codebases with all severity levels and positive feedback.
Changelog: Source: GitHub https://github.com/Viniciuscarvalho/swift-code-reviewer-skill
Directory Structure

Current level: Root
📁 .github/
- 📄 FUNDING.yml 25 B
📁 assets/
- 📄 demo.png 280.9 KB
📁 bin/
- 📄 install.js 4.9 KB
📁 references/
- 📄 architecture-patterns.md 28.3 KB
- 📄 custom-guidelines.md 17.9 KB
- 📄 feedback-templates.md 15.1 KB
- 📄 performance-review.md 23.9 KB
- 📄 review-workflow.md 30.2 KB
- 📄 security-checklist.md 19.6 KB
- 📄 swift-quality-checklist.md 20.1 KB
- 📄 swiftui-review-checklist.md 40.9 KB
📄 .gitignore 433 B
📄 .npmignore 109 B
📄 CHANGELOG.md 7.2 KB
📄 CONTRIBUTING.md 6.9 KB
📄 LICENSE 1.1 KB
📄 package.json 936 B
📄 README.md 5.2 KB
📄 SKILL.md 21.9 KB
SKILL.md

---
name: swift-code-reviewer
description: Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, security, and adherence to Swift 6+ best practices, SwiftUI patterns, navigation architecture, sheet routing, theming, async state, iOS/macOS platform guidelines, and project-specific coding standards from .claude/CLAUDE.md. Use when reviewing code changes, performing quality audits, or providing structured feedback on Swift codebases with all severity levels and positive feedback.
---

# Swift/SwiftUI Code Review Skill

## Overview

This skill provides comprehensive code review capabilities for Swift and SwiftUI projects, combining Apple's best practices with project-specific coding standards. It performs multi-layer analysis covering code quality, architecture, performance, security, and maintainability.

### Key Capabilities

- **Project-Aware Reviews**: Reads `.claude/CLAUDE.md` and related architecture documents to validate against project-specific standards
- **Multi-Layer Analysis**: Combines Swift 6+ best practices, SwiftUI patterns, performance optimization, and security checks
- **Comprehensive Feedback**: Provides Critical/High/Medium/Low severity issues, positive feedback, and refactoring suggestions
- **Integration with Existing Skills**: Leverages `swift-best-practices`, `swiftui-expert-skill`, and `swiftui-performance-audit` for domain expertise
- **Actionable Output**: Structured feedback with file:line references, code examples, and prioritized action items

## When to Use This Skill

Use this skill when you need to:

- Review Pull Requests or Merge Requests for Swift/SwiftUI projects
- Perform code quality audits on existing codebases
- Validate code changes against project-specific standards
- Analyze individual Swift/SwiftUI files for best practices
- Review uncommitted git changes before committing
- Assess architecture and maintainability of Swift code
- Provide structured feedback to team members

**Trigger patterns:**
- "Review this PR"
- "Review [filename].swift"
- "Review my changes"
- "Code review for [component]"
- "Check if this follows our coding standards"
- "Review against .claude/CLAUDE.md"

## Review Workflow

The skill follows a **four-phase workflow** to ensure comprehensive and actionable feedback:

### Phase 1: Context Gathering

**Objective**: Understand the project context and scope of review

1. **Read Project Guidelines**
   - Load `.claude/CLAUDE.md` if it exists in the repository
   - Read related architecture documents (e.g., `DependencyInjection-Architecture.md`, `Design System Structure.md`)
   - Extract custom coding standards, patterns, and rules

2. **Identify Review Scope**
   - Determine files to review:
     - User-specified files
     - Git diff (uncommitted or PR/MR changes)
     - Modified files in a specific directory
   - Categorize changes by type (UI, logic, tests, configuration)

3. **Gather File Context**
   - Read all files that will be reviewed
   - Understand the broader context (related files, dependencies)
   - Identify the purpose and role of each component

### Phase 2: Automated Analysis

**Objective**: Run parallel checks across multiple quality dimensions

Execute checks across **six core categories**:

#### 1. Swift Best Practices
Reference: `swift-best-practices` skill knowledge base

- **Concurrency Safety**
  - Actor isolation correctness
  - MainActor usage for UI code
  - Sendable conformance
  - Data race prevention
  - Async/await patterns

- **API Design**
  - Naming conventions (Swift API Design Guidelines)
  - Parameter labels clarity
  - Return type appropriateness
  - Error handling (typed throws)

- **Language Features**
  - Availability attributes for new APIs
  - Migration to Swift 6 features
  - Avoiding deprecated patterns
  - Proper use of optionals

#### 2. SwiftUI Quality
Reference: `swiftui-expert-skill` knowledge base

- **State Management**
  - Correct property wrapper selection (@Observable, @State, @Binding, @Environment)
  - State ownership and data flow
  - Avoiding unnecessary state
  - View model patterns

- **Modern API Usage**
  - Replace deprecated APIs with modern equivalents
  - Use latest SwiftUI features (iOS 17+, macOS 14+)
  - Proper use of view modifiers
  - Composition over inheritance

- **View Composition**
  - View extraction appropriateness
  - Component reusability
  - View hierarchy depth
  - Subview organization

- **Accessibility**
  - Accessibility labels and hints
  - VoiceOver support
  - Dynamic Type support
  - Keyboard navigation

#### 3. Performance
Reference: `swiftui-performance-audit` knowledge base

- **View Optimization**
  - Unnecessary view updates
  - Heavy computation in body
  - Equatable conformance for view models
  - Lazy loading patterns

- **List Performance**
  - ForEach identity stability
  - Cell reuse patterns
  - Scroll performance
  - Large dataset handling

- **Layout Efficiency**
  - Layout thrash detection
  - GeometryReader overuse
  - Frame calculations
  - Animation performance

- **Resource Management**
  - Image loading and caching
  - Memory leaks (retain cycles)
  - Background task management
  - Network request optimization

#### 4. Security & Safety

- **Data Validation**
  - Input sanitization
  - Type safety
  - Boundary checking
  - Force unwrap audit (avoid `!` and `as!`)

- **Sensitive Data Handling**
  - Password and token management
  - Keychain usage for credentials
  - Secure data transmission
  - Log sanitization (no sensitive data in logs)

- **Platform Security**
  - Permission handling (camera, location, etc.)
  - Network security (TLS, certificate pinning)
  - Secure storage (UserDefaults vs Keychain)
  - Code signing and entitlements

#### 5. Architecture & Maintainability

- **Project Architecture Compliance**
  - Adherence to defined patterns (MVVM, MVI, TCA, etc.)
  - Layer separation (View/ViewModel/Repository/UseCase)
  - Dependency injection patterns
  - Module boundaries

- **Code Organization**
  - File structure and naming
  - Logical grouping
  - Extension organization
  - Protocol conformances

- **Testability**
  - Unit test coverage
  - Test structure (Arrange-Act-Assert)
  - Mock/stub usage
  - Test isolation

- **Documentation**
  - DocC comments for public APIs
  - Complex logic explanations
  - Architecture decision records
  - README and guides

#### 6. Project-Specific Standards

- **Custom Coding Standards**
  - Validate against `.claude/CLAUDE.md` rules
  - Check custom error handling patterns
  - Verify project-specific naming conventions
  - Validate testing requirements

- **Design System Compliance**
  - Use of design tokens
  - Consistent spacing and typography
  - Color palette adherence
  - Component library usage

- **Navigation Patterns**
  - Coordinator pattern compliance
  - Deep linking support
  - State restoration
  - Navigation flow consistency

### Phase 3: Report Generation

**Objective**: Aggregate findings into a structured, actionable report

1. **Categorize Findings by Severity**
   - **Critical**: Security vulnerabilities, data races, crashes, breaking changes
   - **High**: Performance issues, anti-patterns, major architecture violations
   - **Medium**: Code quality improvements, missing documentation, minor violations
   - **Low**: Style inconsistencies, suggestions for refactoring

2. **Include Positive Feedback**
   - Acknowledge good practices and patterns
   - Highlight excellent code quality
   - Recognize proper use of modern APIs
   - Note strong architecture decisions

3. **Add Refactoring Suggestions**
   - Proactive improvement opportunities
   - Modernization suggestions
   - Code simplification ideas
   - Performance optimization hints

4. **Group and Organize**
   - Group by file, then by category
   - Sort by severity within each file
   - Include code location references (file:line)
   - Provide specific code examples

### Phase 4: Delivery

**Objective**: Present findings in a clear, actionable format

1. **Format as Structured Markdown**
   - Executive summary with key metrics
   - Severity breakdown
   - File-by-file detailed findings
   - Positive feedback section
   - Prioritized action items

2. **Include Code References**
   - Exact file and line numbers (file.swift:123)
   - Before/after code examples
   - Links to relevant documentation
   - Comparison with project guidelines

3. **Provide Context**
   - Explain *why* something is an issue
   - Reference best practices or standards
   - Suggest specific fixes with examples
   - Link to learning resources

## Core Review Categories

### 1. Swift Language Quality

**What to Check:**
- Concurrency patterns (actors, async/await, Sendable)
- Error handling (typed throws, Result type)
- Optionals handling (avoid force unwrapping)
- Access control (public, internal, private, fileprivate)
- Naming conventions (Swift API Design Guidelines)
- Type inference vs explicit types
- Value types vs reference types

**Reference:** `references/swift-quality-checklist.md`

### 2. SwiftUI Patterns

**What to Check:**
- Property wrapper selection and usage
- State management patterns
- View lifecycle understanding
- Modern API usage (avoid deprecated)
- View composition and extraction
- Accessibility implementation
- Preview configurations

**Reference:** `references/swiftui-review-checklist.md`

### 3. Performance Optimization

**What to Check:**
- View update optimization
- ForEach identity and performance
- Heavy work in view body
- Image loading and caching
- Memory management
- Background task efficiency
- Layout performance

**Reference:** `references/performance-review.md`

### 4. Security & Safety

**What to Check:**
- Force unwrap detection (`!`, `as!`, `try!`)
- Input validation and sanitization
- Sensitive data handling (passwords, tokens)
- Keychain usage for credentials
- Network security (HTTPS, certificate pinning)
- Permission handling
- Logging safety (no sensitive data in logs)

**Reference:** `references/security-checklist.md`

### 5. Architecture & Design

**What to Check:**
- MVVM, MVI, TCA, or other architecture compliance
- Dependency injection patterns
- Separation of concerns
- Module boundaries
- Code organization
- Testability
- Documentation quality

**Reference:** `references/architecture-patterns.md`

### 6. Project-Specific Standards

**What to Check:**
- `.claude/CLAUDE.md` compliance
- Custom architecture patterns
- Design system usage
- Navigation patterns
- Error handling standards
- Testing requirements

**Reference:** `references/custom-guidelines.md`

## Integration with Existing Skills

This skill **references** (not duplicates) three foundational skills for domain expertise:

### 1. swift-best-practices
**When to Use:** Reviewing Swift language usage, concurrency patterns, API design, or Swift 6+ migration

**What it Provides:**
- Swift 6+ concurrency patterns (actors, async/await, Sendable)
- API design guidelines compliance
- Availability pattern validation
- Breaking changes detection
- Modern Swift feature adoption

**How to Leverage:**
- Read `~/.claude/skills/swift-best-practices/references/concurrency.md` for concurrency checks
- Reference `swift6-features.md` for Swift 6 migration patterns
- Use `api-design.md` for naming and parameter validation

### 2. swiftui-expert-skill
**When to Use:** Reviewing SwiftUI views, state management, or UI code

**What it Provides:**
- State management patterns (@Observable, @State, @Binding)
- Modern SwiftUI API guidance (iOS 17+, macOS 14+)
- View composition best practices
- Property wrapper selection guide
- Accessibility patterns

**How to Leverage:**
- Read `~/.claude/skills/swiftui-expert-skill/references/state-management.md` for property wrapper checks
- Reference `modern-apis.md` for deprecation detection
- Use `view-composition.md` for component structure validation

### 3. swiftui-performance-audit
**When to Use:** Performance concerns identified or mentioned in PR description

**What it Provides:**
- View update optimization patterns
- ForEach performance analysis
- Layout thrash detection
- Image handling best practices
- Memory management

**How to Leverage:**
- Read `~/.claude/skills/swiftui-performance-audit/SKILL.md` for performance audit workflow
- Reference performance-specific checks when reviewing view code
- Apply recommendations from the skill to performance-sensitive paths

### 4. swiftui-ui-patterns
**When to Use:** Reviewing navigation architecture, sheet/modal routing, TabView setup, theming, async state management, focus handling, or API client patterns

**What it Provides:**
- Navigation architecture (route enums, RouterPath, centralized navigationDestination)
- Sheet/modal routing (item-driven sheets, SheetDestination enum)
- TabView with independent per-tab navigation history
- Theming with semantic colors via `@Environment(Theme.self)`
- Async state patterns (`.task(id:)`, LoadState enum, CancellationError handling)
- Focus chaining with FocusField enum and `.onSubmit`
- Lightweight API client pattern (closure-based structs, `.live()` / `.mock()` factories)

**How to Leverage:**
- Read `~/.claude/skills/swiftui-ui-patterns/references/navigation.md` for route enum and RouterPath checks
- Reference `sheets-modals.md` for sheet routing validation
- Use `theming.md` for semantic color enforcement

**Integration Strategy:**
1. Load relevant reference files from these skills as needed
2. Apply their checklist items to the review
3. Reference their documentation in feedback
4. Avoid duplicating content—point to their knowledge base

## Platform Support

### GitHub Pull Requests
Use `gh` CLI for fetching PR data:

```bash
# Get PR details
gh pr view <PR-number>

# Get PR diff
gh pr diff <PR-number>

# List PR files
gh pr view <PR-number> --json files

# Get PR comments
gh pr view <PR-number> --json comments
```

### GitLab Merge Requests
Use `glab` CLI for fetching MR data:

```bash
# Get MR details
glab mr view <MR-number>

# Get MR diff
glab mr diff <MR-number>

# List MR files
glab mr view <MR-number> --json

# Get MR comments
glab mr note list <MR-number>
```

### Local Git Changes
For uncommitted changes or manual review:

```bash
# Get uncommitted changes
git diff

# Get staged changes
git diff --cached

# Get changes in specific files
git diff -- path/to/file.swift

# Get commit diff
git show <commit-hash>
```

## Output Format

The review report follows this structure:

```markdown
# Code Review Report

## Summary
- **Files Reviewed**: X
- **Total Findings**: Y
- **Critical**: 0
- **High**: 2
- **Medium**: 5
- **Low**: 3
- **Positive Feedback**: 8
- **Refactoring Suggestions**: 4

## Executive Summary
[Brief overview of the changes and overall code quality]

---

## Detailed Findings

### File: Sources/Features/Login/LoginView.swift

#### ✅ Positive Feedback
1. **Excellent State Management** (line 23)
   - Proper use of @Observable for view model
   - Clean separation of concerns

2. **Modern API Usage** (line 45)
   - Using new SwiftUI APIs effectively
   - Proper async/await integration

#### 🔴 Critical Issues
1. **Data Race Risk** (line 67)
   - **Severity**: Critical
   - **Category**: Concurrency
   - **Issue**: Mutable state accessed from multiple actors without synchronization
   - **Fix**:
     ```swift
     // Before
     class LoginViewModel {
         var isLoading = false
     }

     // After
     @MainActor
     class LoginViewModel: ObservableObject {
         @Published var isLoading = false
     }
     ```
   - **Reference**: swift-best-practices/references/concurrency.md

#### 🟡 High Priority
1. **Force Unwrap Detected** (line 89)
   - **Severity**: High
   - **Category**: Safety
   - **Issue**: Force unwrapping optional can cause crash
   - **Fix**:
     ```swift
     // Before
     let user = fetchUser()!

     // After
     guard let user = fetchUser() else {
         logger.error("Failed to fetch user")
         return
     }
     ```
   - **Reference**: Project coding standard (.claude/CLAUDE.md:45)

#### 💡 Refactoring Suggestions
1. **Extract Subview** (lines 120-150)
   - Consider extracting login form into separate view
   - Improves testability and reusability

---

## Prioritized Action Items

### Must Fix (Critical/High)
1. [ ] Fix data race in LoginViewModel.swift:67
2. [ ] Remove force unwrap in LoginView.swift:89

### Should Fix (Medium)
1. [ ] Add documentation to public APIs
2. [ ] Improve error handling in NetworkService.swift

### Consider (Low)
1. [ ] Refactor login form into separate view
2. [ ] Add more unit tests for edge cases

---

## Positive Patterns Observed
- Excellent use of @Observable for state management
- Consistent adherence to project architecture (MVVM)
- Comprehensive accessibility support
- Strong error handling in most areas
- Good test coverage for core functionality

## References
- [Swift Best Practices](~/.claude/skills/swift-best-practices/SKILL.md)
- [SwiftUI Expert Guide](~/.claude/skills/swiftui-expert-skill/SKILL.md)
- [Project Coding Standards](.claude/CLAUDE.md)
```

## How to Use

### Example 1: Review Specific File
```
User: "Review UserProfileView.swift"

Steps:
1. Read .claude/CLAUDE.md for project standards
2. Read UserProfileView.swift
3. Run multi-layer analysis
4. Provide structured feedback with severity levels and positive feedback
```

### Example 2: Review Git Changes
```
User: "Review my uncommitted changes"

Steps:
1. Read .claude/CLAUDE.md
2. Execute `git diff` to get changes
3. Identify modified files
4. Run analysis on each file
5. Generate comprehensive review report
```

### Example 3: Review Pull Request
```
User: "Review PR #123"

Steps:
1. Read .claude/CLAUDE.md
2. Execute `gh pr view 123` and `gh pr diff 123`
3. Identify changed files
4. Read affected files for context
5. Run multi-layer analysis
6. Generate report with file:line references
```

### Example 4: Review Against Custom Guidelines
```
User: "Review LoginViewModel.swift against our coding standards"

Steps:
1. Read .claude/CLAUDE.md
2. Read related docs (DependencyInjection-Architecture.md)
3. Read LoginViewModel.swift
4. Validate against project-specific patterns
5. Provide detailed feedback comparing with standards
```

### Example 5: Review Multiple Files
```
User: "Review all ViewModels in the Features folder"

Steps:
1. Read .claude/CLAUDE.md
2. Find all *ViewModel.swift files in Features/
3. Analyze each against architecture patterns
4. Provide file-by-file review
5. Summarize common patterns and issues across all files
```

### Example 6: Review Navigation / Routing Code
```
User: "Review our navigation setup and routing code"

Steps:
1. Read .claude/CLAUDE.md for project navigation patterns
2. Read router/coordinator files (RouterPath, AppCoordinator, TabRouter)
3. Read root views that set up NavigationStack and TabView
4. Run navigation architecture checks:
   - Route destinations use typed Hashable enum (not String/Int)
   - RouterPath @Observable owns path (not ad-hoc @State)
   - Single centralized .navigationDestination per stack
   - .sheet(item:) preferred over .sheet(isPresented:) when model selected
   - Multiple sheets use SheetDestination enum (not multiple booleans)
   - Each tab has independent RouterPath (not shared)
   - .onOpenURL at app root, not scattered in feature views
5. Run async state checks:
   - .task(id:) for input-driven async work
   - CancellationError silenced
   - LoadState<T> enum instead of multiple booleans
6. Generate report with navigation-specific findings
```

## Resources

This skill includes the following reference materials:

### Core References
- **review-workflow.md**: Detailed step-by-step review process, git commands, and diff parsing strategies
- **feedback-templates.md**: Templates for positive/negative comments, severity classification guidelines

### Quality Checklists
- **swift-quality-checklist.md**: Swift 6+ concurrency, error handling, optionals, access control, naming
- **swiftui-review-checklist.md**: Property wrappers, state management, modern APIs, view composition
- **performance-review.md**: View updates, ForEach optimization, layout efficiency, resource management
- **security-checklist.md**: Input validation, sensitive data, keychain, network security

### Architecture & Customization
- **architecture-patterns.md**: MVVM, MVI, TCA patterns, dependency injection, testing strategies
- **custom-guidelines.md**: How to read and parse .claude/CLAUDE.md and project-specific standards

## Best Practices

1. **Always Read Project Guidelines First**
   - Load `.claude/CLAUDE.md` before starting review
   - Understand project-specific patterns and rules
   - Merge project standards with Apple guidelines

2. **Provide Balanced Feedback**
   - Include positive feedback for good practices
   - Don't just criticize—acknowledge what's done well
   - Suggest improvements, not just problems

3. **Be Specific and Actionable**
   - Include exact file:line references
   - Provide code examples for fixes
   - Explain *why* something is an issue
   - Link to relevant documentation

4. **Prioritize by Severity**
   - Critical: Must fix before merge (security, crashes, data races)
   - High: Should fix before merge (anti-patterns, performance issues)
   - Medium: Address soon (code quality, documentation)
   - Low: Consider for future (style, refactoring suggestions)

5. **Leverage Existing Skills**
   - Reference swift-best-practices for language patterns
   - Use swiftui-expert-skill for UI code
   - Apply swiftui-performance-audit for performance concerns
   - Don't duplicate their content—point to their knowledge

6. **Focus on Education**
   - Explain the reasoning behind feedback
   - Link to learning resources
   - Help developers understand best practices
   - Foster continuous improvement

## Limitations

- Cannot execute code or run tests (can only analyze statically)
- Cannot access external systems or APIs
- Limited to analyzing code provided or accessible via git
- Cannot detect runtime issues that require execution
- Performance analysis is based on patterns, not profiling data

For runtime analysis, recommend using Instruments or other profiling tools.

## Version

**Version**: 1.1.0
**Last Updated**: 2026-03-16
**Compatible with**: Swift 6+, SwiftUI (iOS 17+, macOS 14+, watchOS 10+, tvOS 17+, visionOS 1+)
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
swift-code-reviewer

Directory Structure

SKILL.md

Report

Notice
