Spec Kit 设计哲学：规范驱动开发的深度解析

一、核心洞察：权力倒置

传统范式的困境

几十年来，软件开发遵循一个隐含假设：代码是王。

传统流程：
需求文档 → 设计文档 → 代码 → 测试 → 文档腐烂
    ↓           ↓        ↑
  (参考)      (指导)   (真相)
    

规范服务于代码——它们是搭建后即丢弃的脚手架。我们写 PRD 来指导开发，画架构图来说明设计，但这些都从属于代码本身。代码是真相，其他一切充其量是"良好意愿"。随着代码演进，规范很少能跟上步伐。

Spec Kit 的颠覆

Spec Kit 彻底颠覆这一范式：规范是王，代码服务于规范。

SDD 流程：
规范(Spec) → 计划(Plan) → 任务(Tasks) → 代码
    ↑__________________________________|
              生产反馈闭环
    

这不是渐进式改良，而是对"什么驱动开发"的根本性重构。当规范直接生成代码时，意图与实现之间的鸿沟不复存在——只有转换。

二、与敏捷开发的概念对比

2.1 核心概念映射

2.2 关键差异

Sprint 1:
  - Story A (5 points) → Alice
  - Story B (3 points) → Bob
  - Story C (8 points) → Team
        

specs/001-user-auth/
├── spec.md        # WHAT: 用户需要什么
├── plan.md        # HOW: 技术如何实现
├── tasks.md       # SEQUENCE: 执行顺序和依赖
└── contracts/     # INTERFACE: API 契约定义
        

三、与 Jira Issue 的深度对比

3.1 本质定位

3.2 信息结构对比

Jira Issue 结构：

Issue: AUTH-123
Type: Story
Summary: "用户可以通过邮箱登录"
Description: "作为用户，我希望..."
Status: In Progress
Assignee: Alice
Sprint: Sprint 5
Story Points: 5
Labels: [auth, mvp]
Comments: [讨论历史...]
    

Spec Kit spec.md 结构：

# Feature: User Authentication

## User Story 1 - Email Login (P1)
**Why this priority**: 核心功能，阻塞其他所有功能
**Independent Test**: 可通过登录流程独立验证

**Acceptance Scenarios**:
1. Given 有效邮箱和密码
   When 用户提交登录表单
   Then 返回 JWT token 并跳转到首页

2. Given 无效密码
   When 用户提交登录表单
   Then 显示错误信息，不泄露用户是否存在

## Functional Requirements
- FR-001: 系统必须支持邮箱+密码认证
- FR-002: 密码必须使用 bcrypt 哈希存储
- FR-003: 登录失败 5 次后锁定账户 15 分钟

## Success Criteria
- SC-001: 用户可在 3 秒内完成登录流程
- SC-002: 系统支持 1000 并发登录请求
    

3.3 为什么不能用 Jira 替代 Spec Kit？

Jira 的局限性：

1. 信息碎片化 - 需求分散在多个 Issue 中，AI 无法获得完整上下文
2. 缺乏技术深度 - 没有数据模型、API 契约、技术决策的标准位置
3. 无执行顺序 - Issue 之间的依赖关系是弱链接，不是强约束
4. 非版本化 - Issue 状态变化不与代码版本绑定

Spec Kit 的优势：

1. 信息聚合 - 一个目录包含功能的完整上下文
2. 技术完备 - 从需求到 API 契约到任务分解，层层递进
3. 强依赖图 - tasks.md 明确定义执行顺序和并行机会
4. Git 原生 - 规范与代码在同一仓库，同步版本化

3.4 互补使用模式

Spec Kit (设计时)              Jira (执行时)
─────────────────              ────────────
spec.md ──────────────────────→ Epic
  └── User Story 1 ───────────→ Story
  └── User Story 2 ───────────→ Story
tasks.md ─────────────────────→ Sub-tasks
  └── T001 Setup ─────────────→ Sub-task (Alice)
  └── T002 Model ─────────────→ Sub-task (Bob)

/speckit.taskstoissues 命令可自动同步到 GitHub Issues
    

四、Spec Kit 的独特概念

4.1 Constitution（宪法）

敏捷/Jira 中没有对应概念。

Constitution 是项目的"架构 DNA"——一组不可变原则，确保每次生成的代码都遵循相同的架构哲学：

# Project Constitution

## I. Library-First
每个功能必须先是独立库，不允许直接在应用代码中实现

## II. CLI Interface
所有库必须通过 CLI 暴露功能，文本输入/输出

## III. Test-First (NON-NEGOTIABLE)
没有测试就没有代码，红-绿-重构严格执行

## VII. Simplicity
最多 3 个项目，复杂度必须被证明而非假设
    

为什么需要 Constitution？

• 确保不同时间、不同 AI 模型生成的代码架构一致
• 防止过度工程化（每个复杂度都需要在 Complexity Tracking 中证明）
• 作为 Plan 阶段的"编译时检查"

4.2 Checklist 作为"需求的单元测试"

传统 Checklist： 验证实现是否正确

- [ ] 验证登录按钮可点击
- [ ] 测试错误提示显示正确
- [ ] 确认跳转到首页
    

Spec Kit Checklist： 验证需求是否写得正确

- [ ] 登录失败的错误信息是否明确定义？[Completeness, Gap]
- [ ] "快速登录"是否量化为具体时间指标？[Clarity, Spec §NFR-1]
- [ ] 移动端和桌面端的登录流程是否一致？[Consistency]
- [ ] 是否定义了账户锁定后的解锁流程？[Coverage, Edge Case]
    

核心区别：

• 传统：测试系统是否工作
• Spec Kit：测试需求是否写清楚

4.3 Tasks 的并行标记 [P]

Jira 的依赖： 弱链接，主要用于甘特图展示

AUTH-124 blocks AUTH-125
AUTH-126 is blocked by AUTH-124
    

Spec Kit 的依赖： 强约束，直接影响执行顺序

## Phase 2: Foundational (BLOCKS all user stories)
- [ ] T004 Setup database schema
- [ ] T005 [P] Implement auth framework    # 可与 T006 并行
- [ ] T006 [P] Setup API routing           # 可与 T005 并行
- [ ] T007 Create base models (depends on T004)

## Phase 3: User Story 1
- [ ] T010 [P] [US1] Create User model     # 可与 T011 并行
- [ ] T011 [P] [US1] Create Session model  # 可与 T010 并行
- [ ] T012 [US1] Implement AuthService (depends on T010, T011)
    

[P] 标记的含义：

• 不同文件，无依赖
• AI 可以同时生成这些任务的代码
• 人类团队可以分配给不同成员并行开发

五、工作流对比

5.1 敏捷 Sprint 流程

Sprint Planning → Daily Standup → Development → Review → Retro
     (会议)         (会议)         (编码)      (会议)   (会议)
    

特点： 以会议为节点，人工协调，代码是产出物

5.2 Spec Kit SDD 流程

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
    (生成规范)      (生成计划)      (生成任务)       (生成代码)
        ↓               ↓               ↓               ↓
    spec.md         plan.md         tasks.md        src/*.py
                    research.md
                    data-model.md
                    contracts/
    

特点： 以命令为节点，自动生成，规范是产出物（代码是规范的表达）

5.3 时间对比

六、Bug 处理的哲学差异

6.1 传统方式

Bug 发现 → 创建 Issue → 分配 → 修复 → 关闭
              ↓
         (与原需求脱节)
    

Bug 修复往往是"打补丁"，不更新原始需求文档。

6.2 Spec Kit 方式

Bug 发现 → 更新 Spec → 重新生成 Plan → 重新生成 Tasks → 重新生成代码
              ↓
         (规范演进)
    

"Production metrics and incidents don't just trigger hotfixes—they update specifications for the next regeneration."

Bug 不是独立事件，而是规范不完整的信号。修复 Bug 意味着完善规范。

6.3 当前局限

Spec Kit 目前没有专门的 Bug 处理模板，这是一个设计上的空白：

• 没有根因分析模板
• 没有轻量级 hotfix 流程
• 没有 Bug 与 Spec 的关联追踪

这反映了 SDD 的理想主义：所有问题都应该回归到规范层面解决。实际项目中可能需要补充轻量级的 Bug 处理流程。

七、为什么是现在？

三股力量的交汇使 Spec Kit 成为可能：

7.1 AI 能力跨越阈值

自然语言规范可以可靠地生成工作代码。这不是替代开发者，而是放大开发者的效能——自动化从规范到实现的机械翻译。

7.2 软件复杂度指数增长

现代系统集成数十个服务、框架和依赖。通过手动流程保持所有部分与原始意图对齐越来越困难。SDD 通过规范驱动生成提供系统性对齐。

7.3 变化成为常态

需求变更不再是例外，而是日常。传统开发将变更视为干扰——每次转向都需要手动传播变更到文档、设计和代码。SDD 将需求变更从障碍转变为正常工作流：改变规范中的核心需求，受影响的实现计划自动更新。

八、一句话总结

这套方法论将开发者从"代码的维护者"转变为"规范的策展人"，将创造力聚焦于定义"做什么"和"为什么"，而非"怎么做"的机械劳动。

附录：概念速查表