GitHub Spec Kit 是一个开源工具包，通过将规范与 AI 编程助手集成，实现规范驱动开发（Spec-Driven Development，SDD）。

回顾 GitHub Spec Kit 基础知识

GitHub Spec Kit 解决了 AI 辅助开发中的一个基本挑战：在与编程助手的多次交互中保持上下文和一致性。

它提供了以下三个基本功能：

持久化工件（Persistent artifacts）：规范、计划和任务以 Markdown 文件的形式存储在你的代码仓库中。标准化工作流（Standardized workflow）：定义了一个过程，引导你完成规范驱动开发的四个阶段：规范制定、计划、任务分解和实现。可复用命令（Reusable commands）：内置的斜杠命令封装了最佳实践提示模式。

核心组件

GitHub Spec Kit 实现了以下核心组件：

组件

用途

specify CLI

初始化和管理规范驱动项目。

Markdown 工件文件

constitution.md、spec.md、plan.md、tasks.md 驱动开发。

斜杠命令

/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement 调用 GitHub Spec Kit 工作流。

AI 智能体（AI agents）

GitHub Spec Kit 支持以下 AI 智能体：GitHub Copilot、Claude Code、Cursor、Windsurf、Amazon Q Developer 等。每个智能体都会收到针对其特定提示格式的模板，同时使用相同的底层工件文件。

用于功能跟踪的环境变量

GitHub Spec Kit 使用环境变量来跟踪你当前正在开发的功能。SPECIFY_FEATURE 变量指示活动功能目录。

在基于 Git 的工作流中，GitHub Spec Kit 会从你的分支名称推断出功能。如果你在分支 feature/document-upload 上，GitHub Spec Kit 会自动使用 features/document-upload/ 目录。

对于非 Git 工作流或手动指定功能，可以显式设置环境变量：

$env:SPECIFY_FEATURE = "001-document-upload"

此设置告诉 GitHub Spec Kit 在 features/001-document-upload/ 目录中读取和写入工件文件，而不管 Git 分支是什么。

这个功能跟踪确保了当你调用 /speckit.plan 时，AI 会读取当前功能的正确 spec.md 文件，而不是混合不同功能的规范。

将 GitHub Spec Kit 与 Git 工作流集成

GitHub Spec Kit 通过多种机制与你的现有开发实践集成。

版本控制集成

GitHub Spec Kit 的所有工件都是存储在你的 Git 代码仓库中的普通 Markdown 文件。这种方法有以下优点：

变更跟踪（Change tracking）：对规范、计划或任务的每一次修改都会创建一个 Git 提交。你可以查看需求变更的历史记录，了解决策的原因，并回退有问题的变更。基于分支的开发（Branch-based development）：创建包含规范工件和实现代码的功能分支。这种方法保持了需求和实现的同步，并使代码审查更加全面——审查者可以看到你正在构建的内容（规范）以及你是如何构建的（代码）。拉取请求工作流（Pull request workflows）：当你为一个功能提交拉取请求时，将 spec.md、plan.md 和 tasks.md 与代码变更一起提交。审查者会验证实现是否符合规范，以及规范是否与项目目标一致。

例如，如果你正在实现一个新功能，你的功能分支包含以下内容：

spec.md 定义上传需求。plan.md 描述 Azure Blob Storage 架构。tasks.md 列出实现步骤。实现该功能的源代码。验证规范合规性的测试。

这种完整的视图可以进行彻底的审查。如果审查者质疑为什么文件大小限制为 50 MB，他们可以参考 spec.md，并看到这一需求来自利益相关者的讨论。

AI 助手集成场景 - GitHub Copilot

GitHub Spec Kit 通过 Visual Studio Code 的聊天界面与 GitHub Copilot 集成。运行 specify init --ai copilot 后，工具包会配置你的工作区以识别 /speckit.* 命令。

当你在 GitHub Copilot 聊天中输入 /speckit.specify 时，GitHub Copilot 会访问 .github/prompts/ 目录中的预定义模板。这些模板有助于结构化 AI 的输出，使其包含所有必要的规范部分：用户故事、验收标准、功能性需求、非功能性需求和边缘情况。

这种集成是无缝的——你不需要手动管理模板。GitHub Spec Kit 自动处理模板加载和上下文注入。你的工作是提供功能描述并回答澄清问题。GitHub Copilot 负责规范的格式化和完整性。

项目结构约定

GitHub Spec Kit 使用一致的目录结构来组织工件：

这种结构将规范工件与实现代码分开，同时将它们放在同一个代码仓库中。功能按顺序编号（001、002、003），以便跟踪开发顺序。

对于同时处理多个功能的团队，每个功能都有自己的目录，包含完整的规范、计划和任务。这种隔离可以防止混淆，并允许并行工作而不会产生冲突。

持续工作流支持

GitHub Spec Kit 通过命令链支持迭代开发。在生成初始规范后，你可以逐步完善它们：

生成初始规范：/speckit.specify。识别差距：/speckit.clarify。根据回答更新规范。创建实现计划：/speckit.plan。验证一致性：/speckit.analyze。生成任务：/speckit.tasks。逐步实现：/speckit.implement。

在任何时候，如果需求发生变化，你可以返回到早期阶段，更新工件，并重新生成下游工件。如果利益相关者在你生成任务后改变了对文件大小限制的看法，你可以更新 spec.md，重新生成 plan.md 以反映架构影响，重新生成 tasks.md 以更新验证步骤，然后更新实现代码。

这种灵活性支持现实世界中的开发，需求会不断演变。规范优先的方法确保了变更可以系统地传播，而不是在没有更新文档的情况下将变更直接修补到代码中。

利用 GitHub Spec Kit 的可选增强命令

除了核心工作流命令外，GitHub Spec Kit 还提供了可选命令，以提高规范的质量和一致性。

使用 /speckit.clarify 进行差距分析

/speckit.clarify 命令会分析你的规范，识别模糊之处、缺失的细节以及未充分说明的边缘情况。在生成初始规范后，调用此命令让 AI 提出澄清问题。

AI 会审查你的规范，并生成类似以下的问题：

“规范中提到了文件上传，但没有指定最大并发上传数量。是否应该设置限制？”“没有指定网络故障的错误处理。如果上传连接丢失，应该怎么办？”“规范要求文件验证，但没有指定验证失败的消息。用户应该看到什么？”

对于每个问题，AI 通常会提供多种选择，供你选择如何填补差距。你可以选择一个选项或提供自定义答案，AI 会相应地更新规范。

这种交互式完善可以在实施开始之前发现潜在问题。这就像有一位经验丰富的分析师审查你的规范并指出你遗漏的内容。

使用 /speckit.analyze 进行一致性验证

/speckit.analyze 命令会进行跨工件一致性检查。它会验证你的计划是否实现了所有规范要求，任务是否涵盖了计划的所有元素，以及一切是否与宪法一致。

在生成 plan.md 和 tasks.md 后但在开始实现之前运行此命令。AI 会识别不一致之处：

“计划建议使用 PostgreSQL，但宪法要求使用 Azure SQL Database。”“规范要求审计日志，但计划中没有描述日志实现。”“任务列表遗漏了计划中提到的数据库迁移脚本。”

每个识别出的不一致之处都是在实施或代码审查阶段会浮现的问题。在分析阶段发现这些问题可以避免返工。

使用 /speckit.checklist 进行质量验证

/speckit.checklist 命令会根据你的规范生成定制的质量检查表。这些检查表有助于验证需求的完整性、清晰度和一致性——就像“对代码进行单元测试一样”。

AI 会分析你的规范，并生成一个检查问题的清单：

“每个用户故事都有对应的验收标准吗？”“所有错误场景是否都已记录，并附有具体的错误消息？”“非功能性需求是否包含可衡量的成功标准？”“所有外部依赖项是否都已明确列出？”

你可以逐项检查清单，回答每个问题。任何“否”的答案都表明规范存在差距，你需要加以解决。

这种自我审查过程可以提高规范的质量，然后再与利益相关者分享或继续实施。

将 GitHub Spec Kit 应用于不同的开发场景

GitHub Spec Kit 支持各种开发场景，不仅仅是从头开始构建新功能。

绿地开发（Greenfield development）

对于从零开始的新项目，GitHub Spec Kit 在将高层次的产品愿景转化为具体的实现方面表现出色。你可以从 /speckit.constitution 开始，确立项目原则，然后在迭代构建应用程序时，为每个功能使用 /speckit.specify。

这是 GitHub Spec Kit 的主要用例——该工作流是为 0 到 1 的开发设计的，即创建尚不存在的东西。

棕地增强（Brownfield enhancement）

对于现有应用程序，你可以使用 GitHub Spec Kit 在保持与现有代码库一致的同时添加新功能。你的宪法文件记录了现有的架构模式和约束。新功能规范引用这些既定的模式。

当你向现有的员工门户添加文档上传功能时，你的规范会承认现有的 React 前端、.NET 后端和 Azure 基础设施。计划展示了新功能如何与当前架构集成，而不是提出一个单独的实现方案。

重构和现代化（Refactoring and modernization）

GitHub Spec Kit 可以通过将期望的最终状态视为规范来指导重构工作。你记录下重构代码应实现的目标（保持相同的功能，但结构有所改进），创建一个重构方法的计划，并生成逐步更改的任务。

这种结构化的方法可以避免重构过程中常见的问题，即开始重构后在代码部分工作时迷失方向。

探索性开发（Exploratory development）

在你探索多种潜在方法的情况下，使用 GitHub Spec Kit 从相同的规范生成多个计划。稳定的规范代表了你想要实现的目标，而不同的计划则探索不同的技术方法。

你可以根据相同的上传规范生成一个使用 Azure Blob Storage 的计划和另一个使用 Azure Files 的计划。分别实现这两个计划，比较结果，并根据实际经验（而非假设）选择更好的方法。

总结

GitHub Spec Kit 是一个强大的工具包，通过整合结构化工作流、持久化工件和可复用的 AI 命令模式，实现了规范驱动开发。它改变了我们与 GitHub Copilot 等 AI 编程助手的工作方式，提供了一种系统化的方法，将规范转化为实际的实现。通过使用 GitHub Spec Kit，你可以确保需求与代码之间的一致性，保持决策的可追溯性，并增强开发团队之间的协作。