Spec Coding: Spec-Kit + Cursor 实践指南

第一部分：引言和概述

---

1.1 什么是 Spec Coding？

传统开发的痛点

在传统的软件开发流程中，我们经常遇到以下问题：

1. 需求文档和代码脱节

产品经理写了一份 50 页的需求文档，开发团队按照理解开始编码。三个月后交付时，产品经理说：“这不是我要的功能。” 开发团队翻出需求文档：“但你文档里就是这么写的啊！” 争论的焦点往往是：文档已经过时了，没人维护。

案例：

需求文档 (2024-01-10): 
  "用户可以删除待办事项"

实际代码 (2024-03-15):
  - 软删除 + 30天恢复期
  - 垃圾箱功能
  - 批量删除
  
问题：需求文档没有更新，新人看文档完全不知道有这些功能

2. 需求变更成本高

客户突然说：“我们需要支持团队协作功能。” 这个简单的需求变更，可能需要：

• 重新设计数据库（增加团队表、权限表）
• 修改所有 API（增加权限验证）
• 调整前端界面（增加分享按钮）
• 更新测试用例（覆盖新场景）

如果没有清晰的规范，影响范围分析需要数天，实施可能需要数周。

3. 团队沟通效率低

前端工程师：“这个字段叫 createTime 还是 createdAt？“
后端工程师：“我也不知道，问产品吧。“
产品经理：“这个重要吗？随便啦。“
测试工程师：“那我按哪个写测试用例？”

缺少统一的真实来源（Single Source of Truth），团队沟通成本指数级增长。

4. 代码缺乏可追溯性

看到一段奇怪的代码：

if (status == 3 && userId != null && deleted == false && version > 2) {
    // 为什么有这个判断？
}

没人知道为什么要这么写，Git 历史只显示 “fix bug”，需求文档里也找不到相关描述。这段代码成了 “祖传代码”，没人敢动。

---

Spec Coding 的定义

Spec Coding，全称 Specification-Driven Coding（规范驱动编码），是一种现代化的软件开发方法论。它强调：

核心定义：

以详细的、可执行的、版本控制的规范文档作为开发的单一真实来源，通过规范驱动架构设计、任务分解、代码实现和测试验证的完整开发流程。

关键特征：

1. 规范优先（Specification First）

   • 代码之前，先写规范
   • 规范必须详细到可以直接生成代码框架
   • 规范包含：功能需求、非功能需求、验收标准、边界条件

2. 单一真实来源（Single Source of Truth）

   • 规范即文档，文档即规范
   • 所有决策、变更都反映在规范中
   • 代码、测试、文档都从规范派生

3. 完整的开发链路

   需求收集 → 编写规范 → 澄清歧义 → 设计架构 → 
   生成任务 → 一致性验证 → 代码实现 → 测试验证

4. AI 辅助增强

   • AI 根据规范生成代码框架
   • AI 辅助验证规范一致性
   • AI 提供最佳实践建议

---

核心理念

理念 1：先写规范，再写代码

传统开发：

产品需求 → 技术方案 → 直接编码 → 写文档（可能不会写）

Spec Coding：

产品需求 → 详细规范 → 评审锁定 → 架构设计 → 
任务分解 → 代码实现 → 持续更新规范

理念 2：规范即文档，文档即规范

不再维护两套系统（需求文档 + 代码注释），规范就是唯一的文档。

示例：

## FR-001: 创建待办事项

**MUST**: 系统必须允许已认证用户创建新的待办事项

**验收标准**:
- GIVEN 用户已登录
  WHEN 用户提交包含 title、description 的创建请求
  THEN 系统在 100ms 内返回成功响应，包含新创建的 Todo ID

**边界条件**:
- title 不能为空，最大 200 字符
- description 可选，最大 2000 字符
- status 默认为 "PENDING"

这个规范可以：

• 产品用来验收功能
• 开发用来编写代码
• 测试用来编写测试用例
• AI 用来生成代码框架

理念 3：自动化工作流

通过工具链（Spec-Kit + Cursor）自动化：

• 规范生成
• 架构设计
• 任务分解
• 代码框架生成
• 一致性验证

理念 4：AI 辅助开发

AI 不是替代开发者，而是增强开发者：

• AI 生成 80% 的基础代码
• 开发者专注于 20% 的核心逻辑
• AI 辅助验证和优化

---

1.2 为什么需要 Spec Coding？

提高开发效率

数据支持：

• 需求理解偏差减少 60%（明确的验收标准）
• 代码生成速度提升 3-5 倍（AI 辅助）
• 测试用例编写自动化 70%（基于规范生成）

真实案例：

某团队开发一个待办事项管理系统：

阶段	传统开发	Spec Coding	节省时间
需求分析	5 天	3 天	40%
架构设计	3 天	1 天	67%
代码实现	15 天	8 天	47%
测试用例	5 天	2 天	60%
总计	28 天	14 天	50%

---

改善代码质量

1. 强制规范先行

代码质量问题的根源往往是需求不清晰。Spec Coding 强制在编码前澄清所有问题。

对比：

传统开发中的代码：

public void deleteTodo(Long id) {
    todoRepository.deleteById(id);  // 硬删除？软删除？需要权限吗？
}

Spec Coding 指导下的代码：

/**
 * FR-008: 软删除待办事项
 * - 仅所有者可删除
 * - 软删除，设置 deletedAt
 * - 30 天后物理删除
 */
public void deleteTodo(Long id, Long userId) {
    Todo todo = getTodoOrThrow(id);
    
    // 权限验证（规范要求）
    if (!todo.getUserId().equals(userId)) {
        throw new ForbiddenException("无权删除他人的待办事项");
    }
    
    // 软删除（规范要求）
    todo.setDeletedAt(Instant.now());
    todoRepository.save(todo);
    
    // 审计日志（规范要求）
    auditService.log("TODO_DELETED", id, userId);
}

2. 测试驱动设计

规范中的验收标准直接转换为测试用例：

@Test
public void testDeleteTodo_AsOwner_ShouldSoftDelete() {
    // GIVEN 用户已登录且拥有待办事项
    Long userId = 1L;
    Todo todo = createTodo(userId, "Test Todo");
    
    // WHEN 用户删除自己的待办事项
    todoService.deleteTodo(todo.getId(), userId);
    
    // THEN 
    // 1. 待办事项被软删除（规范 FR-008）
    assertNotNull(todo.getDeletedAt());
    // 2. 审计日志已记录（规范 FR-014）
    verify(auditService).log("TODO_DELETED", todo.getId(), userId);
}

3. 完整的验收标准

每个功能都有明确的 Given-When-Then 场景，测试覆盖率自然提升。

数据：

• 规范覆盖的功能：测试覆盖率 ≥ 85%
• 无规范的功能：测试覆盖率 < 50%

---

增强团队协作

1. 规范作为沟通语言

所有角色都基于同一份规范工作：

角色	如何使用规范
产品经理	验证功能是否符合业务需求
架构师	设计技术方案满足规范要求
开发工程师	按规范实现功能和编写代码
测试工程师	基于验收标准编写测试用例
运维工程师	根据非功能需求配置环境

2. 明确的责任划分

规范中定义了每个功能的优先级和验收标准：

## US-001: 创建待办事项 [P1 - 必须实现]

**责任人**: @backend-team
**依赖**: US-000 (用户认证)
**验收标准**: 5 个 Given-When-Then 场景全部通过
**预计工时**: 6 小时

3. 可追溯的决策历史

所有决策都记录在规范的版本历史中：

commit 3a8f2e1
Author: Product Manager
Date: 2024-11-10

feat(spec): 添加团队协作功能

- 新增 FR-015: 分享待办事项
- 新增 FR-016: 团队权限管理
- 影响范围: 需要重构权限模块
- 讨论记录: https://github.com/team/issues/42

---

适应变化需求

1. 规范版本控制

使用 Git 管理规范，每次变更都有记录：

git log features/todo-management/spec.md

v1.0.0 - MVP 版本（单用户）
v1.1.0 - 新增搜索功能
v2.0.0 - 新增团队协作（重大变更）

2. 影响范围分析

当需求变更时，工具可以自动分析影响：

$ specify analyze-impact --change="新增团队协作"

影响分析报告:
✗ 数据模型: 需要新增 Team、TeamMember 表
✗ API: 8 个端点需要增加权限验证
✗ 业务逻辑: TodoService 需要重构
✗ 测试用例: 需要新增 32 个测试场景
✗ 工时估算: 约 80 小时

建议: 在 Phase 2 实现，不影响 MVP 发布

3. 快速迭代能力

有了清晰的规范，迭代速度显著提升：

迭代周期	传统开发	Spec Coding
需求变更确认	3 天	0.5 天
影响范围分析	2 天	0.5 天
代码实现	10 天	5 天
测试验证	3 天	2 天
总计	18 天	8 天

---

1.3 文章结构概览

本文将通过一个完整的实战案例——待办事项管理系统，带你体验 Spec Coding 的全流程。

学习路径

第一部分：引言（当前）
    ↓
第二部分：工具链准备（Spec-Kit + Cursor）
    ↓
第三部分：项目初始化（创建项目宪法）
    ↓
第四部分：核心流程（规范 → 计划 → 任务 → 代码）
    ↓
第五部分：最佳实践（真实经验分享）
    ↓
第六部分：问题解决（常见坑和解决方案）
    ↓
第七部分：案例扩展（其他项目类型）
    ↓
第八部分：总结展望（未来趋势）

你将学到

✅ 理论知识

• Spec Coding 的核心理念
• 规范驱动开发的优势
• 与传统开发的对比

✅ 实战技能

• 如何安装和配置工具链
• 如何编写高质量的规范
• 如何使用 AI 辅助开发
• 如何生成代码框架

✅ 最佳实践

• 规范编写技巧
• 团队协作模式
• 问题排查方法
• 持续改进策略

✅ 完整案例

• 待办事项管理系统（5,975+ 行文档）
• 电商系统对比（高复杂度场景）
• 可直接运行的代码框架

预期成果

学完本文后，你将能够：

1. 独立使用 Spec-Kit + Cursor 开展规范驱动开发
2. 编写高质量规范文档，包含详细的验收标准
3. 使用 AI 生成代码框架，节省 50% 开发时间
4. 建立团队工作流，提升协作效率
5. 持续改进流程，适应团队和项目特点

---

阅读建议

如果你是：

开发工程师

• 重点阅读：第四部分（核心流程）、第五部分（最佳实践）
• 可以跳过：第三部分的详细安装步骤（如已配置环境）

架构师

• 重点阅读：第四部分的架构设计、第七部分的案例对比
• 关注：技术栈选择、架构模式、扩展性设计

产品经理

• 重点阅读：第四部分的规范编写、第五部分的需求管理
• 关注：如何编写可测试的需求、如何进行影响分析

技术经理

• 重点阅读：第五部分的团队协作、第八部分的总结展望
• 关注：团队效率提升、工作流优化、ROI 分析

初学者

• 建议按顺序完整阅读
• 动手实践每个步骤
• 参考附录的扩展资源

---

示例项目信息

项目名称: 待办事项管理系统（Todo Management System）

技术栈:

• 后端: Spring Boot 3.2 + Java 17
• 数据库: H2 (开发) / PostgreSQL (生产)
• 持久化: Spring Data JPA
• 安全: Spring Security + JWT
• API: RESTful 设计

文档规模:

• 功能规范: 501 行
• 澄清文档: 929 行
• 架构计划: 1,510 行
• 任务列表: 981 行
• 分析报告: 855 行
• 实施指南: 826 行
• 总计: 5,602 行完整规范

核心功能:

• ✅ CRUD 操作（创建、查看、更新、删除）
• ✅ 搜索和筛选（按状态、关键词）
• ✅ 分页和排序
• ✅ 用户隔离（权限控制）
• ✅ 软删除和恢复
• ✅ 审计日志
• ✅ 导出功能

完整度:

• 需求覆盖: 100%
• 测试覆盖: 85%+
• 文档完整度: 97.6%（优秀）

---

准备好了吗？

在接下来的章节中，我们将深入每个环节，用真实的命令、完整的输出、详细的解释，带你走完整个流程。

记住 Spec Coding 的核心原则:

先想清楚要做什么（规范），再想清楚怎么做（架构），最后才动手写代码（实现）。

让我们开始这段旅程！

---

第一部分完
下一部分: 工具链介绍 - Spec-Kit 和 Cursor 的安装与配置