Spec-Driven Development 应该是什么样的？

缘起

前几天同事在群里分享了一个开源的支持多数据库的客户端 DBX，功能非常全面。我打开页面看了一眼界面，发现完全不符合我的审美。

我之前在用的是 TablePlus，使用 Setapp 订阅的。但由于我现在实际工作中做具体开发任务的机会越来越少了，可能两个月才会打开一次，所以我就把订阅取消了。又舍不得买断价格，所以一直凑合使用免费试用版（限制很多）。所以我就想，既然 AI Coding 已经这么强了，我为什么不自己写一个呢？

之前已经陆陆续续利用 AI Coding 做了不少小工具，也有了不少思考。最近正好对 Spec-Driven Development 有了一些新的想法，也可以利用这个新项目来验证一下。

失败的 Spec-Driven Development

在去年 SDD（Spec-Driven Development）刚火起来的时候，我就非常相信这个思路 —— 既然 LLM 有很大的随机性，不可控，那么我们就应该先定义出完善的需求、边界、验收标准，形成 Spec 文档，然后再让 LLM 去实现。

想象是美好的，直到我真的开始用 Spec Kit 去做了项目，一周之后，我就彻底放弃了。

回头想想，我认为不好用的原因主要是以下两点：

冗长的流程，没人看的文档

冗长的流程（当时的 Specify → Plan → Tasks → Implement，现在官方还多了 Converge）会产出大量文档，但这些文档我觉得并不产生价值，只带来了成本。

先说 Plan 文档和 Task 文档，其来源是 Spec 文档，由 Agent 生成。但既然 Agent 可以推理出来，也就代表这两类文档不提供额外有效信息。它们唯一的价值是让我来仔细 Review，对实现细节达成一致。但现实是这些文档我完全不想看。我只会关注我的需求有没有表达清楚，Agent 有没有真的理解，实现细节就应该 Agent 自己搞定。

再说 Spec 文档，也是从我的简单几句话描述需求后，Agent 生成的长篇大论。依然是我上面的观点，这代表 Spec 文档的有效信息量很低。这些长篇大论的废话，我依然是完全不想看。

Agent 读代码很快，理解项目没有什么难度。这些低信息密度的文档也并不能对 Agent 理解项目有什么帮助。

这个流程最终只是沦为形式，我只是在枯燥的执行一个命令，下一个命令，哪怕只是一个很小的任务，也要走完整个流程。

Agent 缺少全局视野

我一直觉得 Agent 需要理解项目的全貌（最终目标、完整的形态、关键决策），才能在实现时做出最合理的判断。但 SDD 流程要求我把项目拆分成一个个 Spec 能够描述的小任务，就会导致无论何时 Agent 都不知道项目的全貌，我也就无法期待它能够做出面向未来的合理的决策。

回归简单

最终，我放弃了 SDD，改为在 pi agent 上写了一个极其简单的 plan mode skill：

---
name: plan
description: 当用户需要进行需求分析和方案设计时（或者用户消息以 plan 开始），使用本 Skill。
---

# 计划（需求分析与方案设计）

进入计划模式。**禁止使用 write/edit 工具**，只做需求分析和方案设计。

## 目标

1) 分析需求中需要被澄清的问题点，沿决策树逐分支深入，直到所有细节被澄清。
2) 分析现有代码实现，结合一些必要的技术调研，提出可行方案，并继续讨论需求中的不确定点。
3) 最后输出完整实现方案，在用户确认达成共识之前**不执行**。

## 交互要求

（交互细节略）

## 退出计划模式

当完成最终方案输出后，向用户确认是否退出计划模式，若用户确认，则退出计划模式；否则继续进行需求分析和方案设计。

这个 Skill 只是帮助我澄清需求和方案（不落盘），完成后立刻动手开始干，效果又快又好。

Spec 应该是什么样的

前段时间我开始在日常工作中尝试要求 Agent 输出一些 HTML 文件来替代 Markdown 文档，然后惊奇地发现 Agent 居然可以手写 SVG 来表达各种复杂的图形，用来表达架构，流程，关系等。不仅非常直观，而且还很美观（比 Mermaid 要好很多）。比如这样的：

我会很「惊奇」是因为这个能力并不像「人」，我觉得没有人可以不借助工具，纯手写 SVG 来表达各种复杂的图形。贴一个 SVG 片段大家感受一下：

<g clip-path="url(#win)">
    <rect class="s-chrome" x="8" y="8" width="984" height="28"></rect>
    <circle class="s-red" cx="26" cy="22" r="5.5"></circle>
    <circle class="s-yellow" cx="44" cy="22" r="5.5"></circle>
    <circle class="s-green" cx="62" cy="22" r="5.5"></circle>
    <text class="c b" x="500" y="23">本地开发 — app_dev</text>

    <rect class="s-chrome" x="8" y="36" width="984" height="44"></rect>
    <line class="ln" x1="8" y1="80" x2="992" y2="80"></line>
    ...

不过想一想也可以理解，「人」并不会去读大量的 SVG 代码，但 LLM 是读过大量的 SVG 代码训练出来的。

我们的 Coding Agent 背后的 LLM 通常都是纯文本的，即使是多模态通常也只是能够读图片，而不能够生成图片。但 LLM 能手写 SVG，恰好就补上了这块缺失的拼图。

我突然意识到，有了这个能力的加持，我可能可以让 SDD 回归到它理想的样子了 —— 我只关注表达清楚需求，Agent 关注实现细节。

就以这个 DB 客户端项目为例，我的思路是：

1. 我先让 Agent 根据我的描述和几轮讨论，起草一份能够表达项目完整能力的 Spec 文档，要求以用户视角描述；
2. 然后让 Agent 根据这个文档，生成一份「使用说明书」，以 HTML 来呈现，要求它将所有界面、交互，都用 SVG 画出来（没有代码，纯靠 LLM 根据 Spec 文档和常识来脑补）。
3. 理想情况下，LLM 能够非常详尽地画出所有的界面、交互细节，我就可以直接 Review 这份说明书而不是 Spec 文档了。所有很难用文字表达清楚的细节，在有了真实的图片之后，Review 的效率直接高出一个数量级，心智负担直接降低一个数量级。
4. 我可以 Review 并要求 Agent 修改说明书和 Spec，应该很容易地将这个软件的设计细节完全确定下来，落地成最终的 Spec 文档和说明书 HTML 文档。
5. 最后，启动一个 pi agent，告诉他根据 Spec 文档和说明书 HTML 文档，充分利用 subagent（避免上下文爆炸）完整地实现这个软件。由于所有的细节我已经确定了，实现过程应该不需要我的任何参与。

当然，除了完整的需求描述，讨论过程中还需要确定少量关键方案决策，比如要求做成 macOS 原生应用、使用 libmysqlclient 而不是自己实现 MySQL 协议等。

想象挺美好，但是 LLM 真的能够只根据 Spec 文档和常识来脑补出所有的界面、交互细节吗？Review 说明书真的会容易轻松很多吗？

我试了，真的可以。

我昨晚刚刚按这个思路开始，花了大概两三个小时让 Agent 生成了 Spec 和这个说明书，正在 Review。这里是项目 https://github.com/graycarl/TableLite，这里是说明书 （直接让 Agent 帮我把 HTML 用 GitHub Pages 托管出来了）。

再贴一个说明书界面截图，大家感受一下。

虽然说明书这个阶段效果很好，后续 Agent 真的能够独立完成所有的实现吗？虽然还没验证，但我有很大的信心。

我接下来会继续 Review 这份说明书，然后尝试让 Agent 在没有我的参与下完成这个项目。

由于比较兴奋，就写到这里提前跟大家分享一下，后续的结果我会再更新。

对了，如果你想知道到底是哪个 LLM 这么牛？我想告诉你，我认为现在绝大多数主流 Coding Agent 都可以做到，而我一直在用的，就是 pi agent 加那个「多快好省」的 deepseek-flash。