SuperAPI AI 工具集

engineering-code-review

编程与开发

查看项目

更新于 10-29 14:28

技能介绍

该技能用于在审查代码、拉取请求(PR)、补丁、CL、diff 或待实现方案时,评估工程质量和代码健康度、设计、功能与测试等方面。

用途与标准:目标是保护并提升代码库的长期健康度,同时让有价值的改动顺利合入。审查标准不是完美,而是改动整体改善系统且不引入不可接受的风险。改动若确实改善所涉系统的代码健康度,即使不完美也倾向批准;不应批准让系统变差的改动,除非是真正的紧急情况且后续清理明确。优先依据技术事实、数据、项目现有标准和持久设计原则,而非个人品味;风格指南和自动格式化工具是权威,个人风格偏好视为轻微问题;若多种设计都合理,接受作者偏好,除非损害代码健康度。涉及安全、隐私、并发、可访问性、国际化、基础设施、数据迁移或无法验证的领域逻辑时,应请另一位合格审查者。

审查流程:先确定范围,识别 diff、请求的审查范围、目标分支,以及是全量还是部分审查;部分审查需明确说明审查了哪些文件、行为或关注点。再收集材料:GitHub PR 查看描述、关联 issue/设计文档、变更文件、已有评论、CI 状态和相关提交历史;本地审查查看 git status --short、目标分支或基线 SHA 及本地 diff;若无可见 diff 或 PR 上下文,应索取而非凭空审查。随后先看整体:阅读描述、issue、测试与上下文,判断改动是否应现在进入代码库;方向错误应尽早指出并建议更好路径;改动过大难以彻底审查时,应请求拆分或先获得大改动计划批准,而非做浅层全量审查。接着先审主要设计再审细节:找到定义改动的核心文件或 API,先看架构、职责边界、数据流、兼容性和回滚风险,再提命名和格式意见;重大设计问题若使后续审查失效,应立即提出。然后审查分配范围内每一行人工编写的代码,生成文件、大型数据文件或机械输出可适当抽样;代码难以理解时应要求简化或更清晰的结构。之后对照审查清单检查,并检查验证证据:未要求运行命令时优先看现有 CI 与针对性测试;仅在环境和请求合适时本地运行测试,否则说明哪些测试缺失或未验证;未见命令输出或 CI 结果不得声称测试通过。最后给出结论:APPROVE(代码健康度提升且剩余意见非阻塞)、APPROVE_WITH_COMMENTS(剩余意见轻微、可选,或可信任作者自行处理而无需再一轮审查)、REQUEST_CHANGES(正确性、设计、可维护性、测试、文档或风险问题仍存在)、NEEDS_SPECIALIST(需另一位审查者覆盖无法负责评估的领域)。

审查清单:设计(改动是否属于此处、抽象是否适合当前系统);功能(是否实现作者意图且对用户和未来开发者有益);边界情况(失败、空状态、重试、幂等、顺序、时间、权限、并发);复杂度(是否易快速理解、是否解决当前已知问题而非臆测未来);测试(单元/集成/端到端测试是否与风险匹配、代码损坏时测试是否会失败);测试质量(断言是否有意义、聚焦、确定、可维护);命名(是否传达目的而不含糊或嘈杂);注释(是否解释原因、约束或非显而易见算法而非复述代码);文档(行为或用法变化时 README、API 文档、迁移说明、运行手册或生成文档是否更新);风格与一致性(是否遵循项目约定、是否混入无关格式变动);上下文(是否改善周边系统,还是又增加一小块长期复杂度);运维(部署、迁移、可观测性、回滚、功能开关、失败处理是否充分);安全(授权、认证、密钥、注入、依赖、反序列化、权限边界风险);隐私(是否避免不必要收集、记录、暴露、保留或跨边界移动敏感数据);可访问性(界面键盘访问、语义、焦点、对比度、标签、辅助技术行为);国际化(区域、时区、编码、文本膨胀、复数、排序、翻译字符串)。无法自信评估安全、隐私、可访问性、国际化、并发、基础设施、数据迁移或领域特定正确性时,应升级给专家。

评论分级:BLOCKER(批准前必须修复)、IMPORTANT(批准前应修复,除非有书面理由)、QUESTION(最终结论前需回答)、NIT(打磨项,不得阻塞批准)、OPTIONAL(作者可拒绝的建议)、FYI(学习或未来考虑,非请求改动)。

输出格式:先列发现,按严重程度从高到低,尽量附文件与行号。结构为 ## Findings(如 - [BLOCKER] path/file.ext:123 - 问题、为何重要、所需改动)、## Open Questions、## Verdict(REQUEST_CHANGES | APPROVE_WITH_COMMENTS | APPROVE | NEEDS_SPECIALIST)、## Notes(审查范围、已检查测试/命令、后续事项)。无问题时应明确说明,并提及任何未验证范围或残余风险。

常见错误:因偏好而非代码健康度阻塞批准;只审变更行而忽略周边函数或模块使改动不安全;因作者仅在审查线程解释就接受复杂代码;改动本身引入复杂度却让“以后清理”通过;晚期才要求大改而非尽早标记设计问题;快速宽泛回复即可解锁有价值工作时却拖延作者。

来源与许可:内容改编自 Google 工程实践文档(代码审查概览、审查者指南、审查标准、导航、速度、小改动与紧急情况指南),采用 CC-BY 3.0 许可;同作者亦发布于 agentara/skills(MIT)。完整声明见 NOTICE.md。