swift-code-reviewer

Swift/SwiftUI コードレビュースキル

Swift 6 以降の並行処理、SwiftUI のパターン、パフォーマンス、セキュリティ、アーキテクチャ、プロジェクト固有の規約を対象とする多層レビューです。.claude/CLAUDE.md を読み込み、file:line 形式の参照と、修正前後のコード例を添えて、Critical／High／Medium／Low の重要度で指摘事項を出力します。

このスキルを使用するタイミング

• 「この PR をレビューして」
• 「自分のコードをレビューして」／「変更をレビューして」／「未コミットの変更をレビューして」
• 「[コンポーネント] のコードレビュー」
• 「このコードベースを監査して」／「コード品質を確認して」
• 「.claude/CLAUDE.md に照らしてレビューして」／「コーディング規約に従っているか確認して」
• 「アーキテクチャレビュー」／「パフォーマンス監査」／「セキュリティレビュー」
• 「仕様に照らしてこの PR をレビューして」
• 「エージェントは issue #123 の見落としがありませんか？」
• 「この PR を踏まえて、CLAUDE.md に不足しているルールは何ですか？」
• 「この AI 生成 PR をレビューして」

ワークフロー

フェーズ 0 — 対象範囲の確定

目的：分析を始める前に、正規化された対象範囲オブジェクトを作成します。以降のすべてのフェーズはこのオブジェクトを参照し、各フェーズで変更セットを個別に取得することはありません。

モードの検出

以下のチェックを順番に実行し、最初に一致した時点で停止します。

優先度	条件	モード
1	ユーザーが PR 番号または URL を指定	PR — gh pr view <n> --json files,baseRefName
2	ユーザーが明示的にファイルパスを指定	File — 指定されたパス → scope.modified、検出をスキップ
3	gh pr view --json number が現在のブランチの結果を返す	PR（自動検出）
4	ユーザーの呼び出しに「staged」または「cached」が含まれる	Staged — git diff --cached --name-status
5	デフォルト	Local — git diff --name-status <base>...HEAD と git diff --name-status の和集合

ベースブランチの解決（PR の自動検出および Local モード用）：

# 1. PR metadata (authoritative when a PR exists)
gh pr view --json baseRefName --jq '.baseRefName'
# 2. Remote default branch
git rev-parse --abbrev-ref origin/HEAD
# 3. Last resort
git branch -r | grep -E 'origin/(main|master)$' | head -1

gh が利用できない、または認証されていない場合は、その旨を明確に伝え、Local にフォールバックします。

「gh が利用できません。origin/main を基準にローカルモードへフォールバックします。PR の対象範囲を完全に検出するには、gh auth login を実行してください。」

対象範囲オブジェクト

scope = {
  modified:         Set<Path>   // first-class findings — full file, all severity levels
  deleted:          Set<Path>   // spec-adherence reasoning only — skip per-file analysis loop
  testsForModified: Set<Path>   // coverage findings → main report; other findings → Adjacent Observations
  related:          Set<Path>   // read for context only — all findings → Adjacent Observations
}

modified と deleted の設定：

# PR mode
gh pr view <n> --json files --jq '.files[] | [.path, .status] | @tsv'
# Local / Staged
git diff --name-status <base>...HEAD

• ステータス M、A、C → scope.modified
• ステータス D → scope.deleted
• ステータス R（名前変更）→ 新しいパスを scope.modified に追加し、エージェントが変更されていない内容を新しいコードとして批評しないよう、古いパスを記録します。

testsForModified の設定：scope.modified の各パスについて：

1. テストツリー内の対応するパスを確認します。例：Features/Login/LoginViewModel.swift → Tests/Features/Login/LoginViewModelTests.swift
2. 見つからない場合は、同じディレクトリ内の *Tests.swift を検索します。
3. 見つかったパスのうちディスク上に存在するものを scope.testsForModified に追加します。

related の設定：フェーズ 1 で、エージェントがコンテキストを把握するためにインポートされたファイル、プロトコル宣言、親ビューを読み込む際に追加します。

対象外のパス — 最終確定の前に、すべての集合から除外します。

• Pods/**、Carthage/**、.build/**、DerivedData/**、.swiftpm/**
• *.generated.swift、*.pb.swift、R.generated.swift
• .claude/CLAUDE.md の review-excluded-paths ブロックにあるすべてのパターン

対象範囲のバナー（必須 — 指摘事項より前の最初の出力）

Scope: PR #123 · base: main · modified: 7 · tests-for-modified: 3 · deleted: 1 · related: 12

自動検出された PR の場合は、検出通知を先頭に追加します。

Detected open PR #123 (base: main). Run with --local to review uncommitted work instead.
Scope: PR #123 · base: main · modified: 7 · tests-for-modified: 3 · deleted: 1 · related: 12

ローカルモードの場合：

Scope: local (base: main) · modified: 4 (3 pushed, 1 uncommitted) · related: 8

対象範囲の適用

以下のルールは、フェーズ 1〜3 を通して適用されます。

• L1 — ファイル単位：scope.modified 内のファイルはすべて全体をレビューします。変更行だけでなく、すべての行が対象範囲です。
• O1 — 隔離：scope.modified の外にあるファイル（および scope.testsForModified のカバレッジ確認の対象外）に対する指摘は、レポート末尾の専用セクション 隣接する所見 に記載します。見出しは 「この PR の対象範囲外 — 別途チケットを作成してください。」 とします。
• 重要度の集計（Critical: N | High: N | …）には、対象範囲内の指摘のみを数えます。隣接する所見は含めません。

---

フェーズ 1 — コンテキストの収集

1. 仕様を読む
   • PR の場合：gh pr view <num> --json title,body,closingIssuesReferences,labels
   • 関連するイシューの場合：gh issue view <num> --json title,body,labels
   • MR の場合：glab mr view <num> および glab issue view <num>
   • 以下を抽出します：
     • 明示された目標／解決しようとしている問題
     • 明示的な受け入れ基準（チェックボックス、「should」、「must」、「Given/When/Then」を確認）
     • 言及されているエッジケースや対象外事項
     • スコープ外の項目
   • PR／イシューのコンテキストを利用できない場合は、その旨を記録し、差分から意図を推測します。
2. .claude/CLAUDE.md の読み込みを試みます。
   • 見つからない場合：レポートに "No project standards file found — review uses default Apple guidelines" という注記を追加してから、続行します。
3. Phase 0 の scope.modified を正式なファイル一覧として使用します。各ファイルの変更内容を把握するには：
   • PR モード：gh pr diff <n> -- <file>
   • ローカルモード：git diff <base>...HEAD -- <file>
   • Phase 0 の後に scope.modified が空の場合は、スコープのバナーを報告して終了し、指摘事項は記載しません。
4. scope.modified に含まれる各ファイルをすべて読みます。インポートされたファイル、プロトコル宣言、親ビュー、その他の依存関係を確認したら、それらを scope.related に追加します。これらのファイルは自由に読めますが、それらに関する指摘は「隣接する所見」に記載します。カバレッジ分析では、scope.testsForModified に含まれるテストファイルも読みます。

フェーズ 2 — 分析

各カテゴリについて、指摘を記述する前に参照ファイルを読み込みます：

0. 仕様への準拠

参照：references/spec-adherence.md

• 要件のカバレッジ
  • 各受け入れ基準に対応する具体的なコード変更がありますか？
  • 仕様で言及されているエッジケースに対応していますか？
  • scope.testsForModified のファイルでは、仕様に記載されたシナリオをテストで網羅していますか？カバレッジの不足は主レポートに記載します。それらのテストファイルで見つかったその他の問題は「隣接する所見」に記載します。
• スコープの遵守
  • 明示されたスコープ外の変更（スコープクリープ）を指摘します
  • PR に含まれている無関係なリファクタリングを指摘します
• 削除されたファイル：scope.deleted 内の各パスについて、その削除が仕様の要件を満たすか、違反するかを検討します。「要件のカバレッジ」表に含め、ファイルごとの分析ループはスキップします。
• 未完了の作業
  • TODO、fatalError("not implemented")、空の関数本体
  • 実際の実装に置き換えるべきスタブのモック
  • 対応する差分がない受け入れ基準
• 意図の乖離
  • コードが、明示された問題と似ているものの異なる問題を解決している
  • 命名や構造から、仕様とは異なる考え方がうかがえる

1. Swift の品質 — 並行処理、エラー処理、オプショナル、命名 → references/swift-quality-checklist.md。並行処理に関する指摘については、skills/swift-concurrency/references/sendable.md および actors.md も読みます
2. SwiftUI のパターン — プロパティラッパー、状態管理、非推奨 API → references/swiftui-review-checklist.md。ラッパーの選択については、skills/swiftui-expert-skill/references/state-management.md を読みます
3. パフォーマンス — ビュー本体のコスト、ForEach の識別性、遅延読み込み、保持サイクル → references/performance-review.md
4. セキュリティ — 強制アンラップ、UserDefaults と Keychain の使い分け、入力検証、ログへのシークレット記録の禁止 → references/security-checklist.md
5. アーキテクチャ — MVVM／MVI／TCA への準拠、DI、テスト容易性 → references/architecture-patterns.md
6. プロジェクト標準 — .claude/CLAUDE.md のルールへの準拠を確認 → references/custom-guidelines.md

テストファイルに関する指摘では、skills/swift-testing/references/test-organization.md を参照します。 ナビゲーション／ルーティングに関する指摘では、skills/swiftui-ui-patterns/references/navigationstack.md を参照します。

フェーズ 2.5 — パターン検出（エージェントループへのフィードバック）

目的：コードだけでなく、エージェントの指示に不足があることを示す、繰り返し発生する問題を特定します。

ファイルごとの指摘事項を収集したら、次のように集約します。

1. 指摘事項をルールごとにまとめます（例：「force-unwrap」、「非推奨の NavigationView」、「UI の変更に @MainActor がない」）。
2. 差分全体で 2 回以上 該当したルールを、繰り返し発生するパターンとして記録します。
3. 各パターンについて、.claude/CLAUDE.md またはエージェントのシステムプロンプトに適した、一行のルールを作成します。説明ではなく、指示として記述してください。
4. 過去のレビューでも同じパターンが繰り返し発生している場合（.claude/CLAUDE.md の git log を確認）、優先度を上げます。既存のルールが十分に強くないか、読まれていないことを示しています。

しきい値の根拠：1 回なら見落とし、2 回ならパターン、3 回以上ならエージェントの指示に記載がなく、明示的なルールが必要です。

参照：references/agent-loop-feedback.md。

フェーズ 3 — 報告

指摘事項をファイルごとにまとめ、各ファイル内で重大度順に並べ、優先順位を付けた対応項目を記述します。

重大度：Critical（クラッシュ／データ競合／セキュリティホール）・High（アンチパターン／アーキテクチャ上の重大な違反）・Medium（品質／保守性）・Low（スタイル／提案）。

コードが特に適切に書かれている場合は、一文で肯定的なフィードバックを含めます。ありきたりな褒め言葉で水増ししてはいけません。

具体的な指摘の例

強制アンラップ → guard let（Critical）

LoginViewModel.swift:89 — 現状：

let user = repository.currentUser!

指摘：currentUser が nil の場合（例：サインアウト時の競合状態の後）、クラッシュします。

修正：

guard let user = repository.currentUser else {
    logger.error("currentUser nil — aborting login flow")
    return
}

---

UI に関連付けられた ViewModel に @MainActor がない（High）

FeedViewModel.swift:12 — 現状：

class FeedViewModel: ObservableObject {
    @Published var posts: [Post] = []

    func load() async {
        posts = try? await api.fetchPosts()  // ⚠️ mutates @Published off main thread
    }
}

指摘：Swift 6 の厳格な並行処理では、@Published の変更はメインアクター上で行う必要があります。これはデータ競合です。

修正：

@MainActor
@Observable
final class FeedViewModel {
    var posts: [Post] = []

    func load() async throws {
        posts = try await api.fetchPosts()  // safe: whole class is @MainActor-isolated
    }
}

また、ObservableObject／@Published から @Observable（iOS 17 以降）に移行してください。skills/swiftui-expert-skill/references/state-management.md を参照してください。

出力形式

Scope: PR #123 · base: main · modified: 7 · tests-for-modified: 3 · deleted: 1 · related: 12

# Code Review — <scope>

## Summary
Files: N | Critical: N | High: N | Medium: N | Low: N

## Spec Adherence

**Source**: PR #123 / Issue #456

| Requirement | Status | Location |
|-------------|--------|----------|
| User can log in with email | ✅ Implemented | LoginView.swift:23 |
| Show error on invalid credentials | ⚠️ Partial — missing 401 case | LoginViewModel.swift:67 |
| Persist session in Keychain | ❌ Not implemented | — |
| Rate limit retries | ❌ Not implemented | — |

**Scope creep**: 1 unrelated change (UserSettings.swift refactor) — recommend
splitting into a separate PR.

---

## <Filename.swift>

[Severity] **<Category>** (line N)
Current: `<problematic snippet>`
Fix: <explanation + corrected snippet>

## Positive Observations
...

## Prioritized Action Items
- [Must fix] ...
- [Should fix] ...
- [Consider] ...

---

## Agent Loop Feedback

Recurring patterns suggest the following rules are missing or under-emphasized
in `.claude/CLAUDE.md`:

### Pattern: Force-unwraps (4 occurrences)
**Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12,78

**Suggested rule**:
> Never use `!`, `try!`, or `as!`. Use `guard let` with explicit early return,
> typed throws, or `as?` with handling. Force-unwraps are crashes waiting to happen.

### Pattern: Deprecated NavigationView (2 occurrences)
**Files**: ProfileView.swift:15, SettingsView.swift:22

**Suggested rule**:
> Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.

### Pattern: Business logic in View body (3 occurrences)
**Files**: LoginView.swift:45, ProfileView.swift:78, FeedView.swift:34

**Suggested rule**:
> Views must not contain business logic, network calls, or data transformations.
> Move all such work into the @Observable view model.

---

## Adjacent Observations
*Out of scope for this PR. Findings in files read for context that were not modified in this PR.
Not counted in the summary above. File separately or address in a follow-up PR.*

### <RelatedFile.swift> (unmodified)

[Severity] **<Category>** (line N)
Current: `<snippet>`
Note: <what the issue is — no action required for this PR>

テンプレートと重大度分類の詳細：references/feedback-templates.md。

関連スキル

全ファイルと、各ファイルを参照するタイミングをまとめた完全な参照表：references/companion-skills.md。

スキル	用途
skills/swiftui-expert-skill/	SwiftUI の状態、Liquid Glass、macOS のパターン、アクセシビリティ
skills/swift-concurrency/	アクター、Sendable、Swift 6 への移行、async/await
skills/swift-testing/	Swift Testing フレームワーク、テストダブル、スナップショット
skills/swift-expert/	Swift 6 以降のパターン、プロトコル、メモリ、SPM
skills/swiftui-ui-patterns/	ナビゲーション、シート、テーマ設定、非同期状態、グリッド

プラットフォームのコマンド

# GitHub PR
gh pr diff <n>
gh pr view <n> --json files,comments

# GitLab MR
glab mr diff <n>
glab mr view <n> --json

# Local changes
git diff             # unstaged
git diff --cached    # staged
git diff HEAD~1      # last commit
git diff -- path/to/file.swift

制限事項

• 仕様への準拠を確認するには、アクセス可能な PR の説明またはリンクされた Issue が必要です。PR のコンテキストがないローカル変更をレビューする場合は、意図を推測せず、仕様への準拠を「未評価」としてください。
• エージェントループへのフィードバックは、コードが AI によって生成されたか、AI の支援を受けていることを前提とします。完全に人が書いたコードの場合も、繰り返し発生するパターンは有用ですが、エージェントへの指示ではなく、チームのコーディング規約として提示してください。

参考ファイル

• references/review-workflow.md — 詳細なプロセス、差分の解析、git コマンド
• references/feedback-templates.md — 出力テンプレート、重大度の分類
• references/spec-adherence.md — PR／issue の仕様の解析、要件カバレッジ表、スコープクリープの分類
• references/agent-loop-feedback.md — 繰り返しパターンのしきい値、指示の表現、ルール提案のテンプレート
• references/swift-quality-checklist.md — Swift 6 以降、並行処理、オプショナル、命名
• references/swiftui-review-checklist.md — プロパティラッパー、状態、最新の API
• references/performance-review.md — ビューの最適化、ForEach、リソース管理
• references/security-checklist.md — 入力検証、Keychain、ネットワークセキュリティ
• references/architecture-patterns.md — MVVM／MVI／TCA、DI、テスト容易性
• references/custom-guidelines.md — .claude/CLAUDE.md の解析
• references/companion-skills.md — 関連スキルの全一覧