Spec-Kit 完整实践指南
- 一、uv 安装步骤
- 二、Spec-Kit 简介
- 三、Spec-Kit 完整实践流程
- 四、自动化程度总览
- 五、中文项目完整工作流示例
- 六、支持的 AI 助手
- 七、进阶用法
- 八、最佳实践
- 九、故障排除
- 十、总结
- 十一、参考资源
本文档记录 uv 安装过程及 Spec-Driven Development 的完整实践流程
本文首发地址 https://h89.cn/archives/515.html
一、uv 安装步骤
1.1 什么是 uv？
uv 是一个用 Rust 编写的极速 Python 包管理器和环境管理工具，由 Astral 开发。它是 pip 和 venv 的替代品，速度更快、功能更强大。
1.2 Windows 安装方法
方法一：使用 winget（推荐）
winget install --id=astral-sh.uv -e安装完成后，需要重启终端或刷新环境变量：
$env:Path = [Environment]::GetEnvironmentVariable('Path', 'User')方法二：使用 PowerShell 脚本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"验证安装
uv --version
# 输出: uv 0.10.3 (c75a0c625 2026-02-16)1.3 uv 常用命令
uv venv # 创建虚拟环境
uv pip install <package> # 安装包
uv tool install <tool> # 安装工具
uv run script.py # 运行 Python 脚本
uvx <tool> # 一次性运行（无需安装）二、Spec-Kit 简介
2.1 什么是 Spec-Driven Development？
Spec-Driven Development（规格驱动开发）是一种新型软件开发范式：
传统开发：写代码 → 写文档 → 维护两者同步
Spec-Driven：写规格 → 规格生成代码 → 规格即代码
规格（Spec）不再是开发完成后的文档，而是可执行的、直接生成工作实现的核心资产。
2.2 Spec-Kit 核心组件
| 组件 | 文件 | 说明 |
|---|---|---|
| Constitution | CONSTITUTION.md |
项目宪法，定义开发原则和标准 |
| Spec | SPEC.md |
功能规格，描述做什么和为什么 |
| Plan | PLAN.md |
技术计划，描述如何实现 |
| Tasks | TASKS.md |
任务列表，可执行的具体步骤 |
三、Spec-Kit 完整实践流程
步骤 1：安装 Specify CLI
# 持久化安装（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 验证安装
specify checkspecify check 会检查以下工具是否安装：
- git
- claude / gemini / copilot 等 AI 助手
- code / cursor-agent / windsurf 等 IDE
步骤 2：初始化项目
# 创建新项目目录
specify init my-project
# 或在当前目录初始化
specify init . --ai claude
# 指定脚本类型（Windows 使用 PowerShell）
specify init . --ai claude --script ps初始化后会生成：
AGENTS.md- AI 助手使用指南CONSTITUTION.md- 项目宪法（如不存在）
步骤 3：创建项目宪法（Constitution）
自动化程度：⭐⭐⭐⭐ 半自动 - 你描述原则方向，AI 负责扩展和完善
使用 /speckit.constitution 命令创建项目原则：
/speckit.constitution 创建项目原则：
语言规范：
- 所有项目文档、注释、提交信息必须使用简体中文
- 代码变量名和函数名使用英文，但注释使用中文
- 用户界面文本使用简体中文
- 错误提示和日志信息使用中文
代码质量：
- 遵循 Clean Code 原则
- 单元测试覆盖率 > 80%
- 使用 SOLID 原则
性能要求：
- 页面加载时间 < 2秒
- 接口响应时间 < 500ms
安全规范：
- 遵循 OWASP Top 10 安全标准
- 禁止在代码中硬编码密钥和密码这会生成 CONSTITUTION.md，AI 在后续生成所有内容时，都会遵循这个"宪法"规定，自动使用中文。
步骤 4：编写功能规格（Specify）
自动化程度：⭐⭐⭐⭐⭐ 全自动 - 你只需描述"做什么"，AI 自动生成完整规格
使用 /speckit.specify 描述功能需求：
/speckit.specify 构建一个照片相册管理应用：
核心功能：
1. 相册管理
- 按日期分组创建相册
- 支持拖放重新排序
- 不允许嵌套相册（扁平结构）
2. 照片展示
- 瓷砖式界面预览照片
- 懒加载提升性能
- 支持 JPEG、PNG、WebP 格式
3. 数据存储
- 图片本地存储（不上传云端）
- 元数据存储在本地 SQLite 数据库
- 支持导出/导入相册数据
用户故事：
- 作为用户，我想拖动相册来重新排序
- 作为用户，我想在网格布局中查看照片
- 作为用户，我想让数据保持私密（仅本地）这会生成 SPEC.md，包含功能描述、用户故事、验收标准、非功能需求。
步骤 5：需求澄清（Clarify）
自动化程度：⭐⭐⭐⭐⭐ 全自动 - AI 主动提问帮你澄清模糊想法
/speckit.clarifyAI 会自动分析 SPEC.md，主动向你提问，帮你澄清模糊想法。例如：
- 是否需要支持方言？
- 离线模式是否必需？
- 响应时间要求是多少？
步骤 6：制定技术计划（Plan）
自动化程度：⭐⭐⭐⭐⭐ 全自动 - 你只需说"用什么技术"，AI 自动设计架构
使用 /speckit.plan 提供技术实现细节：
/speckit.plan 技术实现方案：
前端：
- 构建工具：Vite 5.x
- 语言：原生 HTML5、CSS3、ES2023 JavaScript
- UI 框架：无（保持轻量）
- 拖放功能：原生 HTML5 Drag and Drop API
- 状态管理：原生 JS 发布/订阅模式
后端/数据：
- 数据库：SQLite（浏览器端使用 sql.js）
- 存储：IndexedDB 存储二进制图片数据
- 文件处理：Native File System Access API
性能优化：
- 图片懒加载（Intersection Observer）
- 大型相册虚拟滚动
- 缩略图（200x200）+ 按需加载原图
约束条件：
- 零外部运行时依赖
- 支持离线工作（PWA）
- 移动端响应式适配这会生成 PLAN.md，包含技术栈选择、架构设计、数据模型、API 接口定义。
步骤 7：分解任务（Tasks）
自动化程度：⭐⭐⭐⭐⭐ 全自动 - 将规格转化为可执行任务
/speckit.tasks这会分析 SPEC.md 和 PLAN.md，自动生成 TASKS.md：
# 实现任务列表
## 阶段一：项目搭建
- [ ] 初始化 Vite 项目
- [ ] 设置目录结构（src/、assets/、db/）
- [ ] 配置构建和开发脚本
## 阶段二：数据库层
- [ ] 设计 SQLite 表结构（albums、photos 表）
- [ ] 实现 sql.js 封装
- [ ] 创建 CRUD 操作
## 阶段三：UI 组件
- [ ] 创建相册组件
- [ ] 创建照片网格组件
- [ ] 实现拖放逻辑
## 阶段四：功能实现
- [ ] 相册增删改查操作
- [ ] 照片上传和展示
- [ ] 拖放重新排序
- [ ] 数据导出/导入
## 阶段五：完善优化
- [ ] 添加 CSS 样式
- [ ] 实现懒加载
- [ ] 添加错误处理
- [ ] 编写测试用例步骤 8：执行实现（Implement）
自动化程度：⭐⭐⭐⭐⭐ 全自动 - 从需求到代码的最终落地
/speckit.implementAI 助手会：
- 读取
TASKS.md - 按顺序执行每个任务
- 生成代码文件
- 更新任务状态
四、自动化程度总览
| 命令 | 自动化程度 | 输入 | 输出 |
|---|---|---|---|
/speckit.constitution |
⭐⭐⭐⭐ | 原则方向 | CONSTITUTION.md |
/speckit.specify |
⭐⭐⭐⭐⭐ | 需求描述 | SPEC.md |
/speckit.clarify |
⭐⭐⭐⭐⭐ | 无需输入 | 澄清问题 |
/speckit.plan |
⭐⭐⭐⭐⭐ | 技术偏好 | PLAN.md |
/speckit.tasks |
⭐⭐⭐⭐⭐ | 无需输入 | TASKS.md |
/speckit.implement |
⭐⭐⭐⭐⭐ | 无需输入 | 代码文件 |
五、中文项目完整工作流示例
以下是一个智能座舱语音控制系统的完整工作流：
# 步骤1：初始化项目
specify init my-project --ai claude
# 步骤2：创建中文宪法（关键！）
/speckit.constitution
创建项目原则：
- 所有文档、注释、提交信息使用简体中文
- 代码命名遵循英文规范
- 测试覆盖率要求 80% 以上
- 遵循 Clean Code 原则
# 步骤3：描述需求（用中文）
/speckit.specify
构建一个智能座舱语音控制系统：
- 支持语音识别和语音合成
- 可控制空调、车窗、导航等功能
- 支持多轮对话和上下文理解
- 离线模式支持
# 步骤4：澄清需求（AI 自动提问）
/speckit.clarify
# 步骤5：技术方案（自动生成）
/speckit.plan
使用 Android 原生开发，Kotlin 语言，MVVM 架构
# 步骤6：任务分解（全自动）
/speckit.tasks
# 步骤7：自动实现
/speckit.implement六、支持的 AI 助手
| AI 助手 | 支持状态 | 备注 |
|---|---|---|
| Claude Code | ✅ | 完全支持 |
| GitHub Copilot | ✅ | 完全支持 |
| Cursor | ✅ | 完全支持 |
| Gemini CLI | ✅ | 完全支持 |
| Windsurf | ✅ | 完全支持 |
| Amazon Q | ⚠️ | 不支持自定义参数 |
| Codex CLI | ✅ | 完全支持 |
| Roo Code | ✅ | 完全支持 |
七、进阶用法
7.1 增量开发
# 只执行特定阶段的任务
/speckit.implement --phase 2
# 执行单个任务
/speckit.implement --task "创建相册组件"7.2 更新规格
# 修改 SPEC.md 后重新生成任务
/speckit.tasks --update
# 修改 PLAN.md 后重新生成任务
/speckit.plan --update7.3 代码审查
# 根据 Constitution 审查代码
/speckit.review
# 检查测试覆盖率
/speckit.test --coverage八、最佳实践
8.1 Constitution 编写建议
- 具体可衡量：不说"代码要好"，而说"单元测试覆盖率 > 80%"
- 技术无关：关注原则而非具体技术
- 团队共识：与团队一起制定
8.2 Spec 编写建议
- 用户视角：描述用户能看到什么、能做什么
- 避免技术细节：不在 Spec 中指定"使用 React"或"用 Redis"
- 验收标准：每个功能都要有明确的完成标准
8.3 Plan 编写建议
- 技术选型：说明为什么选择某技术
- 架构图：用文字或 ASCII 图描述架构
- 数据流：描述数据如何在系统中流动
九、故障排除
9.1 安装问题
问题：uv tool install 失败
解决：
# 强制重新安装
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
# 或使用 uvx 临时运行
uvx --from git+https://github.com/github/spec-kit.git specify init my-project9.2 AI 助手不响应
问题：/speckit.specify 命令无响应
解决：
- 检查
AGENTS.md是否正确配置 - 确认 AI 助手支持 slash 命令
- 尝试完整路径命令：
/speckit.specify --verbose
十、总结
Spec-Driven Development 的核心价值：
- 规格即代码：规格不再是文档，而是可执行的资产
- AI 原生：专为 AI 助手设计，充分发挥 AI 能力
- 可追溯：从需求到实现的完整链路
- 可维护：修改规格即可更新实现
通过 Spec-Kit，你可以：
- 用自然语言描述需求
- 让 AI 自动生成实现
- 保持代码与需求同步
- 提高开发效率和代码质量
十一、参考资源
本文链接：Spec-Kit 完整实践指南 - https://h89.cn/archives/515.html
版权声明：原创文章 遵循 CC 4.0 BY-SA 版权协议，转载请附上原文链接和本声明。