GitHub Spec-Kit 上手与规范驱动开发实践

配置开发环境

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 选择

建议用支持 AI 的编辑器：

• 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/ 下会生成类似这样的结构：

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
);

#### 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": {
                      "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"}
        }
      }
    }
  }
}

拆任务

speckit.tasks

生成的 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
- **依赖**：无
- **验收标准**：前端项目可以正常启动

开始实施

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

放到真实项目里怎么用

这里拿'订单评价功能'做个例子。这个场景很典型：需求不算复杂，但如果没有规范，接口、表结构、页面状态很容易各写各的。

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 补代码更稳。省下来的不是敲键盘的时间，而是返工和扯皮的时间。

常见用法里的几个坑

• 需求描述太泛，生成结果就会很空
• 技术栈没写死，后面容易偏离现有项目
• 只看生成代码，不看规范和任务文件
• 任务拆得太碎，反而增加维护成本

参考资料

• GitHub Spec-Kit 官方仓库
• 规范驱动开发最佳实践
• AI 辅助开发指南
• 项目模板和示例