Spec-Kit：规格驱动开发工具包

什么是 Spec-Kit？

项目地址：https://github.com/github/spec-kit

Toolkit to help you get started with Spec-Driven Development

Spec-Kit 是 GitHub 官方开源的一个强大工具包，专门用于实现规格驱动开发（Spec-Driven Development，SDD）。它将 AI 编码助手与结构化开发流程深度融合，帮助开发者和团队以更加系统化、规范化的方式进行产品和技术开发。

核心理念

Spec-Kit 通过「规范先行」的理念，将传统的需求文档、产品规范与代码实现有机统一，形成一个完整的开发生态链：

go 复制代码

需求定义 → 规格说明 → 技术方案 → 任务分解 → 代码实现

Spec-Kit 工作流程

Spec-Kit 将复杂的开发过程分解为 5 个清晰的阶段：

阶段	命令	描述
制定规矩	`/speckit.constitution`	建立项目基本原则和约束条件
明确需求	`/speckit.specify`	创建详细的功能规格说明
制定技术方案	`/speckit.plan`	设计技术架构和实现方案
列任务清单	`/speckit.tasks`	生成可执行的开发任务列表
开始编码	`/speckit.implement`	基于规范自动化执行开发任务

快速开始

安装 Spec-Kit

go 复制代码

# 使用 uv 安装 specify-cli
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 如果安装较慢，可以使用国内镜像源
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
  -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com

环境配置

在使用前需要配置 GitHub Token 以访问 GitHub API：

获取 GitHub Token：访问 GitHub Settings > Tokens 创建个人访问令牌
设置环境变量：

go 复制代码

export GITHUB_TOKEN=your_github_token_here

常见问题 ：如果遇到 GitHub API returned 401 错误，请检查 Token 是否正确设置。详见 Issue #378

项目初始化

go 复制代码

# 初始化新项目
specify init <PROJECT_NAME>

# 检查环境配置
specify check

实战案例：开发 Python 代码执行器

项目需求

为 Obsidian 笔记软件开发一个 Python 代码执行器组件，支持：

读取并执行笔记中的 Python 代码块
支持全局 Python 环境配置
支持代码块级别的环境指定（env=xx）
基于通用组件框架开发

开发流程演示

1. 项目初始化

go 复制代码

(base) zhongxin@zhongxindeMacBook-Pro myproject % specify init components_developer
              ███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗              
              ██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝              
              ███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝               
              ╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝                
              ███████║██║     ███████╗╚██████╗██║██║        ██║                 
              ╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝                 

               GitHub Spec Kit - Spec-Driven Development Toolkit                

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  Specify Project Setup                                                       │
│                                                                              │
│  Project         components_developer                                        │
│  Working Path    /Users/zhongxin/myproject                                   │
│  Target Path     /Users/zhongxin/myproject/components_developer              │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯


Selected AI assistant: qwen
Selected script type: sh
Initialize Specify Project
├── ● Check required tools (ok)
├── ● Select AI assistant (qwen)
├── ● Select script type (sh)
├── ● Fetch latest release (release v0.0.62 (51,409 bytes))
├── ● Download template (spec-kit-template-qwen-sh-v0.0.62.zip)
├── ● Extract template
├── ● Archive contents (26 entries)
├── ● Extraction summary (2 top-level items)
├── ● Ensure scripts executable (5 updated)
├── ● Cleanup
├── ● Initialize git repository (initialized)
└── ● Finalize (project ready)

Project ready.

╭─────────────────────────── Agent Folder Security ────────────────────────────╮
│                                                                              │
│  Some agents may store credentials, auth tokens, or other identifying and    │
│  private artifacts in the agent folder within your project.                  │
│  Consider adding .qwen/ (or parts of it) to .gitignore to prevent            │
│  accidental credential leakage.                                              │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭───────────────────────────────── Next Steps ─────────────────────────────────╮
│                                                                              │
│  1. Go to the project folder: cd components_developer                        │
│  2. Start using slash commands with your AI agent:                           │
│     2.1 /speckit.constitution - Establish project principles                 │
│     2.2 /speckit.specify - Create baseline specification                     │
│     2.3 /speckit.plan - Create implementation plan                           │
│     2.4 /speckit.tasks - Generate actionable tasks                           │
│     2.5 /speckit.implement - Execute implementation                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭──────────────────────────── Enhancement Commands ────────────────────────────╮
│                                                                              │
│  Optional commands that you can use for your specs (improve quality &        │
│  confidence)                                                                 │
│                                                                              │
│  ○ /speckit.clarify (optional) - Ask structured questions to de-risk         │
│  ambiguous areas before planning (run before /speckit.plan if used)          │
│  ○ /speckit.analyze (optional) - Cross-artifact consistency & alignment      │
│  report (after /speckit.tasks, before /speckit.implement)                    │
│  ○ /speckit.checklist (optional) - Generate quality checklists to validate   │
│  requirements completeness, clarity, and consistency (after /speckit.plan)   │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

2. AI 助手配置

在项目的 .qwen 目录中创建 .env 文件配置 AI 服务：

go 复制代码

# .qwen/.env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://oneapi.qunhequnhe.com/v1
OPENAI_MODEL=qwen3-coder-plus

提示：进入项目目录后，启动对应的 AI 助手（如 qwen）开始交互式开发

3. 建立项目原则

go 复制代码

/speckit.constitution 
1、安全优先架构：所有代码执行必须在沙箱环境中进行，绝不允许访问系统敏感资源。
2、即时反馈与透明执行：代码运行过程中清晰显示执行进度、资源占用和变量状态变化。
3、简化优于完整性：面向笔记场景提供开箱即用的体验，而非追求IDE级别的功能复杂度。
4、优雅降级与智能恢复：执行失败时保留用户工作成果，并提供清晰的错误指导和一键修复。
5、渐进式价值交付：核心执行器(P1)→增强体验(P2)→专业功能(P3)，每层独立可用且向下兼容。

4. 描述功能需求

go 复制代码

/speckit.specify
我要做一个在Obsidian中执行python代码的组件，该组件被引用后会读取当前文件中的python代码块进行展示，默认使用全局的python环境执行，也可以在代码块中使用env=xx来制定某一段代码的执行环境
全局环境可改，env环境配置优先级高于全局配置
可以参考阅读「自定义组件规范.md」和「计数器.components」
本项目不单只为了开发python代码执行器，还需要更通用的方式开发.components组件

5. 制定技术方案

go 复制代码

/speckit.plan

6. 生成任务清单

go 复制代码

/speckit.tasks

7. 执行开发

go 复制代码

/speckit.implement

优势与劣势分析

核心优势

1. 系统化的规格驱动开发流程

提供完整的 SDD 开发方法论，从需求定义到代码实现全程基于清晰规范
通过标准化流程确保所有开发活动围绕明确目标展开，有效减少需求误解和返工

2. 深度 AI 集成能力

与主流 AI 编码助手无缝集成，充分利用 AI 在代码生成和优化方面的能力
显著提升开发效率，特别适用于重复性任务和复杂业务逻辑的处理

3. 团队协作优化

标准化的需求文档和技术规范大幅提升团队协作效率
统一的工作标准减少沟通成本，提高项目交付质量

4. 结构化开发管理

将复杂开发过程分解为五个清晰阶段，每个阶段都有专门的命令支持
模块化的工作流程使项目管理更加透明和可控

5. 内置质量保障机制

提供多种可选增强命令确保规范一致性和完整性
支持自动生成质量检查清单，帮助验证需求完整性和实现质量

6. 渐进式价值交付理念

鼓励分层次交付价值，确保每个开发阶段都产生可用成果
降低项目风险，提高投资回报率

7. 上下文持续性保障

通过规范化的文档结构，AI 助手可以随时读取项目文件恢复开发上下文
即使在会话中断或切换助手的情况下，也能快速续接之前的开发进度
文档化的规格、计划和任务清单确保开发工作的连续性和一致性

潜在挑战

1. 学习成本较高

初次使用需要时间理解和掌握完整的工作流程和命令体系
虽然提供标准化框架，但用户仍需熟悉具体操作方式和核心概念

2. 外部依赖风险

部分功能依赖 GitHub API 和 AI 编码助手等外部服务
网络连接问题或服务中断会影响整体使用体验
需要配置多个 API 密钥和环境变量

3. 开发灵活性约束

规格驱动的严格流程可能限制快速迭代和敏捷开发
对于探索性项目或频繁需求变更的场景可能显得过于繁重

4. 环境配置复杂度

初始设置涉及多个步骤：CLI 安装、API 配置、环境变量设置等
新用户可能在配置过程中遇到技术障碍
需要一定的技术基础来解决配置问题

5. 生态成熟度限制

作为相对新兴的工具，社区支持和文档资源相对有限
遇到问题时可能难以找到充分的解决方案和最佳实践

6. 定制化能力不足

内置工作流相对固定，缺乏深度自定义选项
难以完全适应不同组织的特殊开发流程和企业文化

7. 性能和响应时间

AI 代码生成可能存在响应延迟
大规模项目或复杂交互场景下可能出现性能瓶颈

总结

Spec-Kit 作为 GitHub 官方推出的规格驱动开发工具包，为现代软件开发提供了一套系统化的解决方案。它通过将 AI 编码助手与结构化开发流程深度融合，有效提升了从需求分析到代码实现的全链路开发效率。

适用场景

最适合的团队和项目：

追求高质量代码和规范化开发流程的团队
需要频繁协作和知识共享的中大型项目
希望充分利用 AI 编码能力的开发者
对项目文档和需求管理有较高要求的企业

需要谨慎考虑的情况：

快速原型开发和探索性项目
团队技术基础相对薄弱的情况
对外部服务依赖敏感的环境
需要高度定制化开发流程的组织