Speck 完全指南：用规格驱动 AI 编码 Agent，让代码生成可复现、可验证

AI 编码 Agent 正在改变我们写代码的方式，但一个问题始终存在：如何让 Agent 的代码生成从「碰运气」变成「可预期」？ 传统的对话式交互——你说一句、Agent 写一段——在简单任务上够用，但面对复杂项目时经常出现「同一个需求每次生成不同代码」「前一次改好的逻辑被后一次覆盖」「没有清晰的架构痕迹可以追溯」等痛点。

Speck 提供了一种不同的思路：规格驱动（Spec-Driven）的 Agentic 编译器。它把需求拆解为三层规格（Features → Technical → Source），让 AI 编码 Agent 像传统编译器一样按规格生成代码，且任意一层被修改时都能双向同步。本文带你从安装到实战，完整了解 Speck 的工作方式。

Speck 是什么

Speck 是一个基于 Zerostack（1404⭐ 轻量编码 Agent）的规格驱动编译器。它不直接面向对话式编码场景，而是定义了一套工作流：你先写规格（specs），Agent 按规格生成代码；如果你改了代码，反向同步回规格；如果改了规格，正向同步到代码。

核心目标：让 AI 编码 Agent 的每次生成都有规格可依、有历史可查、有冲突可解。

项目采用 GPL-3.0 许可证，用 Rust 编写，通过 cargo install speck-dev 安装，当前稳定版为 v1.0.0（2026-07-04 发布）。

架构：三层规格模型

Speck 维护一个三层架构，每层是同一个产品的不同抽象层次：

三层之间通过 BLAKE3 哈希值追踪变更。.speck_hash.toml 文件记录所有文件的当前哈希，speck apply 时对比哈希找出变更层，然后按方向传播。

Apply 管道（四步流程）

Speck apply 检测变更 → feat2tech → tech2code → code2tech

1. 检测变更：对比当前文件的 BLAKE3 哈希与 .speck_hash.toml 中记录的哈希
2. feat2tech：Feature 规格变更 → 向下传播到 Technical 规格
3. tech2code：Technical 规格变更 → 向下传播到 Source 代码
4. code2tech：Source 代码变更 → 向上回流到 Technical 规格

每一步使用一个专门的 Zerostack 提示（prompt），温度设置不同——确定性更新用 0 温度，创意性规格扩展用更高温度。

冲突处理

当同一文件的 Source 代码和 Technical 规格同时被修改，Speck 无法决定谁是权威版本，会交互式地让你选择：

Both spec and code changed for src/auth.rs — which takes priority?
[1] Code (update specs to match)
[2] Specs (update code to match)

也可以用 --prefer-code 或 --prefer-specs 批量非交互式解决所有冲突。

安装

方式一：Cargo

cargo install speck-dev

方式二：GitHub Releases

从 GitHub Releases 页面 下载预编译二进制。

方式三：源码编译

git clone https://github.com/gi-dellav/speck.git
cd speck
cargo install --path .

安装前需确保已安装并配置 Zerostack：

zerostack --version

功能详解

Speck 提供 13 个核心子命令，覆盖从项目初始化到代码审查的完整规格驱动开发流程。

1. 项目初始化：speck init

在新目录中脚手架一个新项目，自动生成目录结构和模板文件：

mkdir my-speck-project && cd my-speck-project
speck init

生成的文件包括：

• specs/features/ 目录（空的 Feature 规格）
• specs/technical/ 目录（空的 Technical 规格）
• src/ 目录（空的代码目录）
• AGENTS.md 和 ARCHITECTURE.md 模板——为所有 Agent（包括 Zerostack）提供共享的核心知识
• .speck_hash.toml（空的哈希数据库）
• Speck.toml（配置文件）

2. 迁移现有项目：speck migrate

如果你已有代码库，不需要从头开始。speck migrate 从现有代码反向工程出 Technical 规格，再推导出 Feature 规格：

cd existing-project
speck migrate

这会在项目根目录创建 specs/ 目录，并用 AI Agent 分析源代码自动生成对应的技术规格文档。

3. 双向同步：speck apply

这是最核心的命令——检测所有变更并双向传播：

speck apply

当你修改了 Feature 规格后执行 apply，它会一路传播到代码；修改了代码后执行 apply，它会反向更新 Technical 规格。

4. 状态查看：speck status

列出已编辑和未注册的文件，按层级分组：

speck status

输出格式类似：

Changed files (by layer):
  specs/features/user-auth.md (modified)
  src/auth.rs (modified)
  specs/technical/auth-tech.md (unregistered)

5. 格式化和重置：speck fmt / speck force-update

speck fmt          # 运行配置的格式化工具并刷新哈希
speck force-update # 重置所有哈希为当前文件内容

force-update 在你信任当前文件状态、希望刷新哈希数据库时特别有用。

6. 代码审查：speck review

通过专门的 Zerostack 提示运行结构化代码审查，输出 Markdown 报告：

speck review --output report.md

生成的报告包含代码质量、安全、一致性等多维度评估。

7. Git 钩子集成：speck git-hooks

自动在项目安装 Git 钩子，让规格同步成为代码工作流的一部分：

speck git-hooks

安装的钩子：

• pre-commit：运行 speck apply，确保提交前规格与代码一致
• pre-push：运行 speck status，检查是否有未同步的变更
• post-merge：合并后自动刷新哈希数据库
• post-checkout：切换分支后检测文件状态变化

8. 技术栈切换：speck switch-lang

这是一个看似激进但思路清晰的功能——从 Feature 规格重新生成整套代码，切换语言或框架：

speck switch-lang --lang rust  # 将项目从现有技术栈切换为 Rust
speck switch-lang --lang typescript  # 切换到 TypeScript

它本质上是「保留 Feature 规格 → 清空 Technical 规格和代码 → 从零用新模式生成」，适合原型快速迭代或技术栈迁移场景。

9. 文件管理：speck mv / speck rm

移动或删除文件时自动更新哈希数据库：

speck mv src/old.rs src/new.rs
speck rm src/obsolete.rs

10. 交互式会话：speck chat

打开 Zerostack TUI 会话，操作完成后自动应用变更：

speck chat

推出 TUI 后自动执行 speck apply，确保对话中的修改被正确同步。

配置：Speck.toml

项目根目录的 Speck.toml 控制所有行为：

name = "my-app"
source_dir = "src"
model = "claude-3-7-sonnet-latest"
features_dir = "specs/features"
fmt_cmd = "cargo fmt"
test_cmd = "cargo test"

实战：在现有项目中使用 Speck

假设你有一个用 TypeScript 写的 REST API 项目，想引入 Speck 来管理后续开发。

第一步：迁移

cd my-api
speck migrate

Speck 分析现有代码后生成 specs/technical/，其中 api-routes-tech.md 记录了每个端点的技术规格，database-tech.md 记录了数据库交互逻辑。

第二步：检查状态

speck status

所有现有文件被正常识别和注册。

第三步：修改规格，让 Agent 同步代码

编辑 specs/features/ 中的需求文档，新增一个搜索端点，然后：

speck apply

Speck 会检测到 Feature 规格变更，向下传播到 Technical 规格，再传播到代码——自动生成搜索端点的实现。

第四步：修改代码，让规格保持更新

如果你手动改了一个路由的处理逻辑，执行一次 apply 就能让 Technical 规格自动更新，保证文档与代码始终保持一致。

注意事项

• 依赖 Zerostack：Speck 本身是一个编排工具，核心的 AI 编码能力由 Zerostack 提供。安装 Speck 前需要先安装 Zerostack 并配置好 API 密钥。
• GPL-3.0 许可证：如果你是商业项目引入 Speck，注意其许可证条款可能影响分发方式。
• 项目尚在早期：Speck v1.0.0 刚刚发布，GitHub 仅 4⭐，Cargo 下载量 34 次——功能稳定但社区生态尚未形成，遇到问题可能需要向作者提 Issue。
• 哈希冲突提示：.speck_hash.toml 是追踪变更的核心文件，应纳入版本控制但不建议手动编辑。

总结

Speck 代表了一种不同于传统 AI 编码方式的思路——规格驱动。它不追求「一句话生成整个应用」，而是通过三层规格模型让 AI 编码 Agent 的行为变得可预期、可追溯、可复现。如果你厌倦了「反复修改同一个文件、Agent 每次写出不同代码」的体验，Speck 的三层同步机制值得一试。

相关链接：

• Speck GitHub 仓库
• Zerostack – 底层编码 Agent
• Speck 发布页面