SuperAPI AI 工具集

code-review-and-quality

编程与开发

查看项目

更新于 11-13 17:16

技能介绍

该技能是一个代码评审与质量框架,重点在于定义什么算好的评审以及相应的标准,而不是 PR 评审的具体工作流与工具。资料说明,它与 code-review 技能分工不同:后者覆盖 PR 评审流程与工具,两者可同时加载以获得完整覆盖。

用途 用于在合并任何 PR 或变更之前进行评审;功能实现完成后、重构现有代码时、任何 Bug 修复后(同时评审修复与回归测试)使用;也用于评估其他智能体或模型产出的代码,或按多个维度评估代码质量。核心理念是:每一次变更在合并前都必须评审,没有例外。

五轴评审

  1. 正确性:代码是否实现其声称的功能、是否符合规格或任务要求;空值、空集合、边界值等边缘情况与错误路径是否处理;测试是否通过且测的是正确内容;是否存在差一错误、竞态条件或状态不一致;输入恶意时会发生什么。
  2. 可读性与简洁性:他人能否在不需作者解释的情况下理解代码;命名是否清晰且符合项目惯例;控制流是否直白(避免嵌套三元表达式、深层回调);组织是否合理;是否存在应简化的“聪明”技巧;抽象是否值得其复杂度(不要在第三个用例之前泛化);是否有死代码痕迹(空操作变量、兼容垫片、注释掉的代码);是否把新条件硬塞进无关流程;是否对同一形态重复判断。
  3. 架构:变更是否符合系统设计、是否遵循既有模式或引入新模式(若引入是否合理);模块边界是否清晰;是否有应共享的重复代码;依赖方向是否正确(无循环依赖);抽象层次是否合适;重构是降低还是仅转移复杂度(统计读者需同时持有的概念数);特性相关逻辑是否泄漏到共享模块;类型边界是否明确;新增依赖是否逐个审查。
  4. 安全:是否引入漏洞;用户输入是否校验与净化;密钥是否远离代码、日志和版本控制;认证授权是否按需检查;SQL 是否参数化;输出是否编码以防 XSS;依赖是否来自可信来源且无已知漏洞;外部数据是否视为不可信;文件路径是否校验以防路径穿越;变更类端点是否有速率限制或校验。
  5. 性能:是否引入 N+1 查询、无界循环或不受限的数据获取、本应异步的同步操作、UI 组件不必要的重渲染、列表端点缺少分页、热路径中创建大对象、性能关键路径上不必要的分配或拷贝。

结构性问题的修复建议 发现结构性问题时应给出“动作”而非只指出问题,例如:用类型化模型或显式分派器替代条件链;合并重复分支;分离编排与业务逻辑;把特性逻辑移出共享模块;复用规范辅助函数而非另写近似重复实现;显式化类型边界以消除下游分支;删除只增加间接层而无澄清作用的透传包装;拆分大文件。优先选择减少活动部件的修复,而非把同等复杂度摊到各处。

变更规模 约 100 行:良好,可一次评审完,继续;约 300 行:若为单一逻辑变更可接受,需仔细评审;约 1000 行以上:过大,要求拆分。“一个变更”指单一自包含的修改,只解决一件事,包含相关测试,提交后系统仍可用。重构应与功能开发分开提交。

评审流程 第一步理解上下文(变更意图、实现哪份规格或任务、预期行为变化);第二步先评审测试(是否存在、是否测行为而非实现细节、边缘情况覆盖、能否捕获回归);第三步按五轴评审实现;第四步对每条意见分级标注:无前缀为必须修改,Critical: 阻断合并(安全漏洞、数据丢失、功能损坏),Nit: 可选,Consider: 建议但非必须,FYI 仅告知;第五步核实作者的验证情况(运行了哪些测试、构建是否通过、是否手动测试、UI 变更是否有截图)。

评审清单与结论 清单分为上下文、正确性、可读性、架构、安全、性能、验证几组勾选项,结论为“批准—可合并”或“请求修改—问题必须解决”。

死代码卫生 重构后识别不再可达或未使用的代码,明确列出,并在删除前询问(如示例中列出被替换的函数与配置项后问“是否可安全删除”)。不要留下死代码,但也不要静默删除不确定的内容。

评审速度与分歧处理 应在“一个工作日内”响应,这是上限而非目标;优先保证个人响应及时而非最终批准快;大变更应请作者拆分。分歧处理优先级:技术事实与数据高于个人观点;风格问题以风格指南为准;软件设计按工程原则而非个人偏好评估;若不影响整体健康,代码库一致性可接受。

评审中的诚实 不要不实质评审就放行(无证据的“LGTM”无益);不要淡化真实问题;尽可能量化问题(如指出 N+1 查询每项约增加 50ms 优于“可能很慢”);对有明显问题的方案提出反对;若作者掌握全部上下文并坚持,应尊重其判断。

常见合理化借口 资料列出并反驳了若干借口,例如“能跑就够了”(不可读、不安全或架构错误的代码会累积债务)、“我写的所以我确信正确”(作者对自己的假设有盲区)、“以后再清理”(评审就是质量门禁)、“AI 生成的代码大概没问题”(AI 代码更需审查)、“测试通过就行”(测试抓不到架构、安全与可读性问题)、“只是小改动”“重构让它更干净”(若读者需持有的概念数不变则未改善)、“只是版本升级”(依赖升级是他人编写的行为变化,应读更新日志)。

红旗信号 未经任何评审即合并的 PR;只检查测试是否通过的评审;无实际评审证据的“LGTM”;安全敏感变更未做安全评审;大到无法认真评审的 PR;Bug 修复 PR 缺少回归测试;接受“以后再修”;只移动代码而不降低复杂度的重构;散落在无关代码路径中的新条件;重复既有规范辅助函数的定制实现;未读更新日志的批量依赖升级 PR。

完成验证 评审完成后确认:所有 Critical 问题已解决;所有必须修改项已解决或附理由明确延期;测试通过;构建成功;验证情况有文档记录;依赖升级已对照更新日志评审。

限制 资料未说明该技能的安装方式、运行环境、支持语言或是否依赖特定工具链,这些信息暂未提供。