SuperAPI AI 工具集

code-review

编程与开发

查看项目

更新于 10-16 02:47

技能介绍

用途

code-review 是一项用于对 pull request 进行代码审查的技能,提供系统化的审查方法。它聚焦于审查流程与质量维度,而不是特定技术栈的模式。其调用方式为 /code-review [arguments],技能名称为 han-core:code-review。

适用场景包括:使用结构化流程开展系统化代码审查;从多个维度(正确性、安全性、可维护性)评估代码;提供清晰、可操作的建设性反馈;依据质量标准判断是否具备批准条件。

不适用于:特定技术栈的模式(应参考相应语言/框架插件);详细的实现指导(应参考特定领域的智能体)。

主要能力

该技能通过多智能体协作完成审查。首先使用 Haiku 智能体检查 PR 是否符合审查条件:是否已关闭、是否为草稿、是否无需审查(如自动化 PR 或非常简单且明显没问题)、是否已有此前的审查、或是否过大(变更超过 1000 行)应拆分。若任一条件成立则不继续。

随后使用 Haiku 智能体列出相关 CLAUDE.md 文件路径(不含内容),包括根目录及 PR 修改文件所在目录中的 CLAUDE.md;再用 Haiku 智能体查看 PR 并返回变更摘要。

接着启动 5 个并行的 Sonnet 智能体独立审查:Agent #1 审计变更是否符合 CLAUDE.md;Agent #2 对变更做浅层扫描以发现明显 bug,聚焦大问题、忽略小问题和误报;Agent #3 阅读被修改代码的 git blame 与历史,结合历史上下文识别 bug;Agent #4 阅读此前触及这些文件的 PR,检查其中可能同样适用于当前 PR 的评论;Agent #5 阅读被修改文件中的代码注释,确保变更符合注释中的指引。

所有智能体完成后,按 proof-of-work 原则验证其工作:检查输出是否为空或泛泛而谈;确认问题描述包含具体文件路径和行号;确认智能体并非在未实际分析的情况下都返回“未发现问题”。若某智能体验证失败,则记录但继续使用已验证的结果。

然后对问题进行去重与评分:按文件路径和行范围分组(±3 行内视为重复),合并相似描述并保留最详细版本,合并发现同一问题的所有智能体的推理。对每个唯一问题启动并行 Haiku 智能体,依据 PR、问题描述和 CLAUDE.md 文件列表给出 0-100 的置信度评分,评分标准为:0 完全不确定(误报或既有问题);25 有些确定(可能是真问题也可能是误报,无法验证;若为风格问题且未在相关 CLAUDE.md 中明确提及);50 中等确定(可验证为真问题,但可能是吹毛求疵或实践中不常发生,相对整个 PR 不重要);75 高度确定(经复核很可能在实践中遇到,现有做法不足,问题很重要且直接影响功能,或相关 CLAUDE.md 直接提及);100 绝对确定(经复核确认是真实问题且在实践中频繁发生,证据直接证实)。过滤掉低于 80 分的问题;若无满足条件的问题则不继续。

再用 Haiku 智能体重复第 1 步的资格检查,确认 PR 仍符合审查条件。最后使用 gh bash 命令在 PR 上评论结果,要求输出简短、避免 emoji、链接并引用相关代码、文件和 URL。

使用方式

技能通过 /code-review [arguments] 调用。实现中使用 gh 与 GitHub 交互(如获取 PR 或创建行内评论),而非 web fetch;使用 TaskCreate 跟踪步骤 1-8 的进度;必须引用并链接每个 bug(如引用 CLAUDE.md 时必须链接)。不检查构建信号,也不尝试构建或类型检查应用,这些将单独运行。

审查流程分为四个阶段。

第一阶段:审查前准备。开始前收集上下文,理解变更(如 git diff <base-branch>...HEAD、git diff --stat <base-branch>...HEAD),识别相关上下文(如 grep -r "similar_pattern" .),验证业务上下文(是否有相关 issue/ticket、涉及哪个领域、对用户的影响)。

第二阶段:系统化审查。从六个维度审查:1. 正确性——是否解决所述问题、业务逻辑是否符合领域规则、边界情况是否处理、测试是否验证预期行为;通过先读测试理解意图、追踪代码路径、验证错误场景、对照需求来检查。2. 安全性——是否遵循授权/认证模式、是否有 API 或契约的破坏性变更、是否可能暴露敏感数据、数据操作是否安全、是否存在竞态条件或数据完整性问题;通过验证访问控制、运行兼容性检查、检查输入验证、审查事务边界、验证输入清理来检查。3. 可维护性——是否遵循现有代码库模式、代码是否可读、复杂区域是否有文档、是否遵循童子军规则、命名是否清晰一致;通过对比类似代码、验证复杂逻辑文档、检查魔法数字和硬编码值、确保命名一致、查找注释掉的代码来检查。4. 可测试性——新功能是否有测试、测试是否覆盖边界和错误场景、测试是否清晰可维护、测试数据设置是否合适;通过审查变更代码的测试覆盖、验证正常与异常路径、确保测试确定且清晰、检查测试隔离来检查。5. 性能——是否有明显性能问题、数据库查询是否高效、昂贵操作是否优化、资源是否妥善管理;通过识别 N+1 查询、检查缺失索引、审查资源分配与清理、验证数据结构来检查。6. 规范符合度——是否遵循语言特定最佳实践、是否通过所有验证检查、是否有 lint 或类型错误、是否遵循约定的编码标准;通过运行验证套件、检查标准模式违规、验证无质量门禁绕过来检查。

第三阶段:置信度评分。对每个发现的问题给出 0-100 的置信度评分。关键过滤规则:只报告置信度 >= 80% 的问题,低置信度发现会产生噪音应省略。高置信度(90-100)应报告:验证失败(lint、测试、类型)、安全漏洞(SQL 注入、XSS、认证绕过)、有明确复现的正确性 bug、破坏性 API 变更、违反已记录的团队标准。中高置信度(80-89)应报告:新功能缺少测试、错误处理缺口、性能问题(N+1 查询、缺失索引)、有明确模式的可维护性问题、童子军规则违规。中置信度(60-79)不报告:无明确代码库先例的风格偏好、推测性性能担忧、无明确收益的替代方案。低置信度(<60)不报告:个人意见、无具体影响的“可以更好”、无证据的理论边界情况。

误报过滤:不报告——本次变更未引入的既有问题(检查 git blame)、已由 linter/formatter 处理的问题、有明确 lint-ignore 注释的代码、无文档标准的风格偏好、无证据或复现的理论 bug、无明确收益的“可以使用”建议、不影响质量的吹毛求疵。报告前需验证:运行 git diff 确认问题在变更行内、检查自动化工具是否已捕获、对照项目文档标准(CLAUDE.md、CONTRIBUTING.md 等)验证、确认问题确实影响正确性、安全性或可维护性。

第四阶段:反馈与决策。提供结构化反馈:摘要(高层评估)、优点(做得好的地方)、问题(按严重程度组织并附置信度评分:Critical 置信度 >= 90 阻止批准,涉及安全、正确性、破坏性变更;Important 置信度 >= 80 应处理,涉及可维护性、最佳实践)、可操作的后续步骤(具体变更并附 file:line 引用)、决策(批准、请求变更或需要讨论)。注意:建议/锦上添花的内容有意省略,只聚焦高置信度、可操作的反馈。

批准条件:所有验证检查通过、业务逻辑正确完整、遵循安全与授权模式、无破坏性变更(或已妥善协调)、代码遵循现有模式、复杂逻辑有清晰文档、测试覆盖正常路径/边界/错误场景、变更符合需求、代码可维护清晰、应用童子军规则。请求变更条件:关键问题(安全漏洞、正确性 bug、破坏性变更)、重要问题(模式违规、缺少测试、代码不清晰)、未解决的验证失败、业务逻辑与需求不符、错误处理不足。需要讨论条件:架构担忧、需求不明确、需要权衡决策、模式偏离需要理由、性能影响不确定。

适用场景与限制

该技能集成于开发工作流第二阶段:实现 -> 验证套件(自动化检查)-> 代码审查(本技能)-> 批准(人工)-> 合并。审查发生在验证之后:开发者运行验证套件,所有自动化检查必须通过,然后应用代码审查技能进行质量评估,识别并修复问题,修复后重新验证,最后由人工审查并批准合并。审查不能替代验证,两者都必需。

常见审查陷阱包括:授权绕过、破坏性变更、错误处理缺口、测试质量不足、领域逻辑错误、注释掉的代码、魔法数字、过度聪明的代码、童子军规则违规。红旗(绝不批准)包括:注释掉的代码(应删除,git 保留历史)、代码中的密钥或凭据(应使用安全配置)、未验证兼容性的破坏性变更、被注释或跳过的测试(应修复代码而非测试)、被忽略的验证失败(必须全部通过)、新功能无测试(测试是必需的)、硬编码业务逻辑(应可配置)、缺少错误处理(必须处理边界情况)、明显安全漏洞(必须立即修复)。

最终评论格式要求:输出简短、避免 emoji、链接并引用相关代码、文件和 URL。示例格式以“Code review”开头并列出发现的问题数量。

关于收费、价格、平台支持等具体信息,资料中暂未提供。