code-review

代码审查技能

按照可重复的检查清单，对 Flutter/Dart 项目进行结构化、客观的代码审查。

适用场景

在以下情况下使用此技能：

• 接到审查拉取请求、合并请求或分支的任务。
• 评估已修改、新增或删除的文件的正确性和质量。
• 合并前审计差异。
• 检查新代码是否符合项目标准。

---

审查工作流

第 1 步 — 验证分支和合并目标

1. 确认当前分支是功能、缺陷修复或 PR/MR 分支，而非项目的主分支（例如 main、master、develop）。
2. 确认分支与目标分支保持同步（没有未解决的冲突）。
3. 确定合并的目标分支。

**检查点：**如果当前分支落后于目标分支，请在继续之前指出。

第 2 步 — 查明变更

1. 列出所有已修改、新增和删除的文件。
2. 对于每项变更，查阅提交标题，并审查相关组件的实现方式。
3. 分析变更：是否清楚变更的原因？如果不清楚，就深入检查相关方法和文件，直到弄清楚为止。报告时，指出你分析了哪些相关文件/方法以及原因——这能表明你理解了变更，而非仅凭假设。
4. 绝不要在未调查实现的情况下假定变更正确。
5. 如果调查后仍无法弄清某项变更，请在报告中明确指出。

第 3 步 — 审查每个文件

逐一检查每个已修改的文件。对于每个文件，核实以下内容：

方面	核实内容
理解变更	变更的原因是什么？审查相关方法/文件，并记录分析了哪些内容
位置	文件是否位于正确目录
命名	文件名是否遵循项目命名规范
职责	文件职责是否明确；变更原因是否易于理解
可读性	变量、函数和类的名称是否清晰且一致
逻辑与正确性	是否存在逻辑错误或遗漏的边界情况
代码异味	检查下方代码异味参考中列出的异味
可维护性	代码是否模块化；是否存在不必要的重复
错误处理	是否妥善处理错误和异常
安全性	是否存在输入验证缺漏；是否将密钥提交到了代码中
性能	是否存在明显低效之处（例如不必要的重建、针对大型列表的 O(n^2) 循环）
SOLID 原则	评估是否遵循原则，同时避免强行加入不必要的样板代码或过度抽象
Flutter/Dart/ 模式	是否符合项目已加载的指南和惯例
文档	公共 API、复杂逻辑和新模块是否有文档说明
测试覆盖率	新增或修改的逻辑是否有足够测试（参见第 4 步）
风格	代码是否符合项目风格指南和 lint 规则
现有代码	如果新增变更看起来没有问题，也要审查周围未修改的现有代码是否存在异味，并在相关时建议重构

对于生成文件（例如 *.g.dart、*.freezed.dart）：确认文件是最新生成的，且未经过手动修改。

范围把控：你的任务不是对每一项变更都发表评论，而是找出错误和具体的改进之处并加以评论。代码没有问题时，不要硬凑评论。

Flutter 专项检查

（注：以下示例使用 Bloc/Cubit；请对 Riverpod、Provider 或你选择的状态管理包应用类似原则。）

// BAD — rebuilds entire tree on every state change
BlocBuilder<MyCubit, MyState>(
  builder: (context, state) => EntireScreen(state: state),
);

// GOOD — scope rebuilds to the widget that actually changes
BlocSelector<MyCubit, MyState, String>(
  selector: (state) => state.title,
  builder: (context, title) => Text(title),
);

• 检查动态生成的组件是否使用了 Key。
• 检查控制器、流和动画控制器是否调用了 dispose()。
• 确认在可能的情况下使用了 const 构造函数。

代码异味参考

检查每个文件中是否存在常见的代码异味。请使用 refactoring.guru/refactoring/smells 查看定义和建议的重构方式。

类别	异味
臃肿型	过长方法、大型类、原始类型偏执、过长参数列表、数据团块
面向对象滥用型	接口不同的替代类、拒绝继承、临时字段、Switch 语句
变更阻碍型	发散式变化、平行继承体系、散弹式修改
可有可无型	注释（冗余）、重复代码、数据类、死代码、惰性类、推测性通用化
耦合型	特性嫉妒、不当亲密关系、不完整的库类、消息链、中间人

步骤 4 — 评估整体变更集

1. 确认变更集聚焦于其声明的目的，且范围恰当——不包含无关变更。
2. 检查 PR/MR 描述是否准确反映变更内容。

测试覆盖率

明确验证测试覆盖率——这很容易被忽略，也很容易造假，因此务必认真检查：

• 对于任何新增逻辑或重大变更，搜索相应的测试文件并确认测试确实存在。
• 检查测试是否覆盖变更功能，包括边界情况，而不只是正常路径。
• 评估测试是否能针对真实代码实际失败，还是只验证模拟行为（断言模拟对象返回了预先设定的值，这并不能证明任何事情）。
• 如果测试缺失或不足，请指出覆盖率不足的问题——不要默默放过。

步骤 5 — 验证 CI 和测试

1. 确保 CI 中所有测试均通过。
2. 检查是否出现新的分析器警告或 lint 违规。
3. 如果不确定某个包的最佳实践，请查阅官方文档。

**检查点：**如果 CI 未通过，或新增逻辑缺少测试，请将其标记为阻塞问题。

---

总结

完成逐文件检查后，确定最终结论：

• 如果一切正常且无需修改：发布一条总体结论评论，总结 MR 的内容（完成了什么）以及任何观察结果，并批准 MR。
• **如果新增变更没有问题，但发现了现有代码中的异味：**将其作为可选重构建议提出，而不是阻塞项。
• 如果发现问题：清楚总结主要问题，让作者知道应优先处理哪些内容。

---

反馈标准

• 保持客观、合理——避免惯例性的赞美或奉承。
• 采取逆向思考的方式：提供诚实、周到的反馈。
• 针对发现的每个问题，提供清晰且有建设性的建议。
• 对任何不清楚的内容，提出澄清请求。
• 将每项发现按严重程度分类：suggestion、minor 或 major。

---

输出格式

默认情况下，请在聊天回复中提供评审——针对每个文件，按以下结构组织：

1. 摘要——说明更改内容及原因。
2. 问题——每项标明严重程度（suggestion / minor / major），并给出具体的修复建议。
3. 问题——针对每个文件提出具体的澄清请求。
4. 结论——以下选项之一：Approved、Approved with suggestions 或 Changes requested。

在线发布评论（仅限用户选择）。 在提供聊天评审后，询问用户是否还希望你在 PR/MR 上在线发布这些评论——这样团队就能看到、审阅并回复。**只有用户明确表示同意后，才能在线发布。**切勿主动在平台上发布评论。

用户选择在线发布后，请将问题作为行内评论发布，锚定到正确的文件和行（使用正确的位置字段）；将结论/主要顾虑作为顶层评审评论，并在适当时批准。这需要平台（GitHub/GitLab）的 review-bot 访问令牌；如果尚未配置，请告知用户，并请其在发布前进行设置。

令牌安全。令牌属于机密信息。你可以检查令牌是否存在，并报告其长度以确认已配置，但切勿读取、回显、记录、打印或以其他方式泄露令牌值——无论是在聊天、文件还是提交中。传给 curl 时，只能引用环境变量（例如 $GITLAB_TOKEN），绝不能直接写入令牌值，并避免使用 curl -v/--verbose（这会打印授权标头）。PreToolUse 钩子（scripts/protect-token.sh）会强制执行此要求，并阻止任何可能泄露令牌值的 Bash 命令。有关安全检查令牌是否存在/长度，请参阅每个参考文件中的“安全处理令牌”部分。

该钩子在 Claude Code CLI 和 Agent SDK 中都会触发。（显式设置 settingSources/setting_sources 的 SDK 应用必须包含 "project"，以便加载技能钩子；默认情况下已包含。）

有关平台特定的 API 详情、curl 格式和审批步骤，请参阅：

• GitLab → references/gitlab-posting.md（使用 GITLAB_TOKEN 环境变量）
• GitHub → references/github-posting.md（使用 GITHUB_TOKEN 环境变量）