Spec Kit 入门：AI Agent 时代的规格驱动开发实践

随着 Cursor、Claude Code、Codex 等 AI 编程工具的发展，软件开发正在发生一个明显变化：AI 已经不只是代码补全工具，而开始参与需求分析、架构设计、代码实现甚至测试工作。

但是，在实际使用过程中，很多开发者会发现一个问题：

AI 写代码的速度越来越快，但项目质量并没有同步提升。

原因很简单：软件开发并不只是"写代码"。

一个完整的软件功能，通常包含：

业务需求理解；
功能边界定义；
技术方案设计；
模块拆分；
编码实现；
测试验证。

而当前很多 AI 编程方式，往往跳过了前面的工程环节，直接进入代码生成阶段。

例如，我们告诉 AI：

"帮我实现一个聊天消息未读红点，只统计最近 7 天。"

对于人类开发者来说，这句话背后隐藏了大量需要确认的问题：

"最近 7 天"按照客户端时间还是服务器时间？
是消息发送时间还是接收时间？
超过 7 天的未读消息是否仍然保持未读状态？
只是隐藏红点，还是修改未读数量？
应该由客户端计算，还是服务端返回结果？
离线情况下如何处理？

如果这些问题没有提前明确，AI 很可能生成一套"看起来正确"的代码，但实际上并不符合业务要求。

Spec Kit 就是在解决这个问题。

它提出了一种新的开发方式：

Spec-Driven Development（规格驱动开发）。

核心思想是：

在让 AI 编写代码之前，先让 AI 理解软件应该如何被构建。

一、什么是 Spec Kit？

Spec Kit 是 GitHub 推出的一个开源工具，用于帮助开发者采用规格驱动开发方式构建软件。

传统软件开发流程：

复制代码

需求
 ↓
产品文档
 ↓
开发理解
 ↓
编码
 ↓
测试

AI 辅助开发初期常见流程：

复制代码

一句需求描述
 ↓
AI生成代码
 ↓
不断修改
 ↓
直到能运行

Spec Kit 推荐的流程：

复制代码

需求
 ↓
Specification（需求规格）
 ↓
Plan（技术方案）
 ↓
Tasks（任务拆解）
 ↓
Implementation（代码实现）
 ↓
验证

这里最大的变化是：

代码不再是开发过程的起点，而是规格说明的最终实现。

二、为什么 AI 编程需要 Spec？

1. AI 最大的问题不是不会写，而是不知道为什么写

大型软件项目中，真正困难的部分通常不是代码。

例如：

实现一个支付功能。

代码可能只是：

创建订单；
调用支付接口；
接收回调；
更新状态。

但是业务规则可能非常复杂：

支付失败如何处理？
重复回调怎么办？
用户关闭页面怎么办？
是否支持退款？
如何保证订单状态一致？

这些信息如果没有明确告诉 AI，它只能根据自己的经验猜测。

而 AI 最大的问题就是：

它可以生成合理的代码，但不一定生成正确的业务。

Spec 的作用，就是把隐藏在开发者脑中的业务规则显式化。

2. Spec 可以减少人与 AI 的沟通成本

普通方式：

开发者：

帮我开发一个登录功能。

AI：

生成登录页面、接口、状态管理。

然后开发者发现：

缺少验证码倒计时；
不支持国际手机号；
错误提示不符合产品要求。

于是不断修改。

Spec 方式：

先定义：

markdown 复制代码

功能：
手机号验证码登录

用户流程：

1. 输入手机号
2. 请求验证码
3. 输入验证码
4. 验证成功进入首页


业务规则：

- 验证码60秒内不能重复发送
- 支持国际手机号
- 登录失败需要展示错误原因

AI 在明确规则之后，再开始设计和编码。

三、Spec Kit 的核心概念

Spec Kit 主要包含几个核心阶段。

1. Constitution：项目规则

Constitution 可以理解为项目级开发规范。

它解决的问题：

如何让 AI 在整个项目中保持一致的开发方式。

例如一个 Flutter 项目：

markdown 复制代码

# Project Constitution

技术规范：

- 使用 Riverpod 管理状态
- 使用 Dio 作为网络层
- 所有接口必须统一异常处理
- 页面必须支持国际化
- 新功能必须包含测试

以后 AI 参与开发时，会遵守这些规则。

它类似团队中的：

编码规范；
架构约束；
技术决策文档。

2. Specification：功能规格

Specification 是 Spec Kit 最核心的部分。

它描述：

"我们要解决什么问题"。

例如：

文件：

bash 复制代码

specs/001-login/spec.md

内容：

markdown 复制代码

# 手机号登录

## 背景

用户需要快速注册并进入应用。


## 功能要求

- 支持手机号输入
- 支持验证码登录
- 验证码有效期60秒


## 验收标准

用户输入正确验证码后进入首页。

验证码错误时提示失败原因。

注意：

Spec 不描述代码怎么写。

它描述：

用户为什么需要这个功能；
功能应该具备什么行为；
什么情况下算完成。

3. Plan：技术设计

有了 Spec 后，再进行技术设计。

例如：

复制代码

spec.md

实现手机号登录

对应：

复制代码

plan.md

描述：

bash 复制代码

技术方案：

Flutter:

LoginPage
    |
LoginController
    |
LoginRepository
    |
LoginApi


新增文件：

features/login/

login_page.dart

login_controller.dart

login_repository.dart

这里就是技术负责人最关注的内容。

因为技术负责人关注的不是：

"某一行代码怎么写。"

而是：

"这个系统应该如何设计。"

4. Tasks：任务拆分

Plan 确定之后，需要拆成执行任务。

例如：

diff 复制代码

Task List:

- 创建登录 API
- 实现验证码倒计时
- 完成登录页面
- 增加异常处理
- 添加单元测试

任务拆分之后，AI Agent 更容易执行。

四、Spec Kit 项目目录如何组织？

一个典型项目结构：

vbnet 复制代码

project/

├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── templates/
│   └── scripts/
│
├── specs/
│   ├── 001-login/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│   │
│   ├── 002-chat/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│
├── lib/
│   ├── features/
│   │   ├── login/
│   │   └── chat/
│
└── README.md

其中：

.specify

保存项目规则。

specs

保存每个功能的设计过程。

代码目录：

vbnet 复制代码

lib/

保存最终实现。

整个关系：

复制代码

为什么做？
   ↓
spec.md


怎么做？
   ↓
plan.md


做哪些事情？
   ↓
tasks.md


最终结果
   ↓
代码

五、一个 Flutter 项目的实际使用流程

假设我们开发一个 AI 聊天 App。

需求：

用户可以和 AI 对话，并实时看到回复。

第一步：创建 Spec

创建：

bash 复制代码

specs/001-ai-chat/spec.md

定义：

diff 复制代码

功能：

AI聊天


要求：

- 用户输入文字
- AI返回回复
- 支持流式输出
- 保存历史记录


限制：

- 网络异常需要提示
- 支持重新发送

第二步：生成技术方案

根据 Spec：

设计：

复制代码

Flutter

ChatPage

↓

ChatController

↓

ChatRepository

↓

AI API

同时确定：

数据结构；
状态管理方式；
网络请求方式；
缓存策略。

第三步：拆任务

生成：

复制代码

tasks.md

例如：

markdown 复制代码

1. 创建聊天页面

2. 实现消息列表

3. 接入AI接口

4. 实现流式响应

5. 增加历史记录缓存

第四步：交给 AI 编码

这时候使用：

Cursor；
Claude Code；
Codex。

告诉 AI：

根据 spec 和 plan 完成功能实现。

AI 不再从零猜测，而是在明确约束下开发。

六、Spec Kit 和 Cursor 的关系

很多人会误认为：

"用了 Spec Kit，是不是不用 Cursor 了？"

不是。

它们解决的问题不同。

Cursor、Claude Code、Codex：

负责：

代码生成；
修改代码；
执行任务。

Spec Kit：

负责：

明确需求；
设计方案；
管理开发流程。

可以理解为：

复制代码

Spec Kit

负责思考：
做什么？
为什么做？
怎么设计？


AI Agent

负责执行：
具体怎么编码。

两者结合，才是完整的 AI 开发流程。

七、Spec Kit 对技术负责人的意义

对于普通开发者来说，Spec Kit 是一个提高 AI 使用效率的工具。

但是对于技术负责人，它的意义更大。

未来的软件开发模式可能会变成：

以前：

复制代码

技术负责人

设计架构
↓

开发人员

写代码

未来：

复制代码

技术负责人

定义需求
设计系统
制定约束

↓

AI Agent

完成大量实现工作

技术负责人的核心能力，会逐渐从：

"写多少代码"

转变为：

"能否定义正确的问题，并控制 AI 输出质量"。

Spec Kit 实际强化的是：

需求分析能力；
架构设计能力；
工程管理能力；
AI 协作能力。

八、Spec Kit 的适用场景

适合：

新项目

例如：

Flutter App；
SaaS 系统；
AI 产品；
多端应用。

中大型功能

例如：

支付系统；
IM 系统；
用户体系；
权限系统。

多人团队协作

Spec 可以成为团队共享知识。

新人加入项目，不需要只看代码，也可以先理解：

为什么设计这个功能；
技术方案是什么；
历史决策是什么。

九、Spec Kit 的局限

Spec Kit 并不是万能工具。

简单修改：

复制代码

调整按钮颜色

修改文字

增加一个字段

没有必要创建完整 Spec。

另外：

Spec 本身也需要维护成本。

如果团队只是形式化地写文档，但没人维护，那么 Spec 很快会失去价值。

真正有效的 Spec：

应该成为代码和业务之间的桥梁。

总结

Spec Kit 的核心并不是生成代码，而是改变 AI 编程方式。

过去：

复制代码

需求 → 人理解 → 写代码

未来：

复制代码

需求 → Spec → AI理解 → 自动实现

AI 的能力正在快速提升，但软件工程中的"思考、设计、约束"仍然需要人负责。 Spec Kit 提供了一套方法，让开发者可以更高质量地使用 AI Agent。对于个人开发者，它可以提升 AI 编程效率。对于团队，它更像是一套面向未来的软件研发流程。在 AI 时代，优秀的工程师不一定是写代码最快的人，而是能够定义正确问题、设计正确方案，并让 AI 高效完成实现的人。