Spexcode：完整的Spec驱动开发工具链

背景

2025 年初，Karpathy 提出了“vibe coding”概念——凭感觉写代码。然而，这种开发方式在实践中暴露出诸多问题：技术债不断累积、审查出现瓶颈、原始意图逐渐丧失，导致系统反复被拉回 agent 的“舒适区”。为解决这些问题，Spec-Driven Development（SDD，规格驱动开发）工具应运而生，其核心口号是“把 spec 当作唯一事实”。然而，现有 SDD 方法不仅未能彻底解决原有痛点，反而制造了新问题：过度工程化、仪式感过重导致成本翻倍、spec 极易失去其“唯一事实”地位。作者作为一名 AI 方向的博士生和独立开发者，曾为前沿 AI 实验室开发商业 code agent，平时保持 3–4 个 code agent 24 小时工作。在积累了大量实践经验后，他开发了 Spexcode 工具，旨在对 SDD 做出体系化的改进，这是该项目的首次公开宣传。

核心内容

Spexcode 是一套完整的 Spec-driven 开发工具链，包含四个主要模块：

1. spex cli：核心模块。负责 spec 树的读写、lint、agent session 的编排（dispatch / watch / review / merge）。所有状态从 .spec 文件夹 + git 现场计算得出，无需独立数据库。

2. spex yatsu：全称 “You As The Stupid User”（你作为那个蠢用户），主张走用户路径做端到端测试。测试以 scenario（场景）方式组织，附着于 spec 的存储结构，写在对应的 yatsu.md 中。通过 git 历史实现每个 bug 的 A/B 对照（前一条 eval 记录失败，后一条成功）。

3. spex dashboard：功能丰富的前端，可充当 Agent IDE。可视化 Spexcode 积累的工程资产，设计上保证人类与 agent 对等。dashboard 中的几乎所有操作都可通过 spex cli 完成，初学者可借助 dashboard 快速上手。

4. spex forge：连接 GitHub 和 GitLab，可直接操作 issue，例如将 bug 修复分配给某个 agent。

重点功能详解：

• spex lint：通过 git 计算 spec 新鲜度，解决 spec 过时问题。每个仓库的 spec 以 .spec 文件夹存储，文件数即为 spec 树。每个节点包含 spec.md（以及 yatsu.md 等），子目录对应子节点。节点通过 frontmatter 中的 code: 列表声明其管辖的源码文件。每个 spec 分为原始 spec（人的原始 prompt 或经人同意的设计抉择，只包含“why”）和扩展 spec（agent 思考后给出的具体化版本，可包含部分“how”）。包含 spec 字数与 code 字数比值的启发式检验，若 spec 字数过多则警告 agent。

• git 即 spec 历史：spec 也纳入 git 版本控制，dashboard 可方便查看 spec 的编辑历史。

• Claude Code 与 Codex 的 hook：在 spex init 初始化后自动注入，包括 worktree 资源管理与 agent 动作规范。每个 agent session 创建时绑定一个 worktree，开始前先用 spex search 了解任务对应的现有 spec，细读后才能看代码；结束时在 pre-commit 等步骤设置 git hook，spex lint 和 yatsu scan 的 warning 会提示 agent 更新 spec，防止 spec 过时。

• spex yatsu 系列命令：负责测试。通过场景附着于 spec 存储结构，利用 git 历史做 bug 的 A/B 对照。作者将代码比作神经网络（黑盒），spec 比作 loss 函数或 reward，每次 commit 类似梯度下降 step，每次测试相当于前向计算 loss。

• dashboard 高级操作：支持测试视频直接鼠标标注，在视频时间点勾画区域并评注。通过 hook 让 agent 自报状态，实现 Claude 与 Codex 互相交流，可组织多层级的 agent 结构。统一的 @ 和 [[ 操作符解析，例如在 issue 中插入 @new 可自动分配新 agent。dashboard 已支持全键盘操作（向 Vim 看齐），未来将支持游戏手柄操作。

• 项目现状：开发不到三周，已有 2k+ 个 commit，仍处于早期探索阶段，首次公开宣传。

关键要点

• 现有 SDD 工具的核心问题：忽略了“为什么”（whys），过度关注“怎么做”（hows），导致 spec 漂移无系统性保证，且缺乏对 spec 过时的自动检测机制。
• Spexcode 的核心理念：将 spec 与代码一同纳入 git 版本控制，通过 git 历史计算 spec 新鲜度，强制 agent 在每次 session 中“从 spec 开始，到 spec 结束”，形成闭环。
• 测试策略：采用端到端测试（yatsu），以用户场景（scenario）组织，用文字描述而非固定代码，避免 agent 自我妥协；每个 bug 的修复通过 git 历史做 A/B 对照。
• 分层 agent 编排：通过 hook 和统一操作符（@、[[）实现 agent 间的协作，支持多层级结构，且 dashboard 完全可替代 cli 操作。
• 项目定位：专为 vibe coder 设计，旨在解决“只会写 demo”的困境，让 agent 能够真正从 1 到 100 维护大型项目。

意义与影响

Spexcode 尝试建立一种新的开发范式，将 spec 从“写完了就丢”的文档转变为与代码同步演变的活资产。它通过 git 历史、lint 检查、自动化 hook 和端到端测试，系统性解决了 spec 漂移问题，使 spec 真正成为“唯一事实”。同时，其 yatsu 测试理念强调以用户意图为出发点，而非让 agent 按固定路径自证，有望提升大型项目的可靠性和可维护性。该项目还引入了多 agent 协作与全键盘/手柄操作等创新设计，预示了未来 code agent 工具的发展方向——更加强调人类与 agent 对等协作，而非单纯依赖 LLM 的自动生成。尽管目前仍处于早期阶段，其思路对社区极具启发性，可能推动 SDD 工具从“过度仪式”走向“轻量实用”。