把设计文档交给 AI，代码审查更有用

把 PR 的 diff 交给 AI，它能挑出一些代码问题；再把设计文档和用户故事交给它，审查才有了另一把尺子：这次改动有没有实现团队约定的需求。作者在真实项目里试了这套做法，找出了控制器阻塞、权限配置错误和登录故障。

这篇最值得借鉴的，是把文档变成可引用的审查依据。不过，案例能证明这种做法有用，还不足以证明它比其他审查方案更划算。尤其要分清：AI 提交了审查意见，不代表它已经验证了程序能正常运行。

AI 审查缺的，可能是判断对错的依据

作者给出的行业数据说明，AI 审查已经相当普遍。原文引用 GitHub Blog 2025 年数据称，Copilot 首年完成超过 6000 万次审查，使用量增长 10 倍，超过 12,000 家组织为每个 PR 开启自动审查，平台超过五分之一的审查有 AI 参与。

JetBrains 2025 年数据则称，44% 的开发者使用 AI 审查代码，Web 开发者和 DevOps 工程师分别达到 52% 和 49%。原文开头把 44% 写作团队采用率，正文写作开发者采用率，统计口径并不一致。另外两组数据覆盖的是更宽泛的 AI 工具使用：JetBrains 2026 年的 90%，以及 Stack Overflow 2025 年「已使用或计划使用」的 84%，不能直接当作代码审查采用率。

普及程度之外，作者关心的是审查目标。

单看 diff，审查者可以判断代码是否清楚、是否存在常见错误，却未必知道业务对象选错了。作者提到，一个表单实现看起来合理，但它操作的领域对象与用户故事要求不符。要发现这个问题，必须知道需求写了什么。

他们给 Agent 的输入有三类：设计文档、PR diff、用户故事 ID。Agent 通过 GitHub pull request API 获取差异和相关文件，对照架构及需求，直接提交行内评论，以及 REQUEST_CHANGES 或 APPROVE。批量处理时，每个 PR 分配一条独立调查线程，并行阅读不同代码区域。

作者称之为规范感知审查（spec-aware review）。大白话解释，就是让审查者同时拿着代码和验收依据，能够指出「这段实现违反了文档的哪一节」。

设计文档的价值，是给 AI 一个可以核对的正确答案范围。

三类故障，说明审查不能停在代码表面

最直观的案例来自 Kubernetes reconciler。下面这段代码能通过编译，但资源未就绪时会长时间占用工作线程：

// Agent 拦下的反模式：在 Reconcile 内休眠
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    if !resourceReady(ctx) {
        time.Sleep(30 * time.Minute) // 占用共享工作线程 30 分钟
        return r.Reconcile(ctx, req) // 使用递归，而非重新入队
    }
    // ...
}

要盯住的是 time.Sleep(30 * time.Minute) 和后面的递归调用。controller-runtime 使用共享工作池，休眠会占住其中一个 worker，降低其他任务的处理能力；是否拖住整个控制器，还取决于并发配置和任务分布。

原文给出的替代方式，是返回 ctrl.Result{RequeueAfter: time.Minute}, nil，把控制权交还工作队列，由管理器在一分钟后安排重试。

第二类是 RBAC 配置。清单把 API group 写成了 platform.example.io，实际资源却属于 labs.platform.example.io。配置能够正常应用，但授权没有覆盖控制器真正访问的资源，错误要到运行时才暴露。审查需要把权限声明和资源定义放在一起核对。

第三类是 OIDC 登录流程。Agent 在另一条 PR 中发现三个问题：中间件文件没有被框架调用，session token 被作为 header 发送而没有作为 cookie 转发，以及 identity-provider URL 被直接暴露给浏览器。作者称，这些问题共同导致登录无法完成。

这里需要保留一点审慎：原文没有交代框架、部署结构和完整认证链路，尤其没有说明第三项为何在该系统中构成故障，不能据此推导出所有项目都应隐藏身份提供方 URL。

这些案例也有区别。表单操作对象错误，直接体现了需求文档的作用；休眠和 RBAC 错误，则也可能被熟悉框架的审查者、专项规则或其他静态检查发现。原文没有做对照实验，无法确定每个发现有多少收益来自设计文档。

接入流程时，先把审查标准写清楚

作者把落地方法归纳为四件事：文档入库、输入结构化、结论有标准、CI 保持建议性质。

架构文档、用户故事和接口契约应与代码一起做版本管理，让审查依据随分支变化。提示词明确给出 PR URL、相关文档章节和用户故事 ID，先核对需求，再检查一般代码质量。这个顺序能避免输出被命名、格式等意见占满。

结论也要分级：违反明确需求或引入运行故障模式时使用 REQUEST_CHANGES；满足对应用户故事并通过质量检查时使用 APPROVE；风格问题只发表评论。

下面的配置展示了如何在 PR 创建和更新时触发审查：

name: spec-aware-review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run agent review against design docs
        run: ./scripts/review-against-spec.sh
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          DESIGN_DOCS: docs/architecture,docs/user-stories
      # 结论以评论发布，不作为必须通过的状态检查。

要注意最后一行注释：是否阻止合并，还需要仓库规则配合，这段 YAML 本身并不能证明审查一定只作建议。原文也没有提供 ./scripts/review-against-spec.sh 的实现，模型调用、文件读取和审查结果发布都需要团队自行补齐。

作者还提到，GitHub 在 2026 年 3 月把 Copilot review 从逐行 diff 审查推进到能够调用工具、探索仓库和追踪跨文件依赖的方式。这支持了扩大上下文的方向，但不能单凭这一变化就断言模型规模不再影响审查质量。

我的判断

我赞成把明确需求放进审查输入。它比一句「看看有没有问题」更容易得到可核对的意见，也能让人类判断 AI 是否误报。对于跨文件接口约束、权限配置和用户故事验收，这种方式尤其值得尝试。

但文档必须准确。过期设计会把正确实现判错，含糊需求会让 Agent 自行补全规则。文档放在仓库里只是方便同步，并不会自动消除歧义。

原文没有公开样本规模、误报率、漏报率、耗时和费用，也没有比较「仅 diff」「diff 加仓库上下文」「再加设计文档」三种方案。因此，「这是平台团队今年回报最高的投入之一」仍是作者的经验判断。

执行能力的限制更具体：他们这次使用的 Agent 不能运行代码，部分被标为「Request Changes, minor」的 PR，后来实际存在阻断性故障。它能推理风险，却没有观察到运行结果。这个限制属于本次配置，不能推广成所有 Agent 都无法执行代码。

AI 的 APPROVE 不能替代运行验证，也不能替代安全审查。

原文引用 Veracode 2025 年数据称，45% 的 AI 生成代码未通过 OWASP Top 10 检查，29.1% 的生成 Python 代码带有安全弱点。这些是生成代码的数据，并非本次审查实验的漏报率，但足以提醒团队保留独立安全扫描。

另外，文章开头说 Agent「拦住了 PR」，后文又明确说它的 REQUEST_CHANGES 本身不阻止合并。更准确的理解是：它发现问题并要求修改，最终仍由人确认、运行验证并决定是否合并。

能拿来做什么

• 在前端表单或业务页面 PR 中附上用户故事 ID、目标领域对象和验收条件，让 AI 先核对功能是否做对，再讨论代码质量。
• 为 Node 或全栈登录改动提供中间件入口、cookie 转发规则和认证流程文档，并要求审查意见引用具体文件；随后实际跑通登录流程。
• 先把 AI 审查接成非必需检查，区分需求违背、运行风险和风格建议，再观察它的有效发现与误报情况。
• 把架构文档和接口契约纳入 PR 更新范围；出现实现与文档冲突时，由维护者先确认哪一份代表当前约定。