被ai写的代码气死了？接入 agent-spec，让 AI 写的代码“可验证”，确实可以封神了！

开源工具 · 实战

2026.07

让 AI 写功能，就高枕无忧了？

写了 ≠ 写对了

给 AI 套张「合同」兜底

Spec-Driven · 机器验证 · 本地开源

agent-spec

RUSTMIT

需求在聊天里说一遍就散了，AI 记不住，你也难复查。这就是现在 AI 编程最大的坑：「写了」不等于「写对了」。

01

PART

痛点：写了 ≠ 写对

THE REAL TRAP OF AI CODING

你用 Cursor、Claude Code 这类 AI 编程工具让模型写功能，是不是经常遇到这种情况：它「啪」一下给你写了一大堆，跑起来才发现——根本不是你要的那个东西？

需求在聊天里说一遍就散了，AI 记不住，你也难复查。这就是现在 AI 编程最大的坑：「写了」不等于「写对了」。

今天给大家安利一个能把这个坑填上的开源工具——agent-spec。它给 AI 编程套了一层「规格 + 机器验证」的安全网：你先写一份「任务合同」，AI 照合同写，写完了机器自动逐条核对「代码到底满不满足合同」。

02

PART

agent-spec 是什么

A SAFETY NET FOR AI CODING

2026 年 AI 编程圈都在聊的 Spec-Driven Development（规格驱动开发），它算是把这套思路做得最实在的一个。

agent-spec = 给 AI 编程套一层「规格 + 机器验证」的安全网。它不替你写产品判断，但能确保「AI 写出来的代码，确实满足了你定义的合同」。

03

PART

这样做有哪些好处

THREE CORE BENEFITS

三个核心好处

1

需求变「合同」，AI 不再瞎发挥：把「我要个用户注册接口」写成一份 Task Contract（含意图 / 已定决策 / 边界 / 完成条件）。AI 是照合同干活，不是凭感觉发挥，跑偏的概率直接降一大截。

2

机器自动验证，不靠人肉 review：代码写完跑一条命令，agent-spec 按 BDD 场景逐条核对「代码是否满足合同」，pass / fail 机器判定。你不用一行行肉眼看，也不用反复和 AI 扯皮「你这不对」。

3

免费开源、本地跑、零成本：Rust 写的，性能快；MIT 协议，完全免费；cargo install 一行就能装上，所有东西都在你本地，不用担心代码外泄。

04

PART

框架选择一句话选型

ONE-LINE POSITIONING

agent-spec = 给 AI 编程套一层「规格 + 机器验证」的安全网。它不替你写产品判断，但能确保「AI 写出来的代码，确实满足了你定义的合同」。如果你已经被 AI 写跑偏折磨过，它就是那个兜底的人。

一句话记住它的位置：它是安全网，不是自动驾驶。产品该怎么设计、业务边界在哪，还是你说了算；它只负责把「写对了」这件事，从人肉复查变成机器判定。

05

PART

核心闭环

HUMAN → AI → MACHINE

agent-spec 的核心闭环只有三步，人和机器各司其职：

人审合同

你写 Task Contract，定边界

→

AI 照合同实现

在边界内编码

→

机器验证是否满足

lifecycle 逐条核对

照合同写 → 机器帮你把关，不再互相猜

06

PART

详细搭建步骤

STEP BY STEP · 小白友好

STEP 01

装好 Rust 工具链（cargo）

agent-spec 是 Rust 写的，靠 cargo 安装。先确认你有没有装：

bash

cargo --version

如果报错说没有，一条命令装好（Mac / Linux）：

bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

装完重开终端，cargo --version 能看到版本号就 OK 了。

STEP 02

一行命令装 agent-spec

bash

cargo install agent-spec

装完验证一下：

bash

agent-spec --version

✦ 实测

这条命令几十秒就装完，比想象中轻量。

如果你想让 Claude Code / Cursor 这类 AI 编程工具直接「认识」它，仓库还带了 5 个 Agent Skill。最简单的方式是把它们软链到全局 skills 目录（以 Claude Code 为例）：

bash

git clone https://github.com/ZhangHanDong/agent-spec.git

cd agent-spec

ln -s "$(pwd)/skills/agent-spec-tool-first" ~/.claude/skills/

ln -s "$(pwd)/skills/agent-spec-authoring" ~/.claude/skills/

也可以直接跑仓库里的 ./install-skills.sh，它会自动 cargo install 并复制全部 5 个 skill。AI 工具装上后，会主动用 contract / lifecycle / guard 来驱动任务。

STEP 03

写一份合同，让 AI 照着写 + 机器来验证

先初始化一份合同模板（支持中文 --lang zh）：

bash

agent-spec init --level task --lang zh --name "用户注册接口"

它会生成一份 .spec 文件，你照着填四块：意图、已定决策、边界、完成条件。比如一段真实可跑的中文写法：

spec

## 意图

实现确定性的用户注册接口，AI 可照此编码，验证器可逐条核对。

## 已定决策

- 仅用 POST /api/v1/users/register 作为唯一公开入口

- 密码哈希成功后才持久化新用户

## 边界

### 允许变动

- crates/api/**

- tests/integration/register_api.rs

### 禁止

- 不得改动已有登录接口的合同

- 注册时不得创建会话

## 完成条件

场景: 注册成功返回 201

　测试: test_register_api_returns_201_for_new_user

　假设 不存在邮箱为 "alice@example.com" 的用户

　当 客户端提交注册请求（email=alice@example.com, password=Str0ng!Pass#2026）

　那么 响应状态码为 201

　并且 响应体应包含 "user_id"

合同写好后，把「合同 + 你的代码库上下文」一起喂给 AI，让它照着写：

bash

agent-spec plan specs/用户注册接口.spec --code .

这个命令会输出三段：完整合同、代码库上下文（哪些文件能改、现有测试函数）、实现提示。把输出贴给 AI，它就能在边界内干活。

代码写完后，跑验证——这是最爽的一步：

bash

agent-spec lifecycle

机器会按「完成条件」里的场景逐条核对，通过的打勾，没过的标红并指出哪里不满足。第一次跑出满屏绿勾的时候，确实有点「终于不用和 AI 互相猜了」的爽感。

想做整个仓库级别的检查，再补一条：

bash

agent-spec guard

07

PART

选型补充（信息增量）

VS OpenSpec / SpecKit

同类里还有 OpenSpec、SpecKit 等。agent-spec 的差异点在于：中间的每一道关（lint / graph / plan / lifecycle / trace）都是确定性、不依赖模型的，只有「起草需求」和「实现合同」两端才用 AI。

并且它强调「活性追踪（liveness）」——代码改了之后，合同是否还被满足会重新算，不把旧结论存死。仓库里的 docs/comparison-openspec-speckit.md 有详细对比，选型时值得翻一眼。

一句话：同类工具拼「AI 多聪明」，agent-spec 拼「验证多确定」。前者依赖模型，后者依赖规则——这正是它敢说「免费、本地、不靠猜」的底气。

///

LAST

写在最后

SUMMARY

在 AI 编程越来越普及的 2026 年，「让 AI 写」已经不是问题，「让 AI 写对」才是。agent-spec 的思路很朴素也很有效：先把需求变成可验证的合同，再让机器替你把关。

免费、开源、本地跑、Rust 写的快，普通项目也能轻松上车。