「开源自荐」Spexcode - 完整的 Spec driven 开发工具链。Vibe Coder 们站起来吧，你们不只会写 demo！

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

• 我的帖子已经打上 开源推广 标签： 是


• 我的开源项目完整开源，无未开源部分： 是


• 我的开源项目已链接认可 LINUX DO 社区： 是


• 我帖子内的项目介绍，AI 生成、润色内容部分已截图发出： 是


• 以上选择我承诺永久有效，并接受社区和佬友监督： 是

以下为项目介绍正文，AI 生成、润色内容已使用截图方式发出。

从头说起

这一话题,值得我们从历史背景讲起:

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

为了解决这些问题,SDD（Spec-Driven Development，规格驱动开发） 工具出现了。“把 spec 当作唯一事实” 是他们的口号，然而现实是，不仅解决原有问题的能力有限,还制造了新问题:

1. 过度工程，营造出一种我很有章法的假象。仿佛一个假装在努力学习，会说花里胡哨一堆名词，却期末依然不及格的学生。可见摘自 spec-kit 的 issue 区 链接，有比较有趣的讨论。


2. 仪式过重,成本翻倍，不如直接写。典型社区反馈：“还没写出一个文件,token 就已经飙到 20k 以上……但我直接对 Claude 发一条命令,2k token 就完成了第一个任务。”


3. 最致命的，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，那种还是需要落成代码形式的定义，理想情况是通过一个优雅的架构来让这种难缠的 bug 本身不太常见，而非事后补救）

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

讲完了问题,接下来就向大家介绍下我自己的解法是如何的。作为一个 AI 领域的 phd 学生和独立开发者,我做过挺多 agent 项目,包括为前沿 AI lab 开发有大量用户的商业 code agent,平时最低限保持 3-4 个 code agent (cc 和 codex 混合) 24 小时工作。下面介绍的 spexcode 工具是我在该领域做出的一个较为体系化的尝试吧。这是该项目的第一次公开宣传,希望大家多来探讨!

项目架构

spexcode 主要分为以下几个模块

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。

重点功能

1. spex lint，通过 git 计算出 spec 新鲜度，解决 spec 过时的问题。一切皆 git。
   
   每个仓库 spec 以 .spec 文件夹的方式存储，文件数即是 spec 树，每个节点带有一个 spec.md（还有 yatsu.md 等，后面会讲），子目录就是子节点。节点通过 frontmatter 里的 code: 列表声明它管辖哪些源码文件。

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

一切皆 git，spec 也如是，你能在 dashboard 上很方便地看到 spec 的编辑历史：

2. 
   

   针对 claude code 和 codex 的各类 hook，在 spex init 初始化后自动注入，包括 worktree 资源管理与 agent 动作规范等部分。其中 agent 这一方面可以概括为“从 spec 开始，到 spec 结束”。每个 agent session 创建之时都绑定一个 worktree，开始工作时先用 spex search 了解任务对应的现有 spec，细读之后才能看代码。结束的时候则在 pre-commit 等步骤设置了 git hook，spex lint 和 yatsu scan 的 warning 会给到 agent，让其对应地去更新 spec。这样就防止了 spec 过时的问题。

   
   


3. 
   

   spex yatsu 系列命令，则负责测试这一块。以 scenario（场景） 的方式来组织，附着于 spec 的存储结构，写在对应的 yatsu.md 里面。通过 git 历史实现每个 bug 的 A/B 对照，即前一条 eval 记录失败，后一条记录成功。

   
   

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

在 dashboard 上支持测试得到的视频直接上鼠标进行标注，即在视频某个时间点勾画一块区域并评注，哪里不对劲点哪里，是一种非常舒服的 prompt 方式。

4. dashboard 骚操作，通过 hook 让 agent 自报状态，claude 与 codex 互相交流，几句话就能组织起一个层级式 agent 结构（不止一层！），让你根本刹不住车。统一的 @ 和 [[ 操作符解析，富有灵性，在哪都能用，例如开启一个 issue 的时候插入 @new，就会自动分配一个新的 agent 去做。

5. 目前 dashboard 上大部分页面已支持全键盘操作，按键设计向 Vim 看齐。来体验风驰电掣般统领 agent 大军的感觉吧！（如果你发现开发过程中你的 agent 开始使用“兵力”，“起兵”这些词，不要像我第一次那样感到惊讶，这是因为他用 spexcode 也用爽了…）后续会支持游戏手柄操作 - 是的，程序员们迟早要意识到，他们即将离开鼠标和键盘 ^-^

截图：

全局搜索跳转功能。你甚至可以把它当笔记软件用。

11 个 worktree，一个主管 agent，token 在燃烧。

还有更多特性等你来玩！

这个项目做了三周不到，2k+ 个 commit，目前只能算本人对新形态的 code agent 工具的一次粗浅的探索，SDD 的赌注是否能赢，是否能让一个大型项目真正从 1 到 100，还需要无数现实的捶打。这是第一次公开宣传（之前都是内部团队在用），欢迎大家多多批评指正。