Coding Agent 实现前，先审一遍计划

0阅读9分钟

计划审查：AI 编程中 ROI 最高的质量关卡

Barry Boehm 在 1981 年给出了缺陷修复成本的 1-5-10-100 模型——需求阶段花 1 块钱能修的问题，拖到生产环境就是 100 块。计划审查的价值，就是把 100 块的修复成本压回 1 块。

AI 编程让这个等式更极端：Agent 从接到指令到完成实现可能只需二十分钟，你用来审查代码的窗口被极度压缩，返工的代价却没有同步降低。不在计划阶段拦截方向性错误，就只能等代码写完再推翻。

为什么计划审查比代码审查 ROI 更高

修复成本随阶段递增

Boehm 在 Software Engineering Economics 中量化了这个规律——需求阶段引入的问题，拖到生产环境修复成本可能翻 50 到 100 倍。IBM System Science Institute 的缺陷修复成本模型得出了类似结论。我把这个规律映射到 AI 编程场景：

发现阶段相对修复成本典型耗时
计划审查1×（基准）几分钟
实现过程中5×几十分钟
Code Review10×几小时
生产环境100×一天到数天

传统开发中，程序员花一天写代码，你有充足时间在 Code Review 阶段发现问题。但 Coding Agent 完成一个任务可能只需二十分钟——审查窗口被压缩了，返工代价却没有同步降低。不把审查前置到计划阶段，窗口就只剩更昂贵的 Code Review 或生产环境回滚。

Agent 为什么容易在错误边界内高效执行

这里有一个根本性的张力：Agent 的目标函数和你的人类意图之间存在偏差。

你说「给旧文章补 cover 字段」，脑子里的完整意思是：

检查所有缺少 cover 字段的文章，补上合理的封面图 URL，同时确保 frontmatter schema、TypeScript 类型定义、首页渲染、分类页卡片、详情页头部、sitemap 和 RSS 输出都能正确使用这个新字段。

Agent 接收到的是：

cover 字段 → 文章文件 → 改 frontmatter

这不是 Agent「笨」——它只是缺少你脑子里那些隐含的上下文。它不知道首页依赖 cover 字段做渲染，不知道 sitemap 需要这个字段，不知道类型定义需要同步更新。这些信息分散在你的项目结构、架构决策和过往经验里，Agent 只能从它看到的代码和上下文推断。

2026 年初的一篇分析文章 The Understanding Gap: Why Agentic Coding Systems Fail Before Coding 把这个现象称为「理解鸿沟」——Agent 在实际编码之前就已经在任务理解上产生了偏差，后续代码质量再高也无力回天。另一项 dev.to 案例研究更直接：一个 AI Agent 在同一任务上只获得了人类开发者大约 15% 的可用信息，却在这个信息子集上自信地做出了完整决策。

计划审查就是用来弥合这条鸿沟的。 让 Agent 先输出计划、你来审一遍，几行文字就能发现理解偏差，用不着在几百行代码里事后挖掘。

从 Scope Creep 到 Scope Leap

AI 编程还带来了一种新现象——Hacker News 上有人把这种变化叫「scope leap」：传统范围蔓延是渐进式的，今天加一点明天加一点；AI 编程里，Agent 可以在一个任务中一口气引入大量额外改动——新依赖、跨目录重构、过度抽象。

Frostbyte 的一篇分析指出：AI 工具同时降低了做对和做错事情的成本。构建一个不必要的抽象，和实现一个正确的功能一样快。不审计划的话，你很难分辨哪些改动是任务必需的，哪些是 Agent 自己加戏。

计划审查的三个维度

维度一：任务理解——Agent 要解决的是什么问题

审查计划的第一步，看 Agent 是否抓住了你要解决的问题本身。

好的计划把目标写成行为结果（用户可见的变化），不写成技术动作（改了什么文件）。两者的差别微妙但关键：

维度坏的计划描述好的计划描述
目标表述「修改 Markdown 文件」「旧文章在首页和分类页能正确显示封面图」
验收标准「所有文件都加了 cover 字段」「缺失 cover 的文章补上默认封面，页面渲染无 fallback 占位」
范围感知只提到了源文件提到了受影响的页面、类型定义、SEO 输出
手段与目标「更新组件代码」「分类页能合并展示本地和接口文章」
非目标未说明「不改动路由结构，不引入新依赖」

我的检验方法：把计划的目标描述给一个不了解技术细节的产品经理看，他能不能判断任务是否完成了？ 如果不能，计划还停留在技术动作层面。

维度二：改动范围——Agent 打算改什么、不改什么

范围审查重点看两类风险：

一类是触达了不该改的模块。Agent 为了完成一个小任务，引入了跨目录重构、过度抽象或新依赖。

另一类是遗漏了必须改的边界。Agent 改了列表页，没检查详情页；改了组件，没检查类型定义；改了渲染逻辑，没检查 sitemap 和 SEO 输出。

风险类型信号特征审查动作
过度抽象计划中出现「通用化」「抽取公共逻辑」确认是否只有一处使用，如果是，要求内联
不必要依赖计划中出现新 npm 包要求说明替代方案，对比已有能力是否满足
跨目录改动改动文件跨越 3 个以上目录确认每个目录的改动是否必要
遗漏边界只提到组件层，没有提到类型/配置/SEO要求补全受影响的完整文件清单
隐式假设没有提到验证方式要求列出具体命令和人工验收点

好的计划应该同时包含「做什么」和「不做什么」。缺少非目标声明的计划，等于给了 Agent 自由发挥的空间——在 AI 编程中，这种模糊通常意味着更多改动。

维度三：验证证据——Agent 怎么证明没搞坏

计划必须把验证写具体。「运行测试」不算验证计划，「运行 pnpm typecheck 并通过、pnpm build 零错误、浏览器打开首页确认封面图渲染正常」才算。

任务类型自动化验证人工验证
内容/数据变更typecheck、build、frontmatter 校验脚本浏览器验收关键页面
UI 组件变更typecheck、build、组件单测（如有）浏览器截图对比、多分辨率验收
API/逻辑变更typecheck、build、单元测试接口返回值人工检查
SEO/元数据变更sitemap 生成、llms.txt 校验搜索引擎预览工具检查
配置/环境变更dry-run 命令、diff 检查部署到 staging 后验收

验证计划还应该包含回滚方式——改动上线后出问题，怎么快速恢复。对 AI 生成的代码，这一点尤其重要，因为你对 Agent 的每一行改动未必都有充分的理解。

三个返工案例

案例一：cover 字段的链路遗漏

Agent 把「给旧文章补 cover 字段」理解为「修改 Markdown 文件」。计划里以下问题都没提到：

  • 哪些文章缺少 cover？判断和填充逻辑是什么？
  • frontmatter schema 是否需要扩展？
  • TypeScript 类型定义是否需要同步更新？
  • 首页、分类页、详情页的封面图渲染是否依赖 cover？
  • sitemap 和 RSS 输出是否需要包含？

计划阶段发现这些问题，修正只要两分钟。实现后才发现，就得回滚、重规划、重实现、重验证。

案例二：分类页合并展示的范围盲区

任务：「让分类页能合并展示本地文章和接口文章」。Agent 的计划是「更新分类列表组件，合并两个数据源」。

问题出在哪里：

  1. API 层被忽略了。本地文章和接口文章数据结构不同，需要在 API 层做适配，不能直接在组件层拼接。
  2. 分页逻辑没有提及。合并后分页的 offset 计算、去重逻辑都要重新设计。
  3. SEO 影响没有评估。分类页的 URL 结构、canonical 标签、结构化数据是否需要调整？
  4. 缓存策略没有考虑。两种来源更新频率不同，缓存失效策略需要区分。
审查维度Agent 的计划审查后补充的计划
数据层未提及API 层新增合并查询，定义统一 Article 接口
组件层「合并两个数据源」组件接收统一接口，不关心数据来源
分页未提及基于合并后的总数重新计算分页
SEO未提及验证分类页 URL、canonical、JSON-LD 不变
缓存未提及本地文章用 ISR，接口文章按 staleTime 刷新

正确的做法是把 API 适配层、分页逻辑、SEO 验证作为独立步骤列出，不要把所有复杂度塞进组件层。

案例三：一个不必要的依赖

任务：「给文章列表加一个虚拟滚动」。Agent 的计划：「安装 react-virtuoso，用 Virtuoso 组件替换列表渲染」。

审查时发现：

  • 文章列表最多几十条记录，虚拟滚动的性能收益可以忽略。
  • 新增一个运行时依赖，增加 bundle size。
  • CSS content-visibility: auto 可以作为零依赖的过渡方案。

计划阶段砍掉不必要的依赖，用更轻量的方案先解决问题。计划审查除了检查 Agent 做对了没有，还要检查 Agent 做的事情是否值得做。

计划审查流程

流程图画布 · 115%
Mermaid 流程图加载中...

好的计划 vs 坏的计划

用一个具体任务——「给文章详情页添加阅读时间估算」——对比两种计划的质量差异：

对比项坏的计划好的计划
目标「添加阅读时间组件」「用户在文章详情页能看到预计阅读时间，数值基于正文字数计算」
实现手段「新建组件，在详情页引入」「在 apps/src/components/article/ 下新建 ReadingTime 组件，接收 wordCount prop，在服务端计算」
受影响文件只提到新组件文件新组件 + 详情页 + 文章数据查询层 + 类型定义
非目标未说明「不修改编辑器逻辑，不新增依赖，不做国际化」
验证方式「运行测试」typecheck、build、浏览器打开详情页确认显示、检查阈值是否合理
回滚方式未说明「组件独立，回滚只需还原详情页引用」

坏的计划只说了「做什么」，好的计划同时说了「做什么、怎么做、不做什么、怎么验证、怎么回滚」。

一份计划审查清单

下次审查 Agent 计划时，我按这个清单逐项过一遍。任何一项未满足，通常意味着计划需要补充或修正。

任务理解

  • 计划是否用行为结果描述了目标（用户可见的变化），而非纯技术动作
  • 计划是否用一句话描述了用户/开发者可感知的最终状态
  • 计划是否区分了目标（要解决什么问题）和手段（用什么技术实现）

改动范围

  • 计划是否列出了所有受影响的文件和模块，而非只提到了主要改动点
  • 计划是否明确声明了非目标——哪些不在本次任务范围内
  • 计划中是否涉及跨目录重构、新依赖或过度抽象？如果有，是否给出了理由和替代方案
  • 计划是否考虑了间接影响：类型定义、配置文件、SEO 输出、缓存策略

验证证据

  • 计划是否列出了具体的自动化验证命令（如 pnpm typecheck、pnpm build、pnpm test）
  • 计划是否列出了人工验收点（浏览器验收、截图对比、接口检查）
  • 计划是否区分了自动化验证和人工验证的边界

风险控制

  • 计划是否写明了回滚方式——如果改动出问题，如何快速恢复
  • 计划是否提到了可能的副作用或对其他模块的影响

三个问题挡住大部分返工

审计划比审代码省成本。计划阶段发现问题，改几行文字就够；实现后才发现范围错了，就得回滚、返工、重新验证。

AI 编程让这个问题更突出——Agent 执行速度远快于人类审查速度，不把审查前置到计划阶段，就只能用更贵的 Code Review 或生产环境回滚来弥补。

下次让 Agent 动手之前，我先问它三个问题：

  1. 你要实现的行为结果是什么？（用户看到什么变化，而非改了什么文件）
  2. 你不改什么？（明确不在范围内的东西）
  3. 你怎么证明没有搞坏？（具体命令和人工验收点）

这三个问题能挡住大部分返工。Agent 的代码能力通常够用，问题在于它在错误边界内执行得越快，返工成本越高。计划审查就是确保边界正确的最低成本手段。

参考资料

评论 0

我
0 / 1000