过去一年，围绕 AI Coding 的讨论里，Spec / Plan / 设计文档几乎被当作了“解药”。

似乎只要模型能先生成一份 Spec，再由 Agent 按图索骥，复杂任务似乎就可以被自动完成。

但在实际工程实践中，结论往往并不乐观。这里问题并不在于 Spec 本身不重要，而在于——我们正在用一种错误的方式，去理解和生成 Spec。

我们在说的 Spec，到底是什么？

当前语境下，大家对 Spec 的默认理解往往是：

• 在编码前生成的一份文档

• 描述实现步骤或技术方案

• 一次性完成，用于驱动后续执行

这种理解，本质上继承自传统软件工程流程。但在 AI Coding 场景中，这个定义本身就存在偏差。

Spec 的真正价值，并不在于“计划本身”，而在于它是否承载了足够完整的上下文。

换句话说：

Spec 不是 Plan，而是“上下文的显式化表示”。

如果上下文是错的或不完整的，再精致的 Spec，也只是在系统性放大错误。

一次性生成 Spec，为什么在机制上必然失败？

当前大量 AI Coding 的实践，都隐含了一个假设：

在上下文不完整的前提下，让模型一次性生成一份可用的 Spec。

这个假设在机制上是站不住的，主要有两个原因。

1. 模型天然存在“快速收敛”的生成倾向

大模型在生成内容时，目标并不是“充分理解问题空间”，而是尽快产出一个看起来合理、结构完整的答案。

这会带来几个典型后果：

• 在信息探索上，模型倾向于在“够用”的地方就停了

• 在代码库搜索中，一旦找到可行实现，很少主动做反证式分析或者交叉验证

• 在不确定的地方，默认使用最常见、最安全的假设

而 Spec 恰恰需要的是：

• 全面性

• 边界条件

• 被否定方案以及否定的原因

• 隐性约束的显性化

这与模型的默认生成是相反方向的。

2. 上下文缺失时，模型只能“编造合理性”

在 Coding Agent 场景中，模型能直接获取的上下文主要是：

• 代码结构

• API 与类型信息

• 有限的历史提交

这部分我们可以称为技术上下文。但真正决定任务能否正确完成的，往往是另一类信息：

• 为什么现在要做这件事

• 成功的判定标准是什么

• 哪些方案在历史上被否定过

• 哪些约束写不进代码，但绝对不能触碰

也就是业务上下文。

而这部分上下文，目前并不存在于代码仓库中，也无法通过搜索自动补齐，只能由人提供。

在这种情况下，一次性生成的 Spec，本质上只是“合理幻想”。

从第一性原理看 AI Coding 的真实瓶颈

如果从第一性原理来抽象问题，其实非常清楚：

智能模型 + X = 可完成的任务

那么这个 X，一定不是流程，而是充足的上下文。

这两年，模型的“智能”提升极快，但 AI Coding 能独立完成的任务边界并没有等比例扩大，根本原因就在于：

• 技术上下文在增长

• 业务上下文几乎没有被系统性地纳入

因此，没有业务上下文的 Coding Agent，本质上只能做代码层面的自动化，而不是任务层面的自动化。

小任务为什么“看起来可行”，大任务却必然翻车？

这也是一个经常被忽略，但在工程上非常重要的边界条件。

• 对于 0.5 PD 或 1 PD 的小任务

上下文简单、约束清晰、失败成本低

一次性生成的 Plan / Spec 偶尔是可以工作的

• 但对于持续时间超过一周的复杂任务

上下文高度耦合、隐性约束大量存在

一次性生成的 Spec 几乎必然失效

这不是模型能力问题，而是问题复杂度的自然结果。

Spec 不应该被“生成”，而应该被“讨论”出来

基于以上现实约束，我们在实践中逐渐形成了一种不同的 AI 使用方式，我把它称为“讨论模式”。
这里的“讨论”，并不是闲聊，而是一种有意识的工程行为：

• 刻意放慢模型的收敛速度

• 不允许一次性给出完整方案

• 通过反复追问，逼迫假设、边界和不确定性显性化

在这种模式下：

• Spec 不是一次性生成的文档

• 而是在多轮对话中逐步成型的上下文结构

本质上，这是在用对话的方式，构建一个可执行的上下文模型。

大型任务中，Spec 必须前置，而不是“边写边改”

对于持续时间超过一周的复杂任务，一次性生成的 Plan 或 Spec 几乎必然失效。

因此，在我们的实践中，Spec 不再是一个“顺手写一下”的中间产物，而是被明确前置，成为整个任务中最重要的阶段。

具体来说，对于评估在10 PD 级别的需求，试过三种不同的开发范式。

1. 传统开发方式（≈ 10 PD）

• 人花 1–2 天编写技术设计

• 评审通过后进入开发阶段

• 剩余时间基本全部由人工完成编码与调试

整体交付成本约为 10 PD

2. 常见的 AI Coding 使用方式（≈ 8 PD）

在目前较为主流的 AI Coding 实践中，整体流程并没有发生本质变化：

• 人依旧需要花 1–2 天完成技术设计

• 评审后进入开发阶段

• 在开发过程中，让 Agent 辅助完成若干0.5 PD 级别的子任务

• 最终可以节约约 1–2 PD，总体成本约为 8 PD

在这种模式下，AI 更多扮演的是工具型加速器的角色，对整体任务结构影响有限。

3. 基于“讨论模式”的 Spec 前置范式（≈ 2.5 PD）

而在我们当前采用的范式中，变化发生在更早的阶段。对于同样一个 10 PD 级别的需求，我们会刻意将时间前置：

• 前 2 天不进入编码阶段

人和 AI 进入“讨论模式”，通过持续、深入的对话，不断补齐业务背景、约束条件和边界假设。

• 在讨论中逐步形成一份详细、可执行的 Spec

这份 Spec 往往达到上万字，明确描述目标、约束、取舍、已被否定的方案，以及 Agent 执行时需要遵守的规则。

• Spec 稳定后，再由 Agent 驱动执行

在这种情况下，实际的编码过程反而变得非常快，通常 4-6 小时即可完成主要实现工作。最终，整体交付成本可以被压缩到约 2.5 PD。

举个例子

在实际工程中，我们采用的是 讨论模式（Discuss）+ 计划模式（Plan） 的双模式协作方式，将复杂性前移并冻结在 Spec 阶段，而不是在编码阶段反复消化。

输入

• PRD 需求文档

• Figma 设计稿

步骤一：技术方案生成（先讨论，不写代码）

子步骤 1.1：技术讨论（Discuss 模式）

• 输出：outline.md

• 作用：澄清目标、约束与关键决策，避免方向性错误

outline.md 只包含三类信息：

• 关键决策与取舍

• 明确约束与禁区

• 已被否定的方案及原因

这一阶段的目标不是生成方案，而是把问题想清楚。

子步骤 1.2：方案生成（Plan 模式）

• 输出：tech-design.md（完整技术方案）

• 特点：可多轮迭代

该文档用于对齐共识，不直接用于 Agent 执行。

步骤二：技术方案 → 可执行计划

生成执行计划（Plan 模式）

• 输出：plan.md

• 作用：将技术方案拆解为可验证的 Task

一个技术方案通常会拆分为多个执行计划（按功能点拆分）。

步骤三：按计划执行（不再讨论）

代码生成（Plan 模式）

• 基于执行计划生成代码骨架

• 覆盖率约 70–90%

• 支持边生成边调试

代码审查

• 结合执行计划与代码改动做 Review

• 验证是否偏离计划或触碰禁区

输出

• 可上线代码

• 可追溯的技术方案与执行计划

效率提升的真正来源：复杂性被前移并消化

需要强调的是，这种效率提升并不是因为代码写得更快，而是因为：

任务中的复杂性被系统性地前移，并在 Spec 阶段被充分消化。

在一次性生成 Spec 或边写边改的模式下，复杂性会在执行阶段不断暴露，导致频繁返工、推翻方案，甚至整体方向错误。而在“讨论模式 + Spec 前置”的范式中：

• 复杂性被尽早暴露

• 隐性上下文被迫显性化

• Agent 执行阶段只做一件事：严格按 Spec 推进

从结果来看，这种方式显著降低了：

• 方向性错误

• 中途推翻方案的概率

• 执行阶段的大规模返工成本

在业务约束复杂、需求规模较大的生产项目中，整体交付效率可以稳定提升2 到 4 倍。

结语

Spec 并不能“解决” AI Coding 的问题。

如果上下文是错的，Spec 只会让 Agent 在错误的道路上越走越远。

但一个在讨论中逐步形成、不断修正的 Spec，至少让 AI Coding 实现较复杂的需求具备了进入真实生产环境的可能性。

真正的瓶颈，从来不在代码，而在我们是否愿意正视上下文的复杂性。