让 AI 做代码评审:从「帮我看看」到可复用的检查清单
第一版评论一半是“建议加注释”。改成只喂 diff、按固定检查项判定、强制 JSON 输出后,评论从每条 MR 十八条降到四条,有效率从三成涨到八成。
团队里每个人都说"AI 评审挺好用",但真正把它挂到合并请求上之后,评论区的画风很快就变了:一半是"建议为该函数补充注释",另一半是"可以考虑使用更优雅的写法"。作者逐条回"已改",改完代码更长,实际问题一个没少。
我前后调了六七版提示词,最关键的一步不是措辞,而是限定输入和输出:只让它看 diff,只让它按固定检查项输出 JSON。这两条定下来之后,有效评论的比例才从三成左右涨到能用的程度。
一、第一版:把整个文件丢进去,得到一堆正确的废话
最初的调用很简单,把改动文件的全文贴进去,加一句"请帮我评审这段代码"。
结果可以预期:模型会通读全文,挑最显眼的地方评论。它不知道哪几行是这次改的,于是把三年前写的旧代码也评一遍;它不知道团队规范,于是给出"加注释""提取常量"这类放之四海皆准的建议。
更麻烦的是格式。二十条评论里,作者要自己判断哪条是阻塞问题、哪条是风格偏好,判断成本比不看还高。
二、输入只给 diff,上下文只给必要的
改成只传 diff 之后,评论立刻收敛到本次改动。命令很普通:
git diff --unified=5 origin/main...HEAD -- '*.java' > /tmp/mr.diff
wc -l /tmp/mr.diff
--unified=5 比默认的 3 行多给一点上下文,模型判断"这个方法上一行有没有判空"时需要它。但也不能给太多,diff 超过两三千行时我会按文件切分,一次只评一个文件 —— 一次性塞进去,模型对后半段的注意力会明显下降,实测漏报集中在 diff 尾部。
有些信息 diff 里没有,但评审必须知道,这些单独补:
- 这次改动的目标(一句话,从 MR 描述里取);
- 相关的接口签名或表结构(只贴被改动到的那几个);
- 团队明确禁止的写法清单。
# 把 diff 和背景拼成一个请求体,避免超长时截断在代码中间
python build_review_input.py \
--diff /tmp/mr.diff \
--intent "订单超时关闭改为延迟消息触发" \
--rules rules/backend.md \
--max-chars 12000 \
--out /tmp/review_input.json
--max-chars 是硬截断保护。没有它,一个大的重构 MR 会把上下文顶满,接口直接报超长,整条流水线红掉。
三、把"评审"拆成可判定的检查项
这是效果提升最明显的一处。原来提示词写"请检查代码质量",现在改成一张固定清单,每条都要明确判定标准:
| 检查项 | 判定标准 | 常见误报 |
|---|---|---|
| 空值与边界 | 新增的入参是否有 null / 空集合 / 越界分支 | 上游已保证非空但 diff 里看不到 |
| 事务边界 | 写操作是否在同一事务内,异常是否回滚 | 方法被同类调用时事务已存在 |
| 并发安全 | 共享可变状态是否有锁或不可变 | 单线程调用链被误判 |
| 资源释放 | 流、连接、锁是否在 finally / try-with-resources | 框架托管被误判 |
| 错误处理 | 捕获后是否吞异常、是否丢失上下文 | 有意降级被误判 |
| 日志与脱敏 | 是否打印了手机号、证件号、token | 字段名相似被误判 |
| 可测性 | 是否引入静态依赖导致无法单测 | 项目已有测试基建 |
清单里每条都配一句"什么情况不算问题"。这一句是降误报的关键:不给排除条件,模型会把所有相似形态都报成问题。
你是资深后端评审者。只评审 <diff> 中新增或修改的行,不要评价未改动的代码。
按下面的检查项逐条判断,只有能指出具体行号和具体后果时才输出。
检查项:
1. 空值与边界:新增入参是否可能为 null / 空集合 / 越界。若上游方法签名已标注非空并做了校验,不报。
2. 事务边界:写操作是否与读操作混在同一事务外。若该方法由已开启事务的上层调用,不报。
...
输出要求:只输出 JSON 数组,不要输出解释性文字。
四、强制结构化输出,让机器先过滤一遍
自然语言评论无法自动分流,所以输出必须是结构化的:
{
"findings": [
{
"file": "src/main/java/com/example/order/OrderService.java",
"line": 128,
"rule": "空值与边界",
"severity": "high",
"confidence": 0.82,
"message": "closeOrder 收到 null 的 orderNo 时直接拼进 SQL,会命中全表更新",
"suggestion": "入口处校验 orderNo 非空,或改为按主键更新"
}
]
}
三个字段决定了它能不能用:
line必须落在 diff 的新增行范围内,否则评论会挂到不相干的位置;severity只允许high/medium/low,对应"阻塞 / 建议 / 风格";confidence让我们可以按阈值过滤,先只把高置信度的推给人。
拉回来之后先做一次结构校验,不合格的直接丢弃而不是硬解析:
import json, sys
raw = open("/tmp/review_raw.json", encoding="utf-8").read()
try:
data = json.loads(raw)
except json.JSONDecodeError:
print("unparsable, drop batch")
sys.exit(0)
valid = [f for f in data.get("findings", [])
if f.get("severity") in {"high", "medium", "low"}
and isinstance(f.get("line"), int)
and f.get("confidence", 0) >= 0.6]
print("kept %d/%d" % (len(valid), len(data.get("findings", []))))
五、误报要治,而不是忍着
头两周我们统计了一下:high 级别的评论里,大约四成是误报,主要集中在上游已保证非空、以及框架已经托管资源这两类。逐条去解释不如从源头压:
- 在提示词里补"排除条件",把已知的误报模式写成明确的"不报";
- 对重复出现的误报建立关键词黑名单,命中就降级为
low; - 每周抽十条
high评论人工标注,作为下一次调提示词的样本。
这套做法和调分类模型没区别:先有标注,再谈优化。我们建了一个二十条的小样本集,每次改提示词都跑一遍,看误报率有没有降、漏报有没有涨。
| 版本 | 评论条数(每 MR 均值) | high 占比 | 人工判定有效率 |
|---|---|---|---|
| 只看全文,自然语言输出 | 18 | 21% | 约 30% |
| 只给 diff,自然语言输出 | 11 | 26% | 约 45% |
| diff 加固定检查项,JSON 输出 | 6 | 34% | 约 70% |
| 再加排除条件与置信度阈值 | 4 | 41% | 约 80% |
评论总数降了,但有效率高了一倍多。评审这件事,少而准比多而杂有用 —— 作者不会逐条读二十条评论。
六、接进流水线:限流、超时、失败不阻塞
最后一公里是工程问题。三个原则:
- 超时短:评审步骤给 120 秒,超时就跳过并留一条日志,不能卡住合并;
- 失败不阻塞:模型接口 5xx 或返回不可解析,按"未评审"处理,不要标红整条流水线;
- 每 MR 只跑一次:用 MR 的 head sha 做去重键,force push 后 sha 变了才重跑。
# 简化的调用与降级
sha=$(git rev-parse HEAD)
if [ -f ".review-cache/${sha}.done" ]; then
echo "already reviewed"; exit 0
fi
timeout 120 curl -sS -X POST "$LLM_ENDPOINT" \
-H "Authorization: Bearer $LLM_API_KEY" \
-H 'Content-Type: application/json' \
-d @/tmp/review_input.json -o /tmp/review_raw.json || {
echo "review skipped: timeout or error"; exit 0
}
python post_review.py --raw /tmp/review_raw.json --mr "$MR_ID" || exit 0
touch ".review-cache/${sha}.done"
注意 || exit 0 这两处。评审是辅助手段,它挂了不该挡住人。真正需要挡住的是编译失败和单测失败,那些有确定性。
七、哪些事不要交给它
用了一个多月,有几类评论我直接关掉了:
- 架构与拆分建议:模型只看得到一个文件的 diff,看不到模块依赖,建议往往是想当然;
- 性能优化:它会把所有循环里的字符串拼接都报成问题,而实际热点根本不在那;
- 命名与风格:这类交给格式化工具和 lint,确定性更高,也不消耗 token。
留下的是它真正擅长的:空值、边界、资源释放、异常吞掉、日志脱敏。这些有明确的判定标准,人能写清规则,模型也能稳定执行。
小结
- 输入只给 diff 加必要背景,全文喂进去只会得到"正确的废话",还会漏报 diff 尾部。
- 把"评审"拆成带判定标准和排除条件的固定检查项,是降误报最有效的一步。
- 输出必须结构化:行号、严重级别、置信度,先机器过滤再给人看。
- 误报靠标注治理:建小样本集、每次改词跑一遍、把重复误报写成"不报"。
- 少而准优于多而杂:评论总数从 18 条降到 4 条,有效率从三成涨到八成。
- 流水线里给短超时、失败降级、按 sha 去重;评审挂了不能挡住合并。
- 架构建议、性能优化、命名风格不要交给它,这些要么信息不足,要么有更确定的工具。
正在加载评论…