review-ios

iOS 代码审查

参数

• --parallel：如果 Agent 支持子 Agent，则针对每个技术领域分派一个专门的子 Agent
• 路径：目标目录（默认为当前工作目录）

硬性门槛

在输出 Issues 前按顺序完成以下步骤（范围为空也可以；不得捏造问题）。

1. 范围门槛： 明确列出待审查的 .swift 路径（来自步骤 1 或用户提供的路径）。通过： 在工作笔记中记录列表，或写一行：No Swift files in scope，然后停止，不输出 Issues。
2. Lint 门槛（样式）： 已针对此代码树运行步骤 2 中的命令；如果不存在 .swiftlint.yml / .swiftlint.yaml，则用一行说明。通过： 当配置存在且 swiftlint 成功时，不报告 SwiftLint 已对该行强制执行的样式问题。
3. 协议门槛： 在步骤 6 前加载 review-verification-protocol。通过： 如果报告任何 Issues，至少有一项发现已根据该清单核验（在 Review Summary 或该 Issue 中注明清单项目）；如果未报告任何 Issues，则在 Review Summary 中写明 Protocol applied; no issues。
4. 证据门槛（Critical/Major）： 对每个 Critical 或 Major 项，在 FILE:LINE 处重新阅读文件（阅读完整上下文，而不只是 diff 代码块）。通过： Issue 文本与该位置可观察到的代码一致。

在满足门槛 1–3 之前，不要开始步骤 6（技能加载顺序仍按步骤 4–5 执行）。

步骤 1：识别变更文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.swift$'

步骤 2：检查 Linter 状态

重要： 在指出任何样式问题前，先运行 SwiftLint。

# Check if SwiftLint config exists and run it
if [ -f ".swiftlint.yml" ] || [ -f ".swiftlint.yaml" ]; then
    swiftlint lint --quiet <changed_files>
fi

规则：

• 如果 SwiftLint 对某条具体规则检查通过，不要手动指出该问题
• SwiftLint 配置是样式规则的权威依据
• 仅指出 Linter 无法检测的问题（语义问题、架构问题）

步骤 3：检测技术

# SwiftUI (always with swift files that import it)
grep -r "import SwiftUI" --include="*.swift" -l | head -3

# SwiftData
grep -r "import SwiftData\|@Model\|@Query" --include="*.swift" -l | head -3

# Swift Testing
grep -r "import Testing\|@Test\|#expect" --include="*.swift" -l | head -3

# Combine
grep -r "import Combine\|AnyPublisher\|@Published" --include="*.swift" -l | head -3

# URLSession (explicit async patterns)
grep -r "URLSession\.shared\|\.data(from:\|\.download(from:" --include="*.swift" -l | head -3

# CloudKit
grep -r "import CloudKit\|CKContainer\|CKRecord" --include="*.swift" -l | head -3

# WidgetKit
grep -r "import WidgetKit\|TimelineProvider\|WidgetFamily" --include="*.swift" -l | head -3

# App Intents
grep -r "import AppIntents\|@AppIntent\|AppEntity" --include="*.swift" -l | head -3

# HealthKit
grep -r "import HealthKit\|HKHealthStore\|HKQuery" --include="*.swift" -l | head -3

# WatchKit
grep -r "import WatchKit\|WKExtension\|WKInterfaceController" --include="*.swift" -l | head -3

# Animations (beyond basic withAnimation)
grep -r "PhaseAnimator\|KeyframeAnimator\|matchedGeometryEffect\|navigationTransition\|scrollTransition\|CABasicAnimation\|CASpringAnimation\|CAKeyframeAnimation\|UIViewPropertyAnimator\|UIDynamicAnimator\|\.symbolEffect\|\.contentTransition\|CustomAnimation\|MeshGradient" --include="*.swift" -l | head -3

步骤 4：加载核验协议

加载 review-verification-protocol 技能，并在整个审查过程中牢记其清单。

步骤 5：加载技能

加载以下适用的每项技能（阅读其 SKILL.md）。

始终加载：

• swift-code-review
• swiftui-code-review

根据检测结果有条件加载：

条件	技能
检测到 SwiftData	swiftdata-code-review
检测到 Swift Testing	swift-testing-code-review
检测到 Combine	combine-code-review
检测到 URLSession	urlsession-code-review
检测到 CloudKit	cloudkit-code-review
检测到 WidgetKit	widgetkit-code-review
检测到 App Intents	app-intents-code-review
检测到 HealthKit	healthkit-code-review
检测到 WatchKit	watchos-code-review
检测到动画代码	ios-animation-code-review

步骤 6：审查

如果 Agent 支持子 Agent（且请求了 --parallel），则并行针对每个技术领域分派一个子 Agent；否则按顺序执行。两种路径的输出相同——均为合并后的发现。

顺序执行（默认）：

1. 加载适用的技能
2. 优先审查 Swift 质量问题（并发、内存、错误处理）
3. 审查 SwiftUI 模式（视图组合、状态管理、无障碍功能）
4. 审查已检测到的技术领域
5. 合并发现

并行执行（支持时，通过 --parallel）：

1. 预先检测所有技术
2. 针对每个技术领域分派一个子 Agent
3. 每个 Agent 加载其技能并审查所属领域
4. 等待所有 Agent 完成
5. 合并发现

标记问题前

1. 检查 SwiftLint 输出——不要重复报告 Linter 已发现的问题
2. 检查代码注释，确认是否有刻意采用的模式（// MARK:、// NOTE: 等）
3. 考虑 Apple 框架的惯用写法——泛泛看来像是错误的做法，对于该框架可能是正确的
4. 追踪异步代码路径，再声称缺少错误处理或存在竞态条件

第 7 步：验证发现的问题

报告任何问题前：

1. 重新阅读实际代码（而不只是差异上下文）
2. 对于“未使用”的说法——你是否搜索了所有引用？
3. 对于“缺少”的说法——你是否检查了框架或父级的处理逻辑？
4. 对于语法问题——你是否查阅了当前版本的文档进行验证？
5. 删除任何属于风格偏好、而非实际问题的发现

第 8 步：评审收敛

单轮评审的完整性

你必须在单轮评审中报告所有类别（风格、逻辑、类型、测试、安全、性能）的所有问题。不要把问题留到后续轮次。

提交发现的问题前，问问自己：

• “如果我建议的修复全部应用，我是否会在修复后的代码中发现新问题？”
• “我是否要求添加新代码（测试、类型、模块），而这些代码本身也需要评审？”

如果任一答案为“是”，请立即在本轮评审中一并指出预期会出现的后续问题，以便作者一次性处理所有问题。

范围规则

• 仅评审差异中的代码及直接相关的现有代码
• 不要要求添加差异前不存在的新功能、测试基础设施或架构变更
• 如果缺少测试覆盖，将其作为一个 Minor 问题标记（“缺少对 X、Y、Z 的测试覆盖”）——不要指定会引入大量新代码的实现细节，例如模拟库、行为提取或依赖注入模式
• 类型规范、文档和命名问题均为 Minor，除非影响公共 API 契约
• 不要要求添加新依赖项（例如 Mox、测试库、Linter 插件）

修复复杂度预算

无论修复规模大小，都应按其实际严重程度标记对现有代码的修复。

但是，对于差异前不存在的全新代码的要求必须归类为 Informational：

• 添加新依赖项（例如 Mox、Linter 插件）
• 创建全新的模块、文件或测试套件
• 提取新的行为、协议或抽象

这些是供作者在后续工作中考虑的改进建议，并非评审阻断项。

迭代政策

如果这是修复后的重新评审：

• 仅验证之前标记的问题是否已正确解决
• 不要提出与之前问题无关的新发现
• 接受尚未修复的 Minor/Nice-to-Have 问题——不要再次标记
• 重新评审的目标是验证，而非发现问题

输出格式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (crash, data loss, security, race condition)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

修复后验证

应用修复后，运行：

# Swift build and lint
swift build
swiftlint lint --quiet

# Run tests if present
swift test

所有检查都必须通过才能批准。

规则

• 评审前加载技能（不要等到评审后）
• 为每个问题按顺序编号（1、2、3……）
• 为每个问题注明 FILE:LINE
• 清晰区分 Issue/Why/Fix
• 按实际严重程度分类
• 检查 Swift 6 严格并发问题
• 修复后运行验证
• 在单轮评审中报告所有问题——不要把问题留到后续迭代
• 重新评审仅验证之前的修复——不再发现新问题
• 对全新代码（新模块、依赖项、测试套件）的要求归为 Informational，不阻止评审通过
• Verdict 忽略 Minor 和 Informational 项——只有 Critical 和 Major 会阻止批准