「开源自荐」Spexcode - Spec-driven 的 vibe-coding 真能征服复杂软件开发吗？这是我的尝试

• 请不要在回答技术问题时复制粘贴 AI 生成的内容

项目链接：Spexcode

2025 年初,Karpathy 造了 "vibe coding" 这个词——凭感觉写代码。然而, vibe coding 的方式在现实中挑战重重：技术债累积，审查瓶颈，原始意图丧失导致系统不断被拉回 agent 舒适区等等。

为了解决这些问题，让开发过程更有章法，vibe coding 语境下的 SDD （ Spec-Driven Development ，规格驱动开发）工具不断涌现。"把 spec 当作唯一事实" 是他们的口号，然而现实是，不仅解决原有问题的能力有限,还制造了新问题，比如:

过度工程，营造出一种我写代码很有章法的假象。Agent 仿佛变成一个假装在努力学习，会说花里胡哨一堆名词，但期末依然不及格的学生。可见摘自 spec-kit 的 issue 区链接，有比较有趣的讨论。
仪式过重,成本翻倍，不如直接写。
最致命的，spec 总是会以各种方式失去其唯一事实的地位。

核心矛盾在于,"spec 是唯一事实"作为 SDD 最大的卖点,但是这一卖点并不能得到保证。要知道,代码有编译器、有单元测试、集成测试等各种"环境"的压力,但 spec 都没有。因此 spec 一旦过时,agent 就会选择去看更加"自洽"的代码,这反过来导致 spec 更加过时, agent 更不愿意看，如此形成恶性循环。

我尝试去寻找问题的根源。

看到这篇博客后，我很同意其中的一个看法:大家选错了抽象层级。

现在的大多数 SDD 方法关注的都是实现细节,也就是"怎么做"(hows):字段定义、枚举、请求/响应 schema 、函数签名。但更重要的其实是背后的"为什么"(whys):意图、约束、上下文。

此外，还有两点：

spec 漂移没有系统性保证。当你和 LLM 因为一个 bug battle 了大半天,终于得到了满意的解法并写入代码后,没有一个硬的系统机制来保证 spec 也得到相应修改。甚至 agent 还有可能忽略现有的 spec 而再增加一项,从而导致 spec 自身的重复。"唯一事实"就这样碎掉了。
spec 的存在是一个很好的"端到端测试资产",但现存的框架都没有很好地利用到这一点。相信平时经常 vibe coding 的朋友们也有体会,就是目前单元测试的价值越来越低,甚至固定脚本的集成测试也没那么奏效了。因为都是 agent 自己根据当时需求写的,他总有各种方式去妥协、去 hack,去顺着他自己的脑回路自我成全。所以从"意图"出发构建的端到端测试变得更加重要。测试可以不落成具体代码,而是用文字的方式来表述,这样 agent 每次重测都不会被固定路径所限制,反而能真正发现问题。（当然，实际开发中可能还是会遇到一些复现条件及其刁钻，但又不得不修的 bug ，那种还是需要落成代码形式的定义。）

种种原因,spec 反而让开发流程更加地不那么 agentic,对人的要求也更高,不是谁都能驾驭 spec 的,搞得像是逆着时代潮流去了。

讲完了问题,接下来就向大家介绍下我自己的解法是如何的。简而言之，我做了一个 SDD 的工具链，叫做 Spexcode ，可以视为一个比较大型的 agent 插件，但是不以 plugin 的形式分发，而是需要单独安装和初始化。它分为以下几个模块：

spex cli 项目的核心，一个命令行工具。spec 树的读写、lint 、agent session 的编排（ dispatch / watch / review / merge ）全在这一层；没有独立数据库，所有状态都从 .spec 文件夹 + git 现场算出来。

spex yatsu 我们死抓软件工程的“头”与“尾”，头是 spec ，那么尾就是测试了。yatsu 是我提出的概念，全称为 You As The Stupid User （你作为那个蠢用户），主张走用户路径做测试，测试手段越端到端越好。

spex dashboard 功能极其丰富的前端，本身完全可以作为一个 Agent IDE 来使用。可视化 spexcode 所积累下来的工程资产，设计上保证人类与 agent 对等，dashboard 里的几乎所有操作都可以通过 spex cli 完成。初学者可通过 dashboard 快速上手，建立起 spexcode 的整套心智模型。

spex forge 连接 github 和 gitlab 。可以直接操作 github 上的 issue ，例如把 bug 修复分配给你的某个 agent 。

好，那么这些模块该如何组合起来，解决 SDD 的种种问题呢？

Spex lint

通过 spex lint 验证来保证 spec 和 code 永远对应不过时。我们将所有的 spec 都存储于项目中的 .spec 文件夹，并受 git 管理。每个 spec 节点都是一个子文件夹，呈树状结构。每个子文件夹都包含一个 spec.md 文件，并在 frontmatter 中链接到代码文件，分为 govern 和 relate 两种强弱链接。spex lint 命令通过 git 来计算代码文件领先于链接到它的 spec 的提交数，然后给出错误或警告。spex lint 会在 spex init 初始化的时候自动注入 git 的 pre-commmit 钩子，也会在项目的 CLAUDE.md 或 AGENTS.md 维护相应指令。

此外，每个 spec 分为原始 spec 和扩展 spec 两部分，原始 spec 是人的原始 prompt 或者明确经过人同意的设计抉择，扩展 spec 则是 agent 自己思考给出的较为忠实的具体化版本。原始 spec 基本只包括“why”的部分，扩展 spec 可以包括一部分“how ”。包含 spec 字数与 code 字数比值计算等启发式检验，如果 spec 字数过多，说明写 spec 的方式有误，会警告 agent 。

Spex Yatsu

spex yatsu 系列命令，则负责测试这一块。以 scenario （场景）的方式来组织，附着于 spec 的存储结构，写在对应的 yatsu.md 里面。对于 scenario 的每次测试被称之为一个 “eval”。可通过 git 历史实现每个 bug 的 A/B 对照（先复现再修复）- 前一条 eval 记录失败，后一条记录成功。spexcode 会要求每次 eval 链接到相应的 evidence 。当然，evidence 本身不被 git ，只有哈希值被 git ，可以是本地图片、视频或日志，并包含实验步骤的元数据。

这里可以提一下我现在比较认同的一个类比，就是如果把代码当作复杂的神经网络（一个黑盒），那么 spec 就是 loss 函数或者 reward ，每个 commit 就像是一次梯度下降的 step （ code agent 是优化器），每次测试则是一个前向计算 loss 的过程。

测试越是端到端，loss 函数的估计也就越精准。但是很多时候 Agent 对需求的理解并不会那么对齐人，这时候人就要对 Agent 的 loss 计算进行干预，也就是 review 。按照现在的开发速度，让人进行 code review 是比较困难了，效率很低（你甚至找不到很好的 review 数据来做一个 benchmark ），但是让人来 review agent 的测试过程是很有希望的。于是我们在 spexcode 上设计了一套 review 的链路。比如说，对于 agent 制作的视频，我们在 dashboard 上面设计了一个很方便的标注工具，哪里不对劲点哪里：