深入解析 Spec Kit 工作流：基于 GitHub 的 Spec-Driven Development 实践

深入解析 Spec Kit 工作流：基于 GitHub 的 Spec-Driven Development 实践

Spec Kit 是 GitHub 推出的一款工具包，旨在通过 Spec-Driven Development（规范驱动开发，SDD） 帮助开发团队更快地构建高质量软件。本文将基于 GitHub 上的 Spec Kit 项目 详细介绍其工作（https://github.com/github/spec-kit），涵盖核心理念、开发阶段、具体步骤以及使用场景，帮助开发者快速上手并将其应用到实际项目中。

什么是 Spec-Driven Development？

传统软件开发中，代码是核心，需求规格说明书（Specification）往往只是临时的“脚手架”，在编码完成后被抛弃。Spec-Driven Development（SDD） 颠覆了这一模式，提出 可执行的规范 概念。规范不再只是指导编码的文档，而是直接驱动生成可运行的实现代码。Spec Kit 提供了一套工具和流程，让开发者专注于产品功能的 “是什么” 和 ​**“为什么”​，而不是技术细节的 ​“如何实现”**​。

Spec Kit 的核心目标是：

• ​以意图驱动开发​：通过清晰的规范定义产品需求。
• ​多阶段细化​：通过规范、计划、任务分解等步骤逐步实现。
• ​技术无关性​：支持多种技术栈和架构，适应不同项目需求。
• ​企业级约束支持​：满足企业设计系统、合规性要求等。

Spec Kit 工作流详解

Spec Kit 提供了一个结构化的工作流，包含五个主要步骤：​项目初始化​、​规范创建​、​计划生成​、计划验证 和 ​实现​。以下是基于 GitHub Spec Kit 文档的详细步骤说明。

步骤 1：初始化项目

首先，安装 Specify CLI 工具并初始化项目。Spec Kit 支持多种 AI 代理（如 Claude、Gemini、Copilot），用户需要选择一个代理来驱动开发流程。

安装 Specify CLI

运行以下命令安装 Specify 工具：

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

或者在当前目录初始化：

specify init --here

你可以通过 --ai 参数指定 AI 代理，例如：

specify init <PROJECT_NAME> --ai claude

如果不希望 CLI 检查本地工具是否安装，可以添加 --ignore-agent-tools 参数：

specify init <PROJECT_NAME> --ai claude --ignore-agent-tools

初始化后，项目目录结构如下：

├── memory
│   ├── constitution.md
│   └── constitution_update_checklist.md
├── scripts
│   ├── check-task-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh
│   ├── get-feature-paths.sh
│   ├── setup-plan.sh
│   └── update-claude-md.sh
├── specs
│   └── <FEATURE_NAME>
│       └── spec.md
└── templates├── CLAUDE-template.md├── plan-template.md├── spec-template.md└── tasks-template.md

这些目录和文件为后续的规范驱动开发提供了模板和脚本支持。

步骤 2：创建功能规范

使用 /specify 命令描述你想要构建的功能，重点是 功能需求 和 ​业务目标​，而不是技术细节。例如，假设我们要开发一个名为 Taskify 的团队生产力平台，功能包括创建项目、分配任务、Kanban 看板等。可以在 Claude Code 环境中输入以下提示：

/specify Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature, let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined. I want five users in two different categories, one product manager and four engineers. Let's create three different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," "In Progress," "In Review," and "Done." There will be no login for this application as this is just the very first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, you should be able to change the current status of the task between the different columns in the Kanban work board. You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick from. There will be no password required. When you click on a user, you go into the main view, which displays the list of projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can delete any comments that you made, but you can't delete comments anybody else made.

运行后，AI 代理会生成一个新分支（如 001-create-taskify）和规范文件（位于 specs/001-create-taskify/spec.md），包含用户故事和功能需求。

规范澄清

如果初始规范不够完善，可以通过进一步的提示澄清。例如：

/specify For each sample project, there should be a variable number of tasks between 5 and 15 tasks for each one, randomly distributed into different states of completion. Make sure that there's at least one task in each stage of completion.

还可以要求 AI 验证规范的 ​Review & Acceptance Checklist​：

/specify Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.

通过多次交互，确保规范准确反映需求。

步骤 3：生成技术实现计划

使用 /plan 命令指定技术栈和架构。例如：

/plan We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API.

此命令会生成包含技术细节的文档，更新后的目录结构如下：

├── CLAUDE.md
├── memory
│   ├── constitution.md
│   └── constitution_update_checklist.md
├── scripts
│   ├── check-task-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh
│   ├── get-feature-paths.sh
│   ├── setup-plan.sh
│   └── update-claude-md.sh
├── specs
│   └── 002-create-taskify
│       ├── contracts
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       ├── data-model.md
│       ├── plan.md
│       ├── quickstart.md
│       ├── research.md
│       └── spec.md
└── templates├── CLAUDE-template.md├── plan-template.md├── spec-template.md└── tasks-template.md

检查 research.md 文件，确保技术栈符合要求。如果需要进一步研究（如 .NET Aspire 的版本兼容性），可以使用以下提示：

/plan I want you to go through the implementation plan and implementation details, looking for areas that could benefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify that require further research, I want you to update the research document with additional details about the specific versions that we are going to be using in this Taskify application and spawn parallel research tasks to clarify any details using research from the web.

如果 AI 研究方向偏离，可以引导其聚焦：

/plan I think we need to break this down into a series of steps. First, identify a list of tasks that you would need to do during implementation that you're not sure of or would benefit from further research. Write down a list of those tasks. And then for each one of these tasks, I want you to spin up a separate research task so that the net results is we are researching all of those very specific tasks in parallel.

步骤 4：验证计划

生成计划后，需验证其完整性。使用以下提示检查计划：

/plan Now I want you to go and audit the implementation plan and the implementation detail files. Read through it with an eye on determining whether or not there is a sequence of tasks that you need to be doing that are obvious from reading this. Because I don't know if there's enough here. For example, when I look at the core implementation, it would be useful to reference the appropriate places in the implementation details where it can find the information as it walks through each step in the core implementation or in the refinement.

如果发现计划过于复杂或包含未要求的功能，可以要求 AI 简化或澄清。例如，检查是否遵循 constitution.md 中的原则。

如果使用 GitHub CLI，还可以让 AI 创建 pull request：

/plan Create a pull request from the current branch to main with a detailed description.

步骤 5：实现

验证计划后，运行以下命令开始实现：

/implement specs/002-create-taskify/plan.md

AI 会根据计划生成代码。确保本地安装了必要的 CLI 工具（如 dotnet）。实现完成后，运行应用并检查错误。如果出现运行时错误（如浏览器日志中的错误），将错误信息提供给 AI 以修复。

核心理念与开发阶段

Spec Kit 的核心理念是 ​以规范为核心​，通过多阶段细化将需求转化为可运行代码。其开发阶段包括：

1. ​**0-to-1 开发（Greenfield）**​：
   • 从零开始生成应用。
   • 活动：需求收集、规范生成、计划制定、实现。
2. ​创意探索​：
   • 探索多种技术栈和 UX 模式。
   • 支持并行实现，比较不同方案。
3. ​**迭代增强（Brownfield）**​：
   • 迭代添加功能。
   • 现代化遗留系统。

实验目标

Spec Kit 的实验目标包括：

• ​技术无关性​：验证 SDD 可适配多种技术栈。
• ​企业约束​：支持企业级需求，如合规性和设计系统。
• ​用户中心​：满足不同用户群体的开发偏好。
• ​创意与迭代​：支持并行探索和持续改进。

故障排除

Linux 上的 Git Credential Manager 问题

如果在 Linux 上遇到 Git 认证问题，可以安装 Git Credential Manager：

#!/bin/bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

支持与社区

如需帮助，可在 GitHub Issues 提交问题，报告 bug 或提出功能请求。

总结与参考资料

Spec Kit 提供了一种创新的开发方式，通过规范驱动开发减少重复工作，让开发者专注于产品功能的设计。它的多阶段工作流（初始化、规范、计划、验证、实现）结合 AI 代理，显著提高了开发效率和代码质量。无论是从零开始的 Greenfield 项目，还是迭代改进的 Brownfield 项目，Spec Kit 都能提供灵活支持。

通过本文的介绍，相信你已经对 Spec Kit 的工作流有了深入了解。快去 GitHub Spec Kit 下载并尝试，将规范驱动开发融入你的项目吧！

https://github.com/github/spec-kit