用途
该技能用于验证一项代码变更是否正确、完整,并已准备好提交拉取请求(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 自动格式化所有源代码并验证格式整洁。
始终
- 始终考虑将长时间运行的步骤作为子代理运行,以保持其专注
- 始终在进入下一步前完全解决当前步骤中的问题
- 始终等待每个子代理完成后再继续
- 始终先运行高层审查,再运行低层审查
绝不
- 绝不并行运行多个子代理(它们可能冲突)
- 绝不跳过任何步骤,即使你认为不必要
- 绝不在所有配置通过前认为验证完成
- 绝不因为想更快进入测试而跳过高层审查
完成
当所有步骤通过且无需任何代码编辑时,变更即已验证并准备好提交拉取请求。按以下方式总结工作:
- 已验证内容的摘要
- 测试过的配置
- 添加的测试覆盖(如有)
- 任何无需变更的观察或次要关注点
若验证无法完成(例如陷入循环),报告:
- 哪个步骤持续失败
- 哪些问题反复出现
- 基本方法是否需要重新考虑
若作为子代理调用,将此摘要传回调用代理。