iOS 代码审查

参数

• --parallel：若代理支持子代理，则为每个技术领域分发一个专用子代理
• 路径：目标目录（默认：当前工作目录）

硬性准入条件（Hard gates）

在输出中撰写 Issues 之前，须按顺序完成以下全部步骤（允许作用域为空；严禁编造问题）。

1. 作用域准入（Scope gate）：你已明确列出本次审查所涵盖的 .swift 文件路径（来自第 1 步或用户指定路径）。通过条件：该文件列表已记录于工作笔记中 或 单独一行写明：No Swift files in scope —— 此时立即终止，不报告任何 Issues。
2. 检查器准入（Linter gate，风格类）：第 2 步命令已在本代码树上执行；若未找到 .swiftlint.yml 或 .swiftlint.yaml，需在单行中注明。 通过条件：当配置存在且 swiftlint 执行成功时，你不得对 SwiftLint 已能覆盖的某行代码重复报告风格类问题。
3. 协议准入（Protocol gate）：review-verification-protocol 必须在第 6 步前加载完毕。通过条件：若你报告了任何 Issues，则至少一项发现必须经由该检查清单验证（在 Review Summary 或对应 Issue 中注明所核对的具体条目）；若未报告 Issues，则需在 Review Summary 中声明 Protocol applied; no issues。
4. 证据准入（Evidence gate，严重/主要级）：对每一项 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 步：验证检查器状态

关键要求：在标记任何风格类问题前，必须先运行 SwiftLint。

# 检查 SwiftLint 配置是否存在并执行
if [ -f ".swiftlint.yml" ] || [ -f ".swiftlint.yaml" ]; then
    swiftlint lint --quiet 
fi

规则：

• 若 SwiftLint 对某具体规则校验通过，则禁止手动标记该问题
• SwiftLint 配置对风格规则具有权威性
• 仅可标记检查器无法检测的问题（语义问题、架构问题等）

第 3 步：识别使用的技术栈

# SwiftUI（始终伴随导入 SwiftUI 的 Swift 文件）
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（显式异步模式）
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

# 动画（超出基础 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

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

第 6 步：执行审查

若代理支持子代理（且启用了 --parallel 参数），则并行分发一个子代理处理每个技术领域；否则按顺序串行执行。两种方式产出完全相同的最终结果——即统一汇总的发现项。

串行模式（默认）：

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

并行模式（如代理支持，通过 --parallel 启用）：

1. 预先全面识别所有技术栈
2. 为每个技术领域分发一个子代理
3. 各子代理加载对应技能并专注审查其所属领域
4. 等待所有子代理完成
5. 汇总所有发现

标记问题前的必要检查

1. 核查 SwiftLint 输出 —— 避免重复报告检查器已覆盖的问题
2. 查阅代码注释（如 // MARK:、// NOTE: 等），确认是否为有意为之的模式
3. 考虑 Apple 框架惯用法 —— 表面看似有误的写法，在特定框架上下文中可能是正确的
4. 追踪异步代码路径 —— 在断言缺少错误处理或存在竞态条件前，务必完成路径分析

第 7 步：验证发现项

在报告任一问题前，请完成以下验证：

1. 重读实际源码（而非仅 diff 上下文）
2. 对于“未使用”类主张 —— 是否已搜索全部引用？
3. 对于“缺失”类主张 —— 是否已检查框架或父级组件的处理逻辑？
4. 对于语法类问题 —— 是否已对照当前版本官方文档核实？
5. 剔除所有属于个人风格偏好的条目，仅保留真实问题

第 8 步：审查收敛性

单次审查完整性

你必须在一次审查中报告所有类别（风格、逻辑、类型、测试、安全、性能）的全部问题。不得将问题留待后续轮次处理。

提交发现前，请自问：

• “若作者采纳我全部建议修复，我在修复后的代码中是否会发现新的问题？”
• “我是否要求新增代码（如测试、类型定义、模块）？而这些新增内容本身是否也需要被审查？”

若任一问题答案为“是”，请立即将这些预期中的下游问题纳入本次审查报告，以便作者一次性解决全部事项。

作用域规则

• 仅审查 diff 中的代码及其直接关联的既有代码
• 不得要求新增功能、测试基础设施或 diff 前不存在的架构调整
• 若测试覆盖率缺失，仅以一项 Minor 级问题形式标记（例如：“Missing test coverage for X, Y, Z”）—— 不得指定 mock 库、行为抽取或依赖注入等实现细节，以免引入大量新代码
• 类型规范、文档和命名问题属于 Minor 级，除非其影响公开 API 协议
• 不得要求新增依赖（例如 Mox、测试库、检查器插件）

修复复杂度预算

对既有代码的修复应依其真实严重程度标注，不受代码修改量影响。

但对 diff 前完全不存在的净新增代码，必须归类为 Informational 级别：

• 新增依赖（例如 Mox、检查器插件）
• 创建全新模块、文件或测试套件
• 抽离新行为、协议或抽象层

此类建议供作者在后续工作中酌情考虑，不构成审查阻塞项。

迭代策略

若本次为修复后的复审：

• 仅验证此前标记的问题是否已正确修复
• 不得引入与上一轮审查无关的新发现
• 接受未修复的 Minor / Nice-to-Have 类问题，不再重复标记
• 复审的目标是 验证，而非 发现

输出格式

## Review Summary

[1–2 句概括性概述]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: 问题描述（具体哪里出错）
   - Why: 此问题为何重要（崩溃、数据丢失、安全风险、竞态条件等）
   - 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] 模式说明（请保留此项）

## Verdict

Ready: Yes | No | With fixes 1-N（仅限 Critical/Major；Minor 项可接受）
Rationale: [1–2 句说明]

修复后验证

修复应用后，运行以下命令：

# Swift 构建与检查
swift build
swiftlint lint --quiet

# 若存在测试，运行之
swift test

所有检查均须通过方可批准。

规则

• 必须在审查前加载技能（不可事后加载）
• 每个 Issue 必须按顺序编号（1、2、3…）
• 每个 Issue 必须包含 FILE:LINE 定位信息
• Issue / Why / Fix 三部分须清晰分隔
• 按实际严重程度准确分类
• 检查 Swift 6 严格并发问题
• 修复后必须执行验证
• 所有问题必须在单次审查中报告 —— 不得保留问题至后续轮次
• 复审仅验证先前问题是否修复 —— 不进行新问题发现
• 对净新增代码（新模块、依赖、测试套件）的要求一律列为 Informational，非阻塞项
• Verdict 判定仅基于 Critical 和 Major 项 —— Minor 和 Informational 不影响批准结论