SuperAPI AI 工具集

validating-a-change

编程与开发

查看项目

更新于 10-16 05:57

技能介绍

用途

该技能用于验证一项代码变更是否正确、完整,并已准备好提交拉取请求(PR)。它通过编排多个其他技能,系统性地检查代码格式、审查代码、确保测试覆盖并运行测试。

该技能工作量较大,建议将其拆分为多个部分,并将每个步骤作为子代理(subagent)运行。每个子代理应专注于适量工作,以免迷失方向或偏离轨道。

关键原则:每个步骤必须完全解决自身问题后,才能进入下一步。发现问题时无需从头重新开始——就地修复并继续推进。

步骤顺序优先考虑:

  • 先进行代码审查(尽早发现设计与语义问题)
  • 添加任何缺失的测试
  • 运行测试
  • 多种配置(发现配置特定问题)
  • 最后进行格式化(机械性清理)

输入

开始验证前,需收集以下信息(若作为子代理运行,应由调用代理提供;否则自行确定或询问用户):

  • 变更目标:该变更试图完成什么?高层代码审查需要此信息。
  • 变更类型:是新功能、缺陷修复、重构还是性能变更?添加测试步骤需要此信息。
  • 缺陷/问题引用(如适用):对于缺陷修复,提供问题编号。
  • 任何特定关注点(可选):希望额外关注的区域。

若作为子代理调用,提示中应包含:“Validate change for: <goal>. Change type: <type>. <issue reference>”

前置条件

该技能组合了以下几个其他技能:

  • low-level-code-review - 用于机械性代码审查
  • high-level-code-review - 用于语义代码审查
  • adding-tests - 用于分析并添加测试覆盖
  • running-tests - 用于运行各级别测试
  • running-make-to-build - 用于正确构建
  • configuring-the-build - 用于设置不同配置

验证步骤

按顺序执行以下步骤。每个步骤应完全解决其发现的问题后,再进入下一步。

步骤 1:高层代码审查

考虑使用 high-level-code-review 技能作为子代理运行。

启动前,确定 git 范围:

  • 若存在未提交的变更,使用 git diff 和 git diff --cached
  • 否则,使用 git diff master...HEAD

启动提示:“Review the change for: <goal>. Get the diff using <git-command>. <issue reference>”

此步骤审查变更的语义正确性、设计一致性和完整性。子代理将返回按严重程度分类的问题报告。

若发现任何 Critical 或 Major 问题,运行子代理在继续前修复它们。Minor 问题和 Suggestions 可自行决定处理或推迟。

步骤 2:低层代码审查

考虑使用 low-level-code-review 技能作为子代理运行。

启动提示:“Review the diff from <git-command>”

此步骤审查 diff 中无需高层理解的小型机械性编码错误。子代理将返回问题工作清单。

若发现任何问题,运行子代理在继续前修复它们。

步骤 3:添加测试

考虑使用 adding-tests 技能作为子代理运行。

启动提示:“Analyze and add tests for: <goal>. Get the diff using <git-command>. <issue reference>”

此步骤分析变更以确定需要哪些测试并添加它们。子代理将返回已添加测试的报告。

步骤 4:运行测试

考虑使用 running-tests 技能作为子代理运行。

启动前,从 diff 中识别变更的文件/模块。

启动提示:“Run tests through full suite for changes in <files/modules>.”

此步骤运行级别 1-3 的测试:冒烟测试、聚焦测试和完整单元测试套件。子代理将返回详细结果报告。

若任何测试失败,运行子代理在继续前修复问题。

步骤 5:使用多种配置构建并测试

考虑使用 running-tests 技能并扩展级别,作为子代理运行。

启动提示:“Run tests through sanitizers for changes in <files/modules>. Include fuzz tests if protocol-critical code was changed.”

此步骤运行级别 4-6 的测试:sanitizer 构建(ASan、TSan、UBSan)、额外检查构建以及随机/模糊测试。配置选项详情参见 configuring-the-build 技能。

同时验证使用 --disable-tests(生产配置)构建成功。

若任何配置构建失败或任何测试失败,运行子代理在继续前修复问题。

步骤 6:格式化代码

运行 make format 自动格式化所有源代码并验证格式整洁。

始终

  • 始终考虑将长时间运行的步骤作为子代理运行,以保持其专注
  • 始终在进入下一步前完全解决当前步骤中的问题
  • 始终等待每个子代理完成后再继续
  • 始终先运行高层审查,再运行低层审查

绝不

  • 绝不并行运行多个子代理(它们可能冲突)
  • 绝不跳过任何步骤,即使你认为不必要
  • 绝不在所有配置通过前认为验证完成
  • 绝不因为想更快进入测试而跳过高层审查

完成

当所有步骤通过且无需任何代码编辑时,变更即已验证并准备好提交拉取请求。按以下方式总结工作:

  • 已验证内容的摘要
  • 测试过的配置
  • 添加的测试覆盖(如有)
  • 任何无需变更的观察或次要关注点

若验证无法完成(例如陷入循环),报告:

  • 哪个步骤持续失败
  • 哪些问题反复出现
  • 基本方法是否需要重新考虑

若作为子代理调用,将此摘要传回调用代理。