用规格约束智能体编码全流程

有效的 Agentic Coding，关键不在于写出更好的 prompt，而在于控制。

你希望同时做到三件事：

• 让 AI 生成几乎所有代码

• 将质量、安全性和生产环境判断牢牢掌握在人类手中

Spec-Driven Development 正是维持这种张力的方法。更强大的 Agent 降低了代码生成的成本，但它们无法替你决定：你想要什么、你拒绝什么，以及如何判断结果是否足够好。Spec 就是整个过程的控制回路。

为什么 Vibe Coding 会失败

当模型在缺乏足够结构的情况下编写代码时：

• 需求始终模糊不清

• 权衡取舍始终没有说透

• 约束条件在生成过程中被遗忘

• 团队交付的是第一个看起来可行的答案，而不是正确答案

更好的自动补全和更强大的 Agent 可以提升速度，却无法建立团队共享的意图。如果在生成开始前，团队无法明确指出什么才算“完成”，那么模型只是在以你的名义进行猜测。

让代码生成成为最后一步

一套实用的流水线如下：

1. 倾倒想法。 记录原始想法、约束条件、边界情况，以及尚未成形的观点。此时不要强行赋予它们结构。

2. 通过多轮澄清形成 PRD。 让 LLM 用几轮对话提出澄清问题，然后将这些零散想法整理成产品需求文档。

3. 结合代码仓库上下文形成 TRD。 将 PRD 与代码和架构上下文结合起来，再次澄清，最终产出技术需求文档。

4. 必要时进行实验。 如果某项设计选择仍存在不确定性，就进行基准测试、技术预研或方案对比。

5. 制定分阶段实施计划。 将 TRD 拆分为可以逐步叠加的小阶段。每个阶段都应该能够独立审查和测试。最好每个阶段对应一个 commit，每项功能对应一个 PR。

6. 生成代码。 只有完成以上步骤后，才开始生成实现代码，并将计划和上下文作为唯一可信依据。

每一步都会产出一份可供下一步信赖的成果。模型负责持续生成，人类则始终对意图负责。

尽早迫使团队回答那些棘手问题

多轮澄清不仅是为了让文档更清晰，还会迫使团队回答一些问题——一旦有人已经开始写代码，这些问题就很容易被跳过：

• 我们究竟要构建什么

• 哪些内容不在构建范围内

• 系统规模扩大后会发生什么

• 数据迁移如何进行

• 部署后如何验证

• 安全问题如何处理

把这些问题内置到流程中。一份根据过去的事故和评审经验整理出来的简短安全检查清单，在流水线强制要求执行时，效果会好得多。那些令人不太自在的检查由此成为常规步骤，而不是可选项。

这套流程还有第二重收益：团队成员会在流水线推进过程中不断学习。等到真正开始编码时，团队对问题的理解通常已经比刚开始时深入得多。

如果模型没有一个稳定的信息来源可供查阅，流水线就会失败。维护一套团队可以明确引用的 Markdown 文档，其中包括：

• 产品和功能领域

• 服务及其职责边界

• 约定：你倾向采用什么、避免什么，以及在这里什么才算“好”

代码的组织形态同样重要。大文件会与上下文窗口相互对抗，让生成效果变差。更小、更聚焦的模块，可以让 Agentic Coding 对人类和模型都更加好用。

要求模型实现功能时，要明确说明：

• 包含依赖项变更

• 包含类和数据库 schema 变更

• 明确指出新增或更新的库

• 确保设计符合 SOLID 原则且可测试

• 将测试视为交付的一部分，而不是事后补充

大部分真正困难的工作并不是打磨 prompt，而是编写上下文、观察生成结果在哪里发生偏离、重写上下文，然后不断重复，直到模型能够始终遵守你的标准。

在作出承诺前解决未知问题

并非每个项目都需要进行技术预研，但有些项目确实需要。

在确定采用某个库、插件或实现方案之前，先要求进行对比。有时这意味着阅读文档，有时则意味着编写一个小型基准测试或原型。

如果设计依赖某个未知条件，就把这个未知条件写下来，并在花费一整个实施周期走上错误路线之前解决它。如果 TRD 本质上仍然只是猜测，那么写得再自信也毫无意义。

工具变化时，保留流程主干

内部代码生成器、Tab 补全、Agent：表层工具一直在变化，但底层应该始终保留同一条主干：

• 必要时进行实验

更强大的 Agent 让规模更大的改动变得切实可行，但它们仍然无法替代清晰的计划。

有效的 Agentic Coding 是什么样的

先写 Spec，再写代码。 先倾倒所有想法，再通过 PRD 和 TRD 迫使这些想法变得清晰。

先划分阶段，再创建 Pull Request。 让每一步都足够小，以便审查、测试和回退。

上下文优先于巧妙的 prompt。 Schema、服务、API 和约定都应该被明确记录下来。

模块化代码优先于魔法。 聚焦的文件可以让人类和模型都发挥得更好。

先比较，再承诺。 不要假装不确定性已经成为设计决策。

先完成检查清单，再说“看起来不错”。 规模、迁移、部署、回滚和安全性都不是可有可无的附加项。

判断权属于人类。 模型负责生成，人类负责决策。

当人们把模型视为事实来源时，Agentic Coding 就会失败。只有当人们把模型视为一名速度极快、在清晰且可测试的计划内工作的实现者时，它才能真正发挥作用。Spec 正是维持这条边界的方式。

大约在 2023 年至 2025 年期间，我在 BlogVault 使用 AI Coding Agent 交付产品，并通过不少艰难的教训总结出了这套方法。我现在已经不在那里工作了，本文也不代表该公司的官方观点。我依然在自己的工作中沿用同样的模式，包括开发 dharmiq：先澄清产品意图，再编写技术需求，最后依据书面原则和计划分阶段实现。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。