swift-code-reviewer

Swift/SwiftUI 代码审查技能

多层审查，涵盖 Swift 6+ 并发、SwiftUI 模式、性能、安全性、架构和项目特定标准。读取 .claude/CLAUDE.md，并输出带有 file:line 引用和修改前/后的代码示例的 Critical/High/Medium/Low 严重性问题。

何时使用此技能

• “审查这个 PR”
• “审查我的代码” / “审查我的更改” / “审查未提交的更改”
• “审查 [组件] 的代码”
• “审计此代码库” / “检查代码质量”
• “对照 .claude/CLAUDE.md 进行审查” / “检查是否符合我们的编码标准”
• “架构审查” / “性能审计” / “安全审查”
• “根据规范审查这个 PR”
• “Agent 有没有遗漏 issue #123 中的内容？”
• “根据这个 PR，我的 CLAUDE.md 中还缺少哪些规则？”
• “审查这个 AI 生成的 PR”

工作流

阶段 0 — 确定范围

目标：在开始任何分析前，生成规范的范围对象。后续每个阶段都读取此对象，不会独立获取变更集。

模式检测

按顺序运行这些检查；遇到第一个匹配项时停止：

优先级	条件	模式
1	用户提供 PR 编号或 URL	PR — gh pr view <n> --json files,baseRefName
2	用户提供明确的文件路径	文件 — 提供的路径 → scope.modified，跳过检测
3	gh pr view --json number 为当前分支返回结果	PR（自动检测）
4	用户的调用中包含 “staged” 或 “cached”	已暂存 — git diff --cached --name-status
5	默认	本地 — git diff --name-status <base>...HEAD + git diff --name-status（并集）

基准分支解析（用于 PR 自动检测和本地模式）：

# 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 不可用或未通过身份验证，请明确告知并回退到本地模式：

"gh 不可用 — 将针对 origin/main 回退到本地模式。运行 gh auth login 以完整检测 PR 范围。"

范围对象

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；记录旧路径，以避免 Agent 将未更改的内容批评为新代码

填充 testsForModified：对于 scope.modified 中的每个路径：

1. 映射到测试目录：Features/Login/LoginViewModel.swift → Tests/Features/Login/LoginViewModelTests.swift
2. 备选方案：在同一目录中搜索 *Tests.swift
3. 将找到的路径（且磁盘上存在）添加到 scope.testsForModified

填充 related：在阶段 1 中，Agent 读取导入的文件、协议声明和父视图以获取上下文时添加。

排除路径 — 定稿前从所有集合中过滤：

• 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
   • 对于关联的 issue：gh issue view <num> --json title,body,labels
   • 对于 MR：glab mr view <num> 和 glab issue view <num>
   • 提取：
     • 明确说明的目标／要解决的问题
     • 明确的验收标准（查找复选框、“should”、“must”、“Given/When/Then”）
     • 提及的边缘情况或非目标
     • 范围外的事项
   • 如果没有 PR／issue 上下文，请注明这一点，并改为根据差异推断意图。
2. 尝试加载 .claude/CLAUDE.md。
   • 如果缺失：在报告中添加备注 — "未找到项目标准文件 — 审查采用默认 Apple 指南" — 然后继续。
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")、空函数体
  • 本应是真实实现却仍为桩代码的 mock
  • 没有对应差异的验收标准
• 意图偏移
  • 代码解决的是类似但不同于所述的问题
  • 命名／结构暗示了不同的思维模型

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. 安全性 — 强制解包、Keychain 与 UserDefaults、输入验证、日志中不得包含机密 → references/security-checklist.md
5. 架构 — 是否符合 MVVM/MVI/TCA、依赖注入、可测试性 → 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 — 模式检测（用于 Agent 循环反馈）

目标：识别反复出现的问题，这些问题表明 Agent 的指令存在缺漏，而不只是代码有问题。

收集每个文件的发现后，进行汇总：

1. 按规则对发现进行分组（例如，“force-unwrap”“已弃用的 NavigationView”“UI 修改缺少 @MainActor”）。
2. 将在差异中触发 ≥2 次的规则标记为重复模式。
3. 对于每个重复模式，起草一条可写入 .claude/CLAUDE.md 或 Agent 系统提示词的一行规则——以指令形式撰写，而非描述。
4. 如果过去的审查中出现过相同的重复模式（检查 .claude/CLAUDE.md 的 git log），则提高优先级——现有规则不够有力，或未被遵循。

阈值依据：出现一次是疏忽；出现两次是模式；出现三次或以上，说明 Agent 的指令对此未作明确要求，需要添加明确规则。

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

阶段 3 — 报告

按文件对发现进行分组 → 在每个文件内按严重程度排序 → 编写优先级行动项。

严重程度：严重（崩溃／数据竞争／安全漏洞）· 高（反模式／重大架构违规）· 中（质量／可维护性）· 低（风格／建议）。

如果代码写得尤为出色，请用一句话给予正面反馈。不要用泛泛的赞扬凑字数。

具体问题示例

强制解包 → guard let（严重）

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（高）

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 的修改必须在主 actor 上进行；否则会发生数据竞争。

修复：

@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/	Actor、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 描述或关联的问题。审查没有 PR 上下文的本地更改时，应将规范遵循情况标记为“未评估”，而不是猜测意图。
• Agent 循环反馈假设代码由 AI 生成或由 AI 辅助编写。对于完全由人工编写的代码，重复模式仍然有用，但应将其表述为团队编码规范，而非 Agent 指令。

参考文件

• 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 — 完整的配套技能表