上下文感知的 AI Code Review：从 Diff 到可验证的工程审查
type
status
date
slug
summary
tags
category
icon
password
wechat_gate
上下文感知的 AI Code Review，核心不是把更长的代码塞给模型，而是让审查者同时看到代码 Diff、仓库规则、任务验收标准和相关依赖。这样 AI 才能回答“这段代码是否符合这个系统的意图”，而不只是“这段代码看起来像不像常见写法”。
我最近整理了一组 AI Code Review 实验，里面有一个很值得警惕的对比：同一组 PR，只给 Diff 的审查容易漏掉任务级问题；加入代码库和任务上下文后，Precision、Recall 和 F1 都明显改善。但这并不意味着 AI 可以替代开发者，它更像一个需要被正确喂养、被独立验证、被人最终裁决的审查系统。
本文会从四个问题展开：为什么 Diff-only 不够、上下文应该如何组织、为什么“全部代码”也不是好答案，以及如何用专用 Agent 和风险分级把审查结果变成可执行的工程决策。
为什么只看 Diff 的 AI Code Review 容易漏问题
代码变更本身通常不是完整需求。一个新增字段，可能影响 API 契约、数据库迁移、前端状态映射、下游服务和监控告警；一个重试逻辑的简化，可能破坏幂等性，却不会在局部代码里留下明显的语法线索。
素材中的一个单例实验很直观：对
update_user 接口只提供 Diff，审查器找到了 4 个问题，包括缺少认证授权、参数未校验、异常处理不足和响应信息不完整。但在“预期问题”集合里，Diff-only 没有命中关键问题。换句话说，报告数量不等于审查质量，问题是否和真实任务相关更重要。
这里有一个容易被忽略的区别：
- Diff-only 问的是“这段修改有哪些看起来不妥的地方”。
- Context-aware 问的是“这段修改是否违反了当前项目和任务的约束”。
后一个问题才接近人类 Code Review 的实际工作。
上下文感知的 AI Code Review，应该提供哪些信息
上下文不是越多越好，而是要覆盖影响判断的几类信息。
1. 任务上下文：代码要实现什么
任务描述最好包含目的、边界、验收标准和不应改变的行为。例如，“增加支付状态”远远不如下面的描述可审查：
有了这些标准，审查器才能判断“接口返回成功”究竟是合理实现，还是绕过了任务要求。
2. 仓库上下文：项目如何实现
仓库规范、架构决策、模块边界、错误处理约定和安全规则，往往不会完整写在 Diff 里。GitHub 文档也建议通过自定义指令补充项目背景、编码规范、安全要求、幂等性和敏感数据处理规则；VS Code 的官方实践同样强调，应该把模型无法从代码推断出的架构决策和非默认约定写进项目级指令。
值得注意的是，规则要短而具体。把几十页团队手册原样贴进 Prompt，通常只会稀释真正重要的约束。更可行的方式是把规则拆成“项目通用规则”和“某类代码专用规则”，并让它们能被审查结果引用。
3. 相关代码上下文：这次修改会影响谁
相关代码包括调用方、被调用方、同类实现、测试、配置和历史变更。它们不一定全部放进上下文窗口，但应该通过检索选出最相关的片段。
在实验中，一个小型 FastAPI 仓库有 25 个文件、1126 行代码。经过 AST 分块后得到 99 个类、函数和测试片段，再为这些片段创建 Embedding 并写入 Chroma。对一个“增加用户搜索功能”的 PR，检索器可以优先找到
list_users、search_reports 等相关函数，而不是把整个仓库一股脑交给模型。全量上下文为什么可能不如选择性检索
直觉上，给模型完整代码库似乎最稳妥。但全量上下文会引入三个问题：
- 相关信息被大量无关代码淹没。
- Token 成本和延迟随仓库规模增长。
- 审查结论难以说明“到底依据了哪条规则和哪段代码”。
实验中的对比是：Full Context 使用 99 个片段、超过 31000 个字符；Selective Context 只使用 15 个片段、约 3500 个字符，规模减少 88.9%。在 15 个 PR 的评估里，选择性上下文的 F1 优于全量上下文。
这组结果的正确解读不是“上下文越少越好”，而是“上下文要和审查问题相关”。真正值得投入工程工作的地方，不是不断扩大 Prompt，而是建立可靠的 Context Engine：
AST 分块的价值在于保留代码结构。按固定字符数切片很容易把函数签名、异常处理和返回逻辑拆开；按函数、类和测试切分，更适合后续定位“哪个行为与当前 Diff 相关”。不过 AST 也不是万能的：跨服务契约、配置含义和业务规则仍然需要任务文档与人工维护的规则补充。
独立审查 Agent，比让写代码的 Agent 自我复核更可靠
让同一个 Coding Agent 写完代码后立刻自审，当然有价值，尤其适合在提交 PR 前快速发现低级问题。但它存在明显的同源盲区：生成和审查共享相同的上下文选择、推理路径和假设，可能一起忽略同一个问题。
更稳妥的流程是：
- Coding Agent 根据任务实现代码。
- 本地先做一次 Pre-PR Review，修复明显错误和测试缺口。
- 把 PR 交给独立审查 Agent，重新收集跨文件、跨规范和安全问题。
- 人类开发者确认严重程度、修改方案和是否合并。
素材中的支付 API 示例体现了这种差异。同一个新增支付状态的 PR，提交前本地审查发现 5 个问题；经过清理后，独立 PR 审查只剩 3 个更高信号的问题。这里的价值不是“问题变少”，而是把可以提前处理的噪声留在本地，把开发者注意力集中到真正需要判断的部分。
用风险分级决定什么能自动修，什么必须人工判断
AI 审查最糟糕的体验，是把拼写、文档、权限绕过和数据一致性问题全部显示成同样紧急。一个可执行的分级可以是：
风险级别 | 典型问题 | 推荐动作 |
低 | 文档缺失、命名不一致、非阻断式重构建议 | 可自动修复，或合并前集中处理 |
中 | API 文档过期、测试不足、实现与任务边界存在歧义 | 与开发者讨论，必要时拆分 PR |
高 | 权限绕过、注入风险、数据丢失、幂等性破坏、不可逆迁移 | 阻止合并，要求代码修复与测试证据 |
例如，支付 capture 流程去掉
Idempotency-Key 强制校验，可能造成重复捕获或重复结算。这不是普通风格建议，而是需要阻止合并的问题。相反，README 与新接口暂时不一致，通常可以单独开一个文档 PR，不必让它阻塞业务代码。风险分级最终服务于注意力管理，而不是替开发者做决定。高风险问题要能回溯到具体代码、任务条款或项目规则；如果审查器只能说“可能有风险”，就不应该直接把它当作阻断理由。
专用 Agent 的价值：让不同问题由不同角色负责
安全、架构一致性、业务规则和测试完整性并不是同一种推理任务。把它们全部压给一个通用审查器，往往会在覆盖面、精度和成本之间反复妥协。
实验采用了一个简单的 ensemble 结构：Security Agent 专注漏洞，Pattern Compliance Agent 专注代码库模式，再由汇总层去重并生成最终结果。上下文引擎保持不变，只改变审查 Agent 的职责。15 个 PR 的结果中，ensemble 的 F1 为 71.1%，通用 Agent 为 60.6%；同时 Recall 有轻微下降。
这个结果非常重要，因为它说明专用 Agent 并非单纯“全面更强”。它提升了 Precision，减少噪声，但可能漏掉部分不属于其专长的问题。生产系统应该把它看成分层防线，而不是一个神奇的总审查员：
- 安全 Agent：认证、授权、注入、秘密泄露和敏感数据。
- 业务规则 Agent：状态机、幂等性、结算和权限边界。
- 代码库模式 Agent：模块边界、异常处理、日志、命名和测试约定。
- 人类审查者：最终风险判断、取舍和合并责任。
我会如何把它落到日常开发流程
我更倾向于把 AI Code Review 设计成一条“证据链”，而不是一个自动批准按钮。最小可用版本可以从下面的输入契约开始：
然后要求审查结果至少包含：问题位置、违反的规则或验收标准、影响、严重程度、复现或验证方式，以及“为什么不是误报”。这一步会显著提升结果的可讨论性，也便于把反复出现的真实问题沉淀为规则或 Agent Skill。
我自己的判断标准是：一次审查没有结束，直到我能回答三个问题——它依据了什么、我如何验证它、修复后如何防止再次出现。审查 Agent 可以帮我找问题和解释风险，但不能替我承担合并责任。
一个失败教训：更多发现，不等于更好的审查
这组材料里最值得保留的反面经验，是 Diff-only 审查看起来也能产出多个高严重度问题，但对预先定义的关键问题没有命中。若只看“发现了几个问题”，很容易误以为审查器很强；一旦和已知问题集合对照，结果就不一样了。
另一个边界是，实验使用的是 15 个合成 PR，仓库规模也较小。它能说明上下文策略的方向性差异，却不能直接推出某个生产系统的绝对准确率。上线前仍然需要用真实历史 PR 建立基线，并持续记录误报、漏报、人工采纳率和修复后回归情况。
总结：把 AI 审查变成可验证的协作系统
AI Code Review 的关键竞争力不只在模型，而在上下文工程和反馈闭环：
- 任务上下文告诉审查器“应该实现什么”。
- 仓库上下文告诉它“这个项目如何实现”。
- 选择性检索告诉它“本次变更真正相关的是什么”。
- 独立审查 Agent 帮助打破生成与审查的同源盲区。
- 风险分级把结果转成开发者可以执行的注意力分配。
- 人类判断把真实经验沉淀为规则和专用 Skill。
最终形成的是一个循环：Review、Judge、Codify、Reuse。AI 可以加速发现问题，但只有当发现能被证据支撑、能被验证、能反馈到下一次审查时，它才真正成为工程能力。
参考资料
- Build an optimized review process with Copilot，GitHub Docs
- Best practices for using AI in VS Code，Visual Studio Code 文档
- Code Review，Claude Code 文档
关注沐风，不定期更新，全是干货。
2026.08.29
沪 · 赵巷