4.5 本章小结
🎯 核心知识点回顾
一句话总结 Spec-kit
Spec-kit 让规格说明书从"计划文档"变成"可执行蓝图"，通过六阶段工作流（Constitution → Specify → Clarify → Plan → Tasks → Implement）将自然语言需求转化为高质量代码。
📚 本章核心内容
4.1 - 本章介绍
核心理念：
- 意图驱动开发：先明确"What"和"Why"，再确定"How"
- 规格即源头：代码从规格生成，而非规格从代码倒推
- 宪法框架：不可协商的原则自动化验证
价值主张：
传统开发：12 小时手工文档 + 代码实现
Spec-kit：15 分钟规格 + AI 自动生成代码
节省时间：~40-60%
减少 bug：规格-实现零漂移
提升质量：宪法自动验证Spec-kit vs Skills vs MCP：
Spec-kit: 开发方法论 + 工作流
Skills: 领域知识库
MCP: 外部系统连接
组合使用 = 完整的 AI 开发堆栈4.2 - 基础概念和结构
六阶段工作流：
阶段 0: Constitution（宪法）[可选但推荐]
↓
阶段 1: Specification（规格说明）
↓
阶段 2: Clarification（澄清）[可选]
↓
阶段 3: Planning（技术方案）
↓
阶段 4: Task Breakdown（任务分解）
↓
阶段 5: Implementation（实现）
↓
阶段 6: Quality Validation（质量验证）[可选]核心文件：
- spec.md: 技术无关的需求描述（What & Why）
- plan.md: 技术方案（How）
- tasks.md: 可执行的任务清单（When）
- constitution.md: 项目宪法（不可协商原则）
关键原则：
- ✅ Spec vs Plan 边界清晰（需求 vs 技术）
- ✅ 任务粒度合适（1-2 小时）
- ✅ Checkpoint 独立验证
- ✅ 绝对路径（避免歧义）
4.3 - 创建你的第一个 Spec
案例 1：个人作品集（10 分钟）
- 技术栈：静态网站（HTML/CSS/JS）
- 重点：体验完整流程
- 学习：基础工作流
案例 2：相册管理器（30 分钟）
- 技术栈：React + TypeScript + IndexedDB
- 重点：澄清流程 + 质量验证
- 学习：用户故事分解、边缘情况处理
案例 3：待办事项 API（60 分钟）
- 技术栈：FastAPI + PostgreSQL
- 重点：契约优先开发
- 学习：OpenAPI、前后端并行、契约测试
递进式学习：
简单 → 中等 → 复杂
静态 → 动态 → 全栈
单人 → 团队 → 企业4.4 - 进阶技巧和最佳实践
宪法框架深度应用：
- Article I: 简洁优先（≤3 依赖）
- Article II: 测试驱动开发（TDD）
- Article III: 契约优先（OpenAPI）
- Article IV: 性能预算（<200ms）
契约优先开发完整流程：
1. 定义 OpenAPI 契约（团队协作）
2. 验证契约合法性
3. 前端使用 Mock 服务器并行开发
4. 后端基于契约实现
5. 契约测试验证一致性
6. 集成零惊喜多技术栈并行探索：
同一个 spec → 3 个 plan → 3 个实现 → 基准测试对比 → 数据驱动决策团队协作模式：
- 规格先行协作（产品 → 技术 → 实现）
- 宪法驱动标准化（自动化验证）
- Git + PR 工作流
CI/CD 集成：
- 自动验证宪法合规性
- 契约测试
- 性能门控
- 自动部署
💡 常见问题 FAQ
Q1: Spec-kit 适合什么样的项目？
适合：
✅ 2+ 天开发周期的功能
✅ 需要文档的项目
✅ 团队协作项目
✅ 技术选型不确定的项目
✅ 企业级应用（需要合规）不适合：
❌ 一次性脚本（< 4 小时）
❌ 快速原型验证
❌ 单文件修改
❌ 探索性编程（需求完全不明确）Q2: 必须创建宪法吗？
答： 不是必须，但强烈推荐。
何时必须创建宪法：
- ✅ 团队协作项目（统一标准）
- ✅ 长期维护项目（防止技术债务）
- ✅ 企业项目（合规要求）
何时可以跳过：
- ❌ 个人学习项目
- ❌ 一次性项目
- ❌ 快速原型
推荐做法：
markdown
即使是个人项目，也可以创建简单宪法：
# Simple Constitution
## Article I: Keep It Simple
- 最多 3 个依赖
- 最多 500 行代码
## Article II: Test First
- 所有功能有测试Q3: Spec 和 Plan 的边界在哪里？
Spec（规格）应该包含：
markdown
✅ 用户故事（用户视角）
✅ 功能需求（系统能做什么）
✅ 成功标准（如何测量）
✅ 边缘情况（异常处理）
❌ 技术选型（React vs Vue）
❌ 数据库设计
❌ API 接口定义Plan（方案）应该包含：
markdown
✅ 技术栈（Python, FastAPI...）
✅ 数据模型（表结构）
✅ API 契约（OpenAPI）
✅ 测试策略
✅ 宪法合规性检查
❌ 用户故事（应在 spec）
❌ 成功标准（应在 spec）记忆口诀：
Spec = What & Why（做什么，为什么）
Plan = How（怎么做）Q4: 如何提高 Spec 的质量？
5 个关键技巧：
1. 用户故事要独立可测试
markdown
❌ 错误："实现用户认证系统"（太大）
✅ 正确：
- P1: 用户注册
- P2: 用户登录
- P3: 密码重置
（每个可独立开发和测试）2. 成功标准要可测量
markdown
❌ 错误："系统要快"
✅ 正确："API 响应时间 < 200ms (P95)"3. 限制澄清标记
markdown
最多 3 个 [NEEDS CLARIFICATION]
超过 3 个 → 需求太模糊，需要更多前期讨论4. 优先级要明确
markdown
P1: Critical（核心功能，必须有）
P2: Important（重要但非核心）
P3: Nice-to-have（锦上添花）5. 边缘情况要完整
markdown
✅ 错误处理（网络失败、超时）
✅ 边界条件（空列表、最大值）
✅ 并发场景（多用户同时操作）Q5: 契约优先开发的核心价值是什么？
核心价值：
1. 前后端并行开发
传统：后端完成 → 前端对接（顺序）
契约：前后端同时开发（并行）
时间节省：40-60%2. 自动生成文档
OpenAPI → Swagger UI / ReDoc（自动）
文档永远最新（因为基于契约生成）3. 契约测试保证一致性
python
def test_contract_compliance():
response = client.post("/api/users", json={...})
validate_response(response, openapi_spec)
# 自动验证实现符合契约4. 类型安全
bash
# 从 OpenAPI 生成 TypeScript 类型
npx openapi-typescript api.yaml -o types.ts
# 编译时发现类型错误完整价值链：
OpenAPI 契约
├→ Mock 服务器（前端开发）
├→ 类型定义（类型安全）
├→ API 文档（自动生成）
├→ 契约测试（自动验证）
└→ SDK 生成（客户端库）Q6: 多技术栈探索什么时候值得？
值得的场景：
✅ 技术选型不确定（创业团队）
✅ 性能要求严格（需要对比）
✅ 团队有不同技术背景
✅ 长期项目（选择影响深远）不值得的场景：
❌ 技术栈已明确
❌ 时间紧迫（无法并行探索）
❌ 团队只熟悉一种技术
❌ 一次性项目ROI 计算：
投入：
- 3 个开发者 × 2 天 = 6 人天
产出：
- 数据驱动的技术选型
- 避免错误选择（可能浪费 数周/数月）
- 团队对技术栈的深入理解
值得：如果项目周期 > 2 周Q7: CI/CD 集成的最小配置是什么？
最小 CI/CD（3 个检查）：
yaml
# .github/workflows/minimal-ci.yml
name: Minimal CI
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
# 1. 宪法合规性
- name: Check constitution
run: |
# 简单检查：依赖数量
deps=$(grep "^dependencies:" plan.md -A 10 | wc -l)
if [ $deps -gt 3 ]; then
echo "❌ Too many dependencies: $deps (limit: 3)"
exit 1
fi
# 2. 测试覆盖率
- name: Run tests
run: |
pytest --cov=src --cov-fail-under=80
# 3. 契约验证（如果有）
- name: Validate contracts
run: |
if [ -f specs/*/contracts/*.yaml ]; then
swagger-cli validate specs/*/contracts/*.yaml
fi扩展（可选）：
- 性能测试（k6）
- 安全扫描（npm audit, safety）
- 代码质量（pylint, eslint）
- 自动部署
Q8: 如何调试 Spec-kit 工作流？
调试技巧：
1. 使用 /speckit.analyze
bash
/speckit.analyze
# 输出：
# ❌ Inconsistency detected:
# - spec.md requires "User can filter by tags"
# - plan.md does not mention tag filtering
# - tasks.md has no tag-related tasks
# 修复：更新 plan 和 tasks2. 检查宪法违规
bash
grep "dependencies:" plan.md -A 10
# 如果超过 3 个，添加复杂度证明：
## Complexity Justification
| Dependency | Reason |
|------------|--------|
| FastAPI | Web framework |
| SQLAlchemy | ORM |
| pytest | Testing |
| Redis | Caching (justified) |3. 契约测试失败
python
# 详细错误信息
from openapi_core.validation.response import openapi_response_validator
result = validator.validate(response)
for error in result.errors:
print(f"❌ {error}")4. 任务卡住
检查：
- 任务是否有明确的文件路径？
- 依赖关系是否正确？
- Checkpoint 是否通过？📋 快速参考指南
工作流速查卡
┌────────────────────────────────────────────────┐
│ SPEC-KIT 工作流速查卡 │
├────────────────────────────────────────────────┤
│ │
│ 1️⃣ Constitution（可选） │
│ /speckit.constitution │
│ → 定义不可协商原则 │
│ │
│ 2️⃣ Specify │
│ /speckit.specify [功能描述] │
│ → 生成 specs/{编号}/spec.md │
│ │
│ 3️⃣ Clarify（可选） │
│ /speckit.clarify │
│ → 解决 [NEEDS CLARIFICATION] 标记 │
│ │
│ 4️⃣ Plan │
│ /speckit.plan [技术栈] │
│ → 生成 specs/{编号}/plan.md │
│ │
│ 5️⃣ Tasks │
│ /speckit.tasks │
│ → 生成 specs/{编号}/tasks.md │
│ │
│ 6️⃣ Implement │
│ /speckit.implement │
│ → 生成代码 │
│ │
│ 7️⃣ Analyze（可选） │
│ /speckit.analyze │
│ → 验证一致性 │
│ │
└────────────────────────────────────────────────┘命令速查表
| 命令 | 用途 | 输入 | 输出 |
|---|---|---|---|
/speckit.constitution | 创建宪法 | 项目原则 | constitution.md |
/speckit.specify [描述] | 创建规格 | 功能描述 | spec.md |
/speckit.clarify | 澄清需求 | spec.md | 更新的 spec.md |
/speckit.plan [技术栈] | 技术方案 | spec.md + 技术选型 | plan.md |
/speckit.tasks | 任务分解 | plan.md | tasks.md |
/speckit.implement | 实现代码 | tasks.md | 源代码 |
/speckit.analyze | 验证一致性 | spec+plan+tasks | 分析报告 |
/speckit.checklist | 质量检查 | spec+plan | checklist.md |
文件模板速查
spec.md 模板：
markdown
# Feature: [名称]
## User Scenarios
### P1: [场景名称]
- Given [前置条件]
- When [操作]
- Then [结果]
## Requirements
- FR-001: MUST [功能]
- FR-002: SHOULD [功能]
## Success Criteria
- SC-001: [可测量指标]plan.md 模板：
markdown
# Implementation Plan
## Technical Context
- Language: [语言]
- Framework: [框架]
- Database: [数据库]
## Constitution Check
✅ Article I: [检查结果]
## Data Model
[数据模型]
## API Contract
[API 定义]tasks.md 模板：
markdown
# Tasks
## Phase 1: Setup
- [ ] T001 Initialize project
## Phase 2: Foundation
- [ ] T005 Create database schema
## Phase 3: User Stories
### US1: [场景]
- [ ] T008 [US1] Implement feature最佳实践清单
Spec 编写：
- [ ] 用户故事独立可测试
- [ ] 成功标准可测量
- [ ] 技术无关（无 React/Vue 等）
- [ ] 澄清标记 ≤ 3 个
- [ ] 优先级明确（P1/P2/P3）
- [ ] 边缘情况完整
Plan 编写：
- [ ] 所有路径绝对路径
- [ ] 宪法合规性检查
- [ ] 复杂度证明（如需）
- [ ] API 契约完整
- [ ] 测试策略明确
Tasks 编写：
- [ ] 任务粒度 1-2 小时
- [ ] 并行任务标记 [P]
- [ ] 依赖关系清晰
- [ ] Checkpoint 独立验证
- [ ] 用户故事关联 [US#]
宪法设计：
- [ ] 不可协商原则明确
- [ ] 验证方法自动化
- [ ] 违规处理流程
- [ ] 版本化管理
🎓 学习成果验证
完成本章后，你应该能够：
基础能力
- [ ] 理解 Spec-kit 的核心理念
- [ ] 掌握六阶段工作流
- [ ] 区分 Spec、Plan、Tasks 的边界
- [ ] 使用 Spec-kit 创建简单项目
进阶能力
- [ ] 创建和维护项目宪法
- [ ] 实践契约优先开发
- [ ] 进行多技术栈并行探索
- [ ] 设计团队协作工作流
专家能力
- [ ] 定制化宪法框架
- [ ] 集成 CI/CD 管道
- [ ] 调试复杂问题
- [ ] 优化开发流程
自测题：
- Spec-kit 的六个阶段是什么？
- Spec 和 Plan 的核心区别是什么？
- 契约优先开发的核心价值是什么？
- 宪法（Constitution）的作用是什么？
- 何时应该进行多技术栈并行探索？
答案见本章内容 😊
📚 扩展资源
官方资源
1. GitHub Spec-kit 仓库 ⭐⭐⭐⭐⭐
- URL: https://github.com/github/spec-kit
- 内容：完整源码、模板、示例
- 推荐：必读，最权威的资料
2. Spec-Driven Development 文档
- 文件: spec-driven.md
- 内容：方法论深度解析
- 推荐：理解理念
3. AGENTS.md
- 内容：15+ AI 工具集成指南
- 推荐：多工具协同
4. 官方博客
- URL: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
- 内容：Spec-kit 发布介绍
社区资源
1. GitHub Discussions
- 问题讨论
- 最佳实践分享
- 案例研究
2. 示例项目
仓库中的示例：
- Mauna Kea Camera Tracker（静态网站）
- Taskify（.NET Aspire 项目管理）
- Specmatic E-commerce（契约优先 API）3. 视频教程
- YouTube 搜索 "Spec-kit tutorial"
- 社区录屏分享
相关工具
OpenAPI 工具链：
- Swagger Editor: https://editor.swagger.io/
- Prism Mock Server: https://github.com/stoplightio/prism
- openapi-generator: https://openapi-generator.tech/
契约测试：
- openapi-core (Python)
- openapi-typescript (TypeScript)
- Specmatic: https://specmatic.io/
性能测试：
- k6: https://k6.io/
- Apache Bench (ab)
- Lighthouse (前端)
🚀 下一步行动
立即行动（今天）
1. 创建你的第一个 Spec-kit 项目
bash
# 10 分钟快速体验
specify init my-first-project --ai claude
cd my-first-project
/speckit.specify 待办事项应用，支持创建、完成、删除任务
/speckit.plan React + FastAPI
/speckit.implement2. 加入社区
⭐ Star GitHub 仓库
💬 加入 Discussions
📢 分享你的第一个项目本周目标
1. 完成 3 个案例
- [ ] 个人作品集（10 分钟）
- [ ] 相册管理器（30 分钟）
- [ ] 待办事项 API（60 分钟）
2. 创建团队宪法
- [ ] 讨论核心原则
- [ ] 编写 constitution.md
- [ ] 在项目中验证
3. 实践契约优先
- [ ] 定义 OpenAPI 契约
- [ ] 前后端并行开发
- [ ] 契约测试验证
本月目标
1. 生产环境项目
- [ ] 选择一个真实项目
- [ ] 完整使用 Spec-kit 工作流
- [ ] 集成 CI/CD
- [ ] 记录经验和教训
2. 团队推广
- [ ] 分享 Spec-kit 给团队
- [ ] 组织内部培训
- [ ] 建立团队最佳实践
3. 深度定制
- [ ] 自定义 Spec 模板
- [ ] 编写自定义验证脚本
- [ ] 优化团队工作流
💬 最后的话
恭喜你完成了 Spec-kit 核心概念的学习！🎉
你已经掌握：
- ✅ Spec-kit 的核心理念和价值
- ✅ 六阶段完整工作流
- ✅ 从简单到复杂的实战案例
- ✅ 宪法、契约、协作等高级技巧
- ✅ 调试、优化和最佳实践
记住核心原则：
Spec（What & Why）先于 Plan（How）
规格是源头，代码是表达
宪法是护栏，AI 是助手Spec-kit 不仅是工具，更是思维方式的转变：
从"我要写什么代码"
↓
到"我想实现什么功能"开始你的 Spec-Driven Development 之旅吧！
🎁 特别福利
模板下载
完整项目模板：
bash
# 克隆官方仓库
git clone https://github.com/github/spec-kit.git
# 使用模板
cp -r spec-kit/.specify/templates/ my-project/.specify/自定义模板集合（本书提供）：
- 个人作品集模板
- 相册管理器模板
- 待办事项 API 模板
- 企业级应用模板
社群支持
加入 Vibe Coding 社群：
- 💬 问题讨论
- 🎯 案例分享
- 📚 资源共享
- 🤝 团队协作
联系方式：
- GitHub Discussions
- Twitter: @VibeCoding
- Email: support@vibecoding.com
📖 继续学习
完成 Module 4 后，推荐继续学习：
Module 2: Skills 核心概念
- 教 Claude 成为领域专家
- 与 Spec-kit 完美互补
Module 3: MCP 深度解析
- 连接外部数据源
- 扩展 Spec-kit 能力
Module 6: 完整工作流集成
- Spec-kit + Skills + MCP 组合
- 企业级实战项目
Keep Spec-Driven, Stay Productive! 🚀
Spec-kit 核心概念教程 v1.0 | 2025 Edition
基于 GitHub Spec-kit 官方仓库 | MIT License