PythonNode.jsAIjava
GitHub Spec-Kit 规范驱动开发实战指南
本文介绍 GitHub Spec-Kit 工具，一种基于 AI 辅助的规范驱动开发方法。内容涵盖环境准备、安装配置、核心操作流程（项目初始化、定义宪法、创建规范、任务分解、实施），以及企业级订单评价功能的实际案例演示。通过详细步骤和最佳实践，帮助团队建立标准化流程，提升开发效率与代码质量，减少技术债务。
本文介绍 GitHub Spec-Kit 工具，一种基于 AI 辅助的规范驱动开发方法。内容涵盖环境准备、安装配置、核心操作流程（项目初始化、定义宪法、创建规范、任务分解、实施），以及企业级订单评价功能的实际案例演示。通过详细步骤和最佳实践，帮助团队建立标准化流程，提升开发效率与代码质量，减少技术债务。
Spec-Kit 是 GitHub 官方推出的一个工具包，专门用于规范驱动开发（Spec-Driven Development）。它帮助开发团队通过 AI 辅助的方式，从需求分析到代码实现，建立一套完整的、可重复的开发流程。
Spec-Kit 基于一个简单而强大的理念：先写规范，再写代码。通过详细的规范文档，AI 可以更好地理解项目需求，生成高质量的代码，减少返工和沟通成本。
传统开发流程：需求 → 直接编码 → 测试 → 部署
Spec-Kit 流程：需求 → 规范文档 → AI 生成代码 → 测试 → 部署
# 1. Git (版本控制)
git --version # 需要 2.20+
# 2. Node.js (前端开发)
node --version # 需要 18.0+
npm --version # 需要 7.7+
# 3. Python (Spec-Kit 工具)
python --version # 需要 3.8+
# 4. Java (后端开发，如适用)
java --version # 需要 11+
# 5. Maven (Java 项目管理，如适用)
mvn --version
# 安装 Spec-Kit
pip install spec-kit
# 验证安装
speckit --version
# 克隆仓库
git clone https://github.com/github/spec-kit.git
cd spec-kit
# 安装依赖
pip install -e .
# 验证安装
speckit --version
# 设置用户信息
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# 配置 Git Credential Manager (Linux 用户)
# 下载并安装 GCM
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
推荐使用支持 AI 的 IDE：
# 创建项目根目录
mkdir my-spec-project
cd my-spec-project
# 初始化 Git 仓库
git init
# 在项目根目录执行
speckit init
# 或者使用模板初始化
speckit init --template web-app
执行后会自动生成以下目录结构：
my-spec-project/
├── CLAUDE.md # Claude AI 配置文件
├── 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
# 项目宪法 (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/ 目录下生成：
specs/001-user-management/
├── contracts/ # 接口契约
│ ├── api-spec.json # API 规范
│ └── 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
# 技术调研文档
## 前端技术选型
### 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
);
##### 4.2 完善 API 规范
编辑 `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": {
: ,
: {
: {: , : {: }},
: {: }
}
}
}
}
}
}
}
}
},
: {
: ,
: {
: ,
: {
: {
: {: }
}
}
},
: {
: {
: ,
: {
: {
: {: }
}
}
}
}
}
}
},
: {
: {
: {
: ,
: {
: {: },
: {: },
: {: },
: {: },
: {: },
: {: , : },
: {: , : }
}
},
: {
: ,
: [, , ],
: {
: {: },
: {: },
: {: },
: {: }
}
}
}
}
}
# 基于规范生成任务分解
speckit.tasks
执行后会在 specs/001-user-management/ 目录下生成 tasks.md：
# 用户管理系统实施任务
## 阶段 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
- **依赖**：无
- **验收标准**：前端项目可以正常启动
# 开始实施
speckit.implement
命令执行过程中会显示：
🚀 开始实施用户管理系统...
✅ 阶段 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
基于您当前的项目结构，我们来演示如何使用 Spec-Kit 添加订单评价功能。
从您的项目结构可以看出：
# 在项目根目录执行
speckit.plan "为现有的订单管理系统添加订单评价功能。用户可以对已完成的订单进行评价，包括评分（1-5 星）和评价内容。评价信息需要存储到数据库，并在订单详情页面显示。需要支持评价的增删改查操作，以及评价统计功能。"
specs/002-order-review/
├── contracts/
│ ├── api-spec.json # 评价 API 规范
│ └── database-spec.md # 评价表结构
├── data-model.md # 评价数据模型
├── plan.md # 实施计划
├── quickstart.md # 快速开始
├── research.md # 技术调研
├── spec.md # 功能规范
└── tasks.md # 任务分解
数据模型 (data-model.md)：
# 订单评价数据模型
## 评价表 (oms_order_review)
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='订单评价表';
评价统计表 (oms_order_review_stats)
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='订单评价统计表';
API 规范 (contracts/api-spec.json)：
{
"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：创建评价实体类
- **文件路径**：`rl-entbase_server/src/main/java/com/eci/project/omsOrderReview/entity/OmsOrderReview.java`
- **描述**：创建订单评价实体类，包含所有字段和 MyBatis Plus 注解
### 任务 2：创建评价 Mapper
- **文件路径**：`rl-entbase_server/src/main/java/com/eci/project/omsOrderReview/mapper/OmsOrderReviewMapper.java`
- **描述**：创建数据访问层接口
### 任务 3：创建评价 Service
- **文件路径**：`rl-entbase_server/src/main/java/com/eci/project/omsOrderReview/service/OmsOrderReviewService.java`
- **描述**：实现评价业务逻辑，包括评分统计
### 任务 4：创建评价 Controller
- **文件路径**：`rl-entbase_server/src/main/java/com/eci/project/omsOrderReview/controller/OmsOrderReviewController.java`
- **描述**：实现评价 REST API
前端实施任务：
## 前端实施任务
### 任务 1：创建评价列表组件
- **文件路径**：`rl-entbase_web/src/web/appRl-entbase/OmsOrderReview/OmsOrderReviewList.vue`
- **描述**：实现评价列表展示，支持分页和筛选
### 任务 2：创建评价表单组件
- **文件路径**：`rl-entbase_web/src/web/appRl-entbase/OmsOrderReview/OmsOrderReviewForm.vue`
- **描述**：实现评价新增和编辑表单，包含星级评分组件
### 任务 3：创建评价 API
- **文件路径**：`rl-entbase_web/src/web/appRl-entbase/apis/manage/omsOrderReview.js`
- **描述**：创建评价相关的 API 调用方法
### 任务 4：集成到订单详情页
- **文件路径**：`rl-entbase_web/src/web/appRl-entbase/OmsOrder/OmsOrderDetail.vue`
- **描述**：在订单详情页添加评价展示和新增功能
# 执行实施命令
speckit.implement
# 验证实施结果
# 1. 检查后端代码生成
ls rl-entbase_server/src/main/java/com/eci/project/omsOrderReview/
# 2. 检查前端代码生成
ls rl-entbase_web/src/web/appRl-entbase/OmsOrderReview/
# 3. 启动服务验证
cd rl-entbase_server && mvn spring-boot:run
cd rl-entbase_web && npm run dev
A: Spec-Kit 特别适合以下类型的项目：
A: 通过以下方式保证代码质量：
A: 集成方式：
A: 需求变更处理流程：
A: 学习成本分析：
A: 效果衡量指标：
❌ 不好的描述："用户需要能够管理订单"
✅ 好的描述："用户需要能够：
- 查看订单列表，支持按状态、时间、客户筛选
- 创建新订单，包含订单基本信息、商品信息、收货地址
- 编辑订单信息，但已发货订单只能修改收货地址
- 删除草稿状态的订单
- 导出订单数据为 Excel 格式"
# 技术约束
- 数据库：使用 MySQL 8.0，表名使用下划线命名
- 后端：Spring Boot 2.4.5，使用 MyBatis Plus
- 前端：Vue 3.2+，使用 Element Plus UI 组件
- API：遵循 RESTful 设计，返回统一格式
- 安全：所有 API 需要 JWT 认证
- 性能：列表查询响应时间 < 500ms
# 数据模型设计原则
1. 字段命名：使用下划线命名法
2. 主键：统一使用 id 作为主键，BIGINT 类型
3. 时间字段：created_at, updated_at 使用 TIMESTAMP
4. 软删除：使用 status 字段，1=正常，0=删除
5. 索引：为查询字段添加适当索引
6. 注释：所有表和字段都要有中文注释
# 规范版本管理
git flow init
# 功能开发流程
git checkout -b feature/order-review
# 开发完成后
git checkout develop
git merge feature/order-review
git push origin develop
# 发布流程
git checkout -b release/v1.2.0
# 测试完成后
git checkout main
git merge release/v1.2.0
git tag v1.2.0
# 代码审查检查清单
## 功能实现
- [ ] 功能是否按规范实现
- [ ] 边界条件是否处理
- [ ] 错误处理是否完善
## 代码质量
- [ ] 代码结构是否清晰
- [ ] 命名是否规范
- [ ] 注释是否充分
## 性能安全
- [ ] 是否存在性能问题
- [ ] 是否存在安全漏洞
- [ ] 数据库查询是否优化
## 测试覆盖
- [ ] 单元测试是否充分
- [ ] 集成测试是否通过
- [ ] 测试覆盖率是否达标
# 文档维护原则
1. 文档与代码同步更新
2. 使用版本控制管理文档
3. 定期审查文档准确性
4. 建立文档更新流程
5. 培训团队文档编写规范
# 团队角色分工
## 产品经理
- 负责需求分析和规范编写
- 与客户沟通确认需求
- 验收功能实现
## 架构师
- 负责技术架构设计
- 制定开发规范
- 代码审查和技术指导
## 开发工程师
- 负责功能实现
- 编写单元测试
- 参与代码审查
## 测试工程师
- 负责测试用例设计
- 执行功能测试
- 性能和安全测试
# 沟通机制
## 日常沟通
- 每日站会：同步进度和问题
- 周例会：总结和计划
- 月度回顾：经验总结和改进
## 技术沟通
- 技术分享会：分享新技术和最佳实践
- 代码审查：技术讨论和知识传递
- 文档评审：确保规范理解一致
## 问题处理
- 问题升级机制：及时上报和解决
- 知识库建设：积累问题和解决方案
- 经验分享：避免重复问题
# CI/CD 配置示例
name: CI/CD Pipeline
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Java
uses: actions/setup-java@v2
with:
java-version: '11'
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: '18'
- name: Run Backend Tests
run: |
cd rl-entbase_server
mvn test
- name: Run Frontend Tests
run: |
cd rl-entbase_web
npm test
- name: Code
// ESLint 配置示例
{
"extends": ["@vue/typescript/recommended", "plugin:vue/vue3-recommended"],
"rules": {
"vue/multi-word-component-names": "off",
"@typescript-eslint/no-unused-vars": "error",
"vue/require-default-prop": "error"
}
}
# 性能监控指标
## 前端性能
- 页面加载时间 < 3 秒
- 首屏渲染时间 < 1.5 秒
- 交互响应时间 < 100ms
## 后端性能
- API 响应时间 < 500ms
- 数据库查询时间 < 100ms
- 内存使用率 < 80%
## 系统性能
- 并发用户数 > 1000
- 系统可用性 > 99.9%
- 错误率 < 0.1%
Spec-Kit 不仅仅是一个工具，更是一种开发理念的转变。通过规范驱动开发，我们可以建立更加高效、稳定、可维护的软件开发流程。在 AI 时代，这种规范化的开发方式将成为软件开发的主流趋势。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online