Synthesis Code Audit 是一个代码审计技能,用于对一次代码差异(diff)做系统性的质量度量。它明确区分“审计”和“评审”:审计输出跨十个正交维度的评分报告,指出质量问题所在;是否合并由评审者决定(相关评审工作见 synthesis-pr-review)。
绑定规则
- 只度量,不决策:审计给 diff 打分,合并由评审者决定。当其他工作流(preflight、PR review)调用审计时,把发现返回给该工作流。
- 始终对比新的基线引用,而不是过期的本地基线:过期基线会同时造成误报和漏报。
- 完整阅读每个变更文件,而不仅是 diff 片段;文件上下文能说明改动是否合理。
- 向评审者提供完整需求(冻结的产物范围、用户结果、验收标准、排除项、决策),但不预设结论;对有误的前提用证据质疑,修订意见交给决策负责人。
- 评定变更行为及其受影响的消费方。即使阻塞性缺陷的代码行早于本次 diff,它仍是阻塞项;无关发现单独记录,绝不把未审查代码称为干净。
- 显式应用项目规范,包括更强的“顺手修复”规则;不对本次 diff 未改动的代码挑风格小毛病。
- 部分覆盖记为 Incomplete,绝不为 Clean。跟踪已审查与未审查路径;UNKNOWN 维度或未审查路径不能满足就绪门槛。
- 复用既有发现时,须绑定到实际 diff、所需消费方与证据输入;材料变化会重新打开相关判断。
参考文件
- references/dimensions.md:十个维度各自检查什么,评分任一维度前先阅读。
- references/principles-and-rules.md:本技能与 pr-review、codebase-review 的关系定位,以及四条原则和规则的完整文本。规则适用范围不清或在技能间选择时阅读。
- references/coverage-map.md:1.1.0 版文本各部分现所在位置。
Diff 范围检测
确定审计对象:
- 存在未提交改动:对照 HEAD 审计已暂存和未暂存的改动。
- 分支有领先基线的提交:审计从基线到 HEAD 的范围。
- 无可比较内容:报告并停止。
大型 diff(40 个以上文件):按后果优先调查,包括影响执行或供应链完整性的配置、生成资源和锁文件;把冻结范围划分为有界评审任务,设一名集成负责人;显式跟踪已审查与未审查路径。部分覆盖产生不完整审计,绝不给出无条件的 Clean 结论;须在打包通过前完成必要覆盖。
十维框架
对每个维度评估变更代码,并给出以下之一:
- PASS:无问题,或仅有琐碎风格偏好
- WARNING:值得关注但不阻塞发布(缺少边界测试、轻微不一致、可改进的模式)
- FAIL:具体缺陷、安全漏洞、规范违规或缺失覆盖,应在合并前修复
- UNKNOWN:无法从现有证据或已完成的评审覆盖中建立所需判断
十个维度(详见 references/dimensions.md):
- 项目规范合规
- 代码复用——优先使用现有实现
- 与现有模式的一致性
- 安全
- 可扩展性与企业就绪
- 未来适应性(不过度工程)
- 代码质量
- 测试覆盖
- 文档与注释
- 清理
报告方式
以表格呈现发现,列为 #、维度、结果、备注,逐行列出十个维度及结果与细节。表格下方给出一行结论:
- “Clean”:完整声明范围内所有适用维度 PASS,并附带精确的源码/基线绑定
- “Has warnings”:存在一个或多个 WARNING,无 FAIL
- “Has blockers”:存在一个或多个 FAIL
- “Incomplete”:任一必需维度或声明范围的一部分为 UNKNOWN 或未审查;不能满足就绪门槛
随后列出可执行的发现,附文件与行号引用;对每个问题说明错在哪里以及如何修复。
PR 评审模式(交叉比对)
作为 PR 评审工作流的一部分被调用时,可获得既有评审评论作为上下文(包含评审者、文件路径、行号、评论内容的条目列表)。完成全部十个维度后,逐条交叉比对:
- 文件+行号匹配:同一文件 ±10 行内是否有既有评论?
- 语义匹配:既有评论是否提出同一类问题(例如都在指出缺少鉴权、都在指出重复)?
为每条发现标注:
- [Already noted by @reviewer]:同一位置存在相同或非常相似的关注
- [Related to @reviewer's comment on file:line]:相似关注,位置不同
- [New finding]:未被任何既有评审者覆盖
最后给出交叉比对摘要:新发现与已被覆盖发现的数量统计。该模式不改变检查哪些维度或如何评估问题,只增加重叠标注,让评审者知道自己的评审在何处增加新价值、在何处确认已有反馈。