跳到主要内容GitHub Spec-Kit 上手与规范驱动开发实践 | 极客日志JavaVScodeNode.jsAIjava
GitHub Spec-Kit 上手与规范驱动开发实践
Spec-Kit 是 GitHub 的规范驱动开发工具包,核心做法是先写规范、再生成代码和任务拆解,让需求、设计、接口和测试保持一致。文章梳理了安装、初始化项目、编写 constitution、生成 spec/plan/tasks、执行 implement 的完整流程,也用订单评价功能演示了如何落到真实项目。它更适合 CRUD 密集型和团队协作项目,能减少返工和沟通成本,但前提是规范本身要写清楚。
Spec-Kit 上手与规范驱动开发
Spec-Kit 是什么
Spec-Kit 是 GitHub 推出的一个工具包,面向规范驱动开发(Spec-Driven Development)。它把需求、设计、任务拆解和实现过程串成一条线,适合让 AI 参与开发,但前提不是'让 AI 直接写',而是先把规则和边界说清楚。
它的思路很直接:先写规范,再动代码。规范写得越细,后面生成的内容越不容易跑偏。反过来,如果需求本来就模糊,工具再强也只是把模糊放大。
它解决的不是'写代码慢'这么简单
Spec-Kit 更像是在处理几个老问题。
- 需求在多人之间传递后容易变形
- CRUD 类工作重复,容易把时间耗在低价值劳动上
- 文档和代码分离后,后期维护会越来越吃力
- 团队没有统一写法时,审查和交接都很费劲
所以它的价值不在'自动生成多少代码',而在把开发过程标准化。对小团队来说,这能少掉不少沟通成本;对多人协作项目来说,收益更明显。
它的核心优势
规范驱动,而不是先写再补
传统流程:需求 → 直接编码 → 测试 → 部署
Spec-Kit 流程:需求 → 规范文档 → AI 生成代码 → 测试 → 部署
这条链路看起来只是顺序变了,实际影响不小。先把约束写下来,很多争议会提前暴露,不会等到代码写完才发现方向错了。
AI 参与,但不替你做判断
- 基于规范生成代码
- 根据功能描述补测试
- 在文档和实现之间维持同步
这里要分清楚:Spec-Kit 不是把开发工作全交给 AI,而是把 AI 放到一个更可控的位置。规范足够清晰时,它很省事;规范不清楚时,它也一样会产出一堆看起来像样、但不好用的东西。
文档不是附属品
Spec-Kit 会把需求规范、技术规范、API 规范、测试规范放在同一套流程里。这个设计不花哨,但很实用。很多项目的问题不是没文档,而是文档跟实现脱节,最后谁都不信。
环境准备
基础要求
- 操作系统:Windows 10/11、macOS 10.15+、Ubuntu 18.04+
- 内存:至少 8GB RAM
- 存储:至少 10GB 可用空间
需要先装好的软件
git --version
node --version
npm --version
python --version
java --version
mvn --version
安装 Spec-Kit
用 pip 安装
pip install spec-kit
speckit --version
从源码安装
git clone https://github.com/github/spec-kit.git
spec-kit
pip install -e .
speckit --version
cd
配置开发环境
Git 基础配置
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
如果你在 Linux 上,还要配 Git Credential Manager。这个步骤不算优雅,但实际用起来省心,尤其是需要频繁拉取和推送时。
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
IDE 选择
- VS Code + GitHub Copilot
- Cursor
- IntelliJ IDEA + GitHub Copilot
初始化项目目录
mkdir my-spec-project
cd my-spec-project
git init
实际操作流程
初始化项目
speckit init
speckit init --template web-app
my-spec-project/
├── CLAUDE.md
├── memory/
│ └── constitution.md
├── scripts/
│ ├── check-prerequisites.sh
│ ├── common.sh
│ ├── create-new-feature.sh
│ ├── setup-plan.sh
│ └── update-claude-md.sh
├── specs/
├── templates/
│ ├── CLAUDE-template.md
│ ├── plan-template.md
│ ├── spec-template.md
│ └── tasks-template.md
└── README.md
先写项目宪法
constitution.md 的作用很像项目的底线说明。它不负责写细节,但要把大方向钉住。
# 项目宪法 (Project Constitution)
## 核心原则
1. **用户至上**:所有功能都以用户体验为中心
2. **代码质量**:遵循最佳实践,确保代码可维护性
3. **文档驱动**:先写文档,再写代码
4. **测试优先**:所有功能都必须有对应的测试
5. **安全第一**:安全性是每个功能的基本要求
## 技术栈
- **前端**:Vue 3 + Vite + Element Plus
- **后端**:Spring Boot + MyBatis Plus
- **数据库**:MySQL/PostgreSQL
- **部署**:Docker + Nginx
## 开发规范
- 使用 TypeScript 进行类型检查
- 遵循 RESTful API 设计原则
- 使用 Git Flow 进行版本管理
- 代码审查是必须的流程
## 质量标准
- 代码覆盖率 > 80%
- 性能测试通过
- 安全扫描无高危漏洞
- 用户体验测试通过
创建功能规范
speckit.plan "创建一个用户管理系统,包含用户注册、登录、权限管理功能。使用 Vue 3 前端,Spring Boot 后端,MySQL 数据库。需要支持角色权限控制,用户信息 CRUD 操作。"
specs/001-user-management/
├── contracts/
│ ├── api-spec.json
│ └── database-spec.md
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
└── spec.md
cat specs/001-user-management/spec.md
cat specs/001-user-management/plan.md
cat specs/001-user-management/research.md
细化技术规范
research.md 里通常会放技术选型理由和数据库设计。这个文件的意义不是'写得漂亮',而是让后面的人知道为什么这么选。
# 技术调研文档
## 前端技术选型
### Vue 3 优势
- Composition API 提供更好的逻辑复用
- 更好的 TypeScript 支持
- 性能提升,包体积更小
- 生态成熟,社区活跃
### Element Plus 选择理由
- 与 Vue 3 完美兼容
- 组件丰富,满足企业级需求
- 文档完善,学习成本低
- 主题定制灵活
## 后端技术选型
### Spring Boot 优势
- 快速开发,约定优于配置
- 生态丰富,集成简单
- 企业级应用首选
- 社区支持强大
### MyBatis Plus 选择理由
- 简化 CRUD 操作
- 代码生成器支持
- 分页插件内置
- 性能优化工具
## 数据库设计
### 用户表设计
```sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) UNIQUE NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role_id BIGINT,
status TINYINT DEFAULT 1,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
角色表设计
CREATE TABLE roles (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(50) UNIQUE NOT NULL,
description TEXT,
permissions JSON,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
`contracts/api-spec.json` 里定义接口结构,后面生成代码和联调时都会用到。
```json
{
"openapi": "3.0.0",
"info": {
"title": "用户管理系统 API",
"version": "1.0.0",
"description": "用户管理系统的 RESTful API 规范"
},
"paths": {
"/api/users": {
"get": {
"summary": "获取用户列表",
"parameters": [
{ "name": "page", "in": "query", "schema": {"type": "integer", "default": 1} },
{ "name": "size", "in": "query", "schema": {"type": "integer", "default": 10} }
],
"responses": {
"200": {
"description": "成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {"type": "integer"},
"message": {"type": "string"},
"data": {
"type": "object",
"properties": {
"records": {"type": "array", "items": {"$ref": "#/components/schemas/User"}},
"total": {"type": "integer"}
}
}
}
}
}
}
}
}
},
"post": {
"summary": "创建用户",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {"$ref": "#/components/schemas/CreateUserRequest"}
}
}
},
"responses": {
"201": {
"description": "创建成功",
"content": {
"application/json": {
"schema": {"$ref": "#/components/schemas/User"}
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"username": {"type": "string"},
"email": {"type": "string"},
"roleId": {"type": "integer"},
"status": {"type": "integer"},
"createdAt": {"type": "string", "format": "date-time"},
"updatedAt": {"type": "string", "format": "date-time"}
}
},
"CreateUserRequest": {
"type": "object",
"required": ["username", "email", "password"],
"properties": {
"username": {"type": "string"},
"email": {"type": "string"},
"password": {"type": "string"},
"roleId": {"type": "integer"}
}
}
}
}
}
拆任务
生成的 tasks.md 会把工作拆成几段,常见的顺序是基础架构、数据模型、API、前端、测试。这个拆法不新鲜,但对团队协作来说够用。
# 用户管理系统实施任务
## 阶段 1:基础架构搭建
### 任务 1.1:项目结构初始化
[P] - **文件路径**:`backend/src/main/java/com/example/usermanagement/`
- **描述**:创建 Spring Boot 项目基础结构
- **依赖**:无
- **验收标准**:项目可以正常启动
### 任务 1.2:数据库配置
[P] - **文件路径**:`backend/src/main/resources/application.yml`
- **描述**:配置 MySQL 数据库连接
- **依赖**:无
- **验收标准**:数据库连接正常
### 任务 1.3:前端项目初始化
[P] - **文件路径**:`frontend/`
- **描述**:创建 Vue 3 项目并配置 Element Plus
- **依赖**:无
- **验收标准**:前端项目可以正常启动
开始实施
🚀 开始实施用户管理系统...
✅ 阶段 1:基础架构搭建
✅ 任务 1.1:项目结构初始化 - 完成
✅ 任务 1.2:数据库配置 - 完成
✅ 任务 1.3:前端项目初始化 - 完成
✅ 阶段 2:数据模型实现
✅ 任务 2.1:创建用户实体类 - 完成
✅ 任务 2.2:创建角色实体类 - 完成
✅ 任务 2.3:创建数据库表 - 完成
✅ 阶段 3:后端 API 实现
✅ 任务 3.1:创建用户 Repository - 完成
✅ 任务 3.2:创建用户 Service - 完成
✅ 任务 3.3:创建用户 Controller - 完成
✅ 阶段 4:前端界面实现
✅ 任务 4.1:创建用户列表组件 - 完成
✅ 任务 4.2:创建用户表单组件 - 完成
✅ 任务 4.3:集成 API 调用 - 完成
✅ 阶段 5:测试和优化
✅ 任务 5.1:编写单元测试 - 完成
✅ 任务 5.2:编写集成测试 - 完成
✅ 任务 5.3:性能优化 - 完成
🎉 用户管理系统实施完成!
cd backend
mvn spring-boot:run
cd frontend
npm run dev
npm test
mvn test
放到真实项目里怎么用
这里拿'订单评价功能'做个例子。这个场景很典型:需求不算复杂,但如果没有规范,接口、表结构、页面状态很容易各写各的。
speckit.plan "为现有的订单管理系统添加订单评价功能。用户可以对已完成的订单进行评价,包括评分(1-5 星)和评价内容。评价信息需要存储到数据库,并在订单详情页面显示。需要支持评价的增删改查操作,以及评价统计功能。"
specs/002-order-review/
├── contracts/
│ ├── api-spec.json
│ └── database-spec.md
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md
数据模型里可以把评价表和统计表分开,避免每次查列表都临时聚合;这个选择不是为了炫技,主要是后面做统计和展示时更省力。
CREATE TABLE oms_order_review (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键 ID',
order_id VARCHAR(50) NOT NULL COMMENT '订单 ID',
customer_id BIGINT NOT NULL COMMENT '客户 ID',
rating TINYINT NOT NULL COMMENT '评分 (1-5)',
content TEXT COMMENT '评价内容',
images JSON COMMENT '评价图片',
status TINYINT DEFAULT 1 COMMENT '状态 (1:正常 0:删除)',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
INDEX idx_order_id (order_id),
INDEX idx_customer_id (customer_id),
INDEX idx_created_at (created_at)
) COMMENT='订单评价表';
CREATE TABLE oms_order_review_stats (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
order_id VARCHAR(50) NOT NULL,
avg_rating DECIMAL(3,2) DEFAULT 0.00 COMMENT '平均评分',
total_reviews INT DEFAULT 0 COMMENT '评价总数',
rating_distribution JSON COMMENT '评分分布',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_order_id (order_id)
) COMMENT='订单评价统计表';
{
"paths": {
"/api/order-review": {
"post": {
"summary": "创建订单评价",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["orderId", "rating"],
"properties": {
"orderId": {"type": "string"},
"rating": {"type": "integer", "minimum": 1, "maximum": 5},
"content": {"type": "string"},
"images": {"type": "array", "items": {"type": "string"}}
}
}
}
}
}
}
},
"/api/order-review/{orderId}": {
"get": {
"summary": "获取订单评价列表",
"parameters": [
{"name": "orderId", "in": "path", "required": true, "schema": {"type": "string"}}
]
}
}
}
}
后端和前端任务也会被拆开,路径、职责、验收标准都能落到文件上。这样做的好处是,团队里谁接手都能看懂,不需要再靠口头约定补齐。
我对它的判断
Spec-Kit 适合两类场景:一类是 CRUD 比较重的企业项目,另一类是团队已经有 AI 工具,但一直没形成稳定流程的项目。
它不是银弹。真正麻烦的地方从来不是'有没有工具',而是'规范能不能写清楚'。如果需求本身就反复,或者团队不愿意先花时间把边界说透,那 Spec-Kit 只能帮你更快地产出混乱。
但如果你本来就打算把文档、任务拆分和实现流程做扎实,它会比单纯让 AI 补代码更稳。省下来的不是敲键盘的时间,而是返工和扯皮的时间。
常见用法里的几个坑
- 需求描述太泛,生成结果就会很空
- 技术栈没写死,后面容易偏离现有项目
- 只看生成代码,不看规范和任务文件
- 任务拆得太碎,反而增加维护成本
参考资料
相关免费在线工具
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online