SpecForge

5 分钟内试用 · 工作原理 · 看看它如何发现问题 · 文档

60 秒内见分晓，无需 Agent。安装、创建项目、删掉一个字母，然后检查：

curl -fsSL https://raw.githubusercontent.com/leaderiop/SpecForge/main/install.sh | sh
mkdir sf-demo && cd sf-demo
specforge init --extensions @specforge/software          # spec/hello.spec, which checks clean
sed -i.bak 's/\[user_logged_in\]/[user_loged_in]/' spec/hello.spec   # drop one letter
specforge check

[E003] Error: unresolved reference 'user_loged_in' in entity 'authenticate_user'
 20 │   produces [user_loged_in]
    │ Help: did you mean 'user_logged_in'?

[W007] Warning: event 'user_logged_in' is not produced by any behavior

1 error, 1 warning, 0 infos

审核者阅读，检查给出结论。

问题所在

你让 AI Agent 为支付服务添加退款功能。它写出的代码整洁，测试通过，拉取请求看起来也没问题。两周后，财务部门发现一笔退款金额超过了被退款的支付金额。

这条规则明明写在规范里：一个位于 docs/、与 PRD 放在一起的 Markdown 文件。Agent 可能三次会话前读过它，也可能根本没找到。因为一切看起来都正常，所以没人发现问题。

这不是模型的问题，而是规则存放位置的问题。如今，重要的知识都放在没有任何机制强制执行的地方：

• Markdown 中的规范（PRD、docs/*.md、spec-kit 文件）都是散文。Agent 可能误读或悄悄跳过某条规则，也没有任何机制检查规范是否完整或各部分是否一致。
• 文档和 Wiki会与代码脱节，即使发生这种情况，也不会触发任何故障。
• 可追溯性（哪个需求有测试、哪条规则在哪里强制执行）依赖某人手动更新的电子表格，直到他们不再更新。
• **每次会话都从零开始。**Agent 会重新阅读几十个文件，试图弄清你的意思，却还是会猜错。

你交给 AI 的工作越多，情况就越糟。它写代码的速度超过任何人的审核速度。

理念：硬技能，而非软技能

教 AI 如何按照团队的方式工作，有两种方法。

软技能是放在 AI 上下文中的建议：Markdown 规范、PRD、技能文件。它有帮助，但本质上是散文。AI 可能遵循，也可能不遵循。

硬技能是由程序强制执行的规则。AI 无法跳过它，因为检查会失败。

**SpecForge 是用于硬技能的工具。**你（或者更常见的是，你的 Agent）将必须满足的条件写入小型结构化 .spec 文件。SpecForge 会像编译器检查代码一样检查这些文件：每个引用都必须指向真实内容，每条规则都必须由某种机制强制执行，每个承诺都必须由测试证明。然后，它会将检查结果作为上下文提供给你的 Agent。

可以把它看作用于检查你意图的类型检查器。

工作原理

1. 你描述想要什么，就像现在一样，通过对话进行。
2. 你的 Agent 起草规范：操作、必须始终成立的规则、事件，以及每一项的证明方式。
3. SpecForge 检查草稿。 错别字、无人执行的规则、缺失的内容：检查会失败，并指出确切行号和修正提示，随后由 Agent 修正。这一步不涉及 AI。相同的输入，每次都会得到相同的判定。
4. 你的 Agent 根据已检查的规范进行构建。 它向 SpecForge 请求所需的确切部分，而不是重新读取你的代码库。
5. 你的测试证明规范。 每项测试都会注明它证明了什么。specforge collect 会运行测试，并记录哪些内容已得到证明，哪些还没有。
6. 你进行审查。 你不必阅读 Agent 写下的每一行，而是查看做出了哪些承诺、哪些已得到证明，以及还有哪些尚未解决。

看看它如何发现问题

你的 Agent 为退款功能起草了以下内容：

invariant refund_within_capture "Refunds never exceed the captured amount" {
  risk high
  verify unit "rejects a refund larger than the captured amount"
}

invariant refund_needs_reason "Every refund records a reason" {
  guarantee "A refund without a reason is rejected"
  risk      medium
  verify unit "rejects a refund with no reason"
}

behavior issue_refund "Refund a captured payment" {
  category   command
  invariants [refund_within_capture]
  produces   [refund_isued]
  contract   "Given a captured payment, refunds up to the captured amount"
  verify unit "refunds the requested amount"
}

event refund_issued "A refund was issued" {
  verify unit "is emitted once per refund"
}

读起来没问题。以下是 specforge check 的检查结果：

[E003] Error: unresolved reference 'refund_isued' in entity 'issue_refund'
    ╭─[ refunds.spec:15:15 ]
 15 │   produces   [refund_isued]
    │ Help: did you mean 'refund_issued'?

[W003] Warning: invariant 'refund_needs_reason' is not enforced by any behavior
[W007] Warning: event 'refund_issued' is not produced by any behavior
[E006] Error: invariant 'refund_within_capture' is missing required field 'guarantee'

2 errors, 2 warnings, 0 infos

人类审查者可能会漏掉的四个问题：

错误总会导致检查失败。使用 specforge check --strict 时，警告也会导致检查失败；这正是你在 CI 中运行的命令。

Agent 修正全部四个问题后再次运行检查：0 errors, 0 warnings, 0 infos。此时规范内部一致，但还没有任何内容得到证明。这正是测试要做的事：每项测试都会注明它证明了哪项承诺，specforge collect 会运行测试，而 specforge review 会显示哪些内容已覆盖、哪些仍未解决。

你刚刚看到的每条规则都来自扩展，而非 SpecForge 本身（参见 硬技能是扩展）。

5 分钟上手

1. 安装。 SpecForge 是一个无需依赖的单文件可执行程序。

curl -fsSL https://raw.githubusercontent.com/leaderiop/SpecForge/main/install.sh | sh

# Homebrew (once the tap is published)
brew install leaderiop/tap/specforge

# Prebuilt binary via cargo-binstall
cargo binstall --git https://github.com/leaderiop/SpecForge specforge-cli

# From source (stable Rust toolchain)
git clone https://github.com/leaderiop/SpecForge && cd SpecForge
cargo install --path crates/surfaces/cli

2. 在你的仓库中创建项目：

specforge init --extensions @specforge/software

这会生成一个 specforge.json，并在 spec/ 中创建第一个文件。如果是 Cargo 或 vitest 项目，还会启用相应的测试运行器。

3. 连接你的 Agent。 SpecForge 支持 MCP，因此任何 MCP 客户端都能读取并检查你的规范。请使用绝对路径：

claude mcp add specforge -- specforge mcp /path/to/your/project

在 Cursor 中，单击一次即可为当前打开的项目（${workspaceFolder}）添加它：

{
  "mcpServers": {
    "specforge": { "command": "specforge", "args": ["mcp", "/path/to/your/project"] }
  }
}

4. 让你的 Agent 编写规范。 例如：

在 spec/ 中为退款功能编写一份规范：说明其行为、绝不能违反的规则、发出的事件，以及证明每项内容的依据。使用 SpecForge 工具验证规范，并在展示给我之前修复所有错误。

5. 亲自查看结果。

specforge check     # is the spec consistent?
specforge review    # what is still unproven?

6. 关联测试。 每项测试都会说明它证明了哪个实体。在 Rust 中（使用 specforge-test crate）：

use specforge_test::prelude::*;

#[specforge_test(behavior = "issue_refund", verify = "refunds the requested amount")]
fn refunds_the_requested_amount() { /* ... */ }

在 vitest 中：

test('refunds the requested amount',
  { meta: { specforge: { behavior: 'issue_refund', verify: 'refunds the requested amount' } } },
  () => { /* ... */ })

然后运行 specforge collect。它会先征求一次许可，再运行你的测试命令，并记录每项测试证明的内容。请参阅 Rust 和 vitest 指南。

我必须学习一种新语言吗？

你需要阅读它，因为规范是由你审批的内容。但你很少需要编写它：你的 Agent 会编写和修复文件，而检查结果会告诉它哪里有误。

它的设计便于阅读。每个块只表示一项内容，包含类型、名称、标题和字段，就像填写好的表单：

invariant refund_within_capture "Refunds never exceed the captured amount" {
  guarantee "The sum of refunds on a payment never exceeds the captured amount"
  risk      high
}

要手动编写规范，请从编写教程和完整示例开始。

它与……有何不同？

硬技能是扩展

SpecForge 本身不了解支付、软件或任何其他领域。规范中的每个词（behavior、invariant、event）以及每条规则（“不变量必须由行为强制执行”）都来自某个扩展。扩展是一种以代码打包的硬技能：它包含一套词汇，以及用于判定这些词汇的规则。

以下扩展内置于二进制文件中：

使用 specforge add @specforge/product 启用扩展。完整列表见扩展清单。若要编写自己的硬技能，请参阅扩展 SpecForge。

未来方向

软件领域优先，是因为如今 AI 在这里编写的内容最多。但引擎本身有意不内置任何领域。它适用于任何专业知识都有规则且错误代价高昂的领域：受监管的软件（IEC 62304、GAMP 5）、制药质量（批次放行、偏差）和安全工程。在这些领域，“AI 起草，硬技能检查，合格人员签字”并非一句口号，而是工作必须遵循的方式。这些领域的扩展正在开发中，目前尚未内置。

此外，计划支持 Agent 通过类型化操作编辑规范，这样无论是人还是 AI，都不必手动编写 .spec 文本。

SpecForge 不是什么

• 不是 AI。 它不会调用模型。它是用 Rust 编写的确定性编译器。
• 不是代码生成器。 它检查意图，代码由你的 Agent 编写。
• 不是测试框架。 你的测试仍然由 cargo test 或 vitest 运行。只有在你批准命令后，SpecForge 才会运行测试，并记录测试证明的内容。

了解更多

• 编写教程：从零开始编写 .spec 文件，包含一个完整示例、一本指南、最佳实践和故障排除。
• Rust 测试追踪和vitest 测试追踪：将测试关联到它们所证明的实体。
• 形式化验证：由 SMT 求解器检查规范，并在确切位置提供反例。
• 快速参考：在一页中列出所有命令、实体类型和诊断代码。
• 愿景：宣言、原则和北极星。
• 架构、crate 结构图和贡献指南：了解 SpecForge 的构建方式、各 crate 的职责，以及如何参与开发。
• 文档中心：实体参考、可追溯链和研究资料。

许可证

你可以选择根据 Apache License, Version 2.0 或 MIT license 许可本项目。