检查 GitHub Spec Kit 的工作流和可选命令

  • 8 分钟

GitHub 规范工具包是一个开源工具包，通过将规范与 AI 编码助手集成，实现规范驱动的开发（SDD）。 在探索高级功能之前，让我们回顾一下基础概念。

回顾 GitHub Spec Kit 基础知识

GitHub 规范工具包解决了 AI 辅助开发中的根本难题：利用编码助手在多次交互中保持上下文的连续性和一致性。 它提供了三项基本功能：

  • 持久化工件：规范、计划和任务作为 Markdown 文件存储在存储库中。
  • 标准化工作流：定义的流程指导你完成四个 SDD 阶段：规范、规划、任务细分和实现。
  • 可重用命令：内置斜杠命令封装了最佳做法提示模式。

核心组件

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

组件 目的
specify CLI（命令行界面） 初始化和管理基于规范的项目。
Markdown 项目文件 constitution.md、spec.md、plan.mdtasks.md推动开发。
斜杠命令 /speckit.specify、/speckit.plan、/speckit.tasks/speckit.implement调用 GitHub Spec Kit 工作流。

AI 代理

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

用于功能跟踪的环境变量

GitHub 规范工具包使用环境变量来跟踪当前正在开发的功能。 该 SPECIFY_FEATURE 变量指示活动功能目录。

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

对于非 Git 工作流或手动功能规范，请显式设置环境变量：

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

无论 Git 分支如何，此设置都会告知 GitHub 规范工具包在 features/001-document-upload/ 目录中读取和写入项目。

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

将 GitHub 规范工具包与 Git 工作流集成

GitHub 规范工具包通过多种机制集成到现有开发实践中。

版本控制集成

所有 GitHub Spec Kit 构件都是存储在 Git 存储库中的纯 Markdown 文件。 此方法有多种优点：

  • 变更记录：每次修改规范、计划或任务都会创建 Git 提交记录。 可以查看要求更改的历史记录，了解决策的原因，并还原有问题的更改。

  • 基于分支的开发：创建包含规范项目和实现代码的功能分支。 此方法保持要求和实现保持同步，并使代码评审全面 - 审阅者同时查看所生成的内容（规范）以及生成方式（代码）。

  • 拉取请求工作流：提交功能的拉取请求时，代码更改应同时包括 spec.md、plan.md 和 tasks.md。 审阅者验证实现是否与规范匹配，并且该规范与项目目标保持一致。

例如，如果要实现新功能，则功能分支包含：

  • spec.md 定义上传要求。
  • plan.md 描述 Azure Blob 存储体系结构。
  • tasks.md 列出实现步骤。
  • 实现该功能的源代码。
  • 测试验证规范符合性。

此完整图片可实现彻底的审查。 如果审阅者质疑文件限制为 50 MB 的原因，他们可以引用 spec.md 并查看此要求来自利益干系人讨论。

AI 助手集成方案 - GitHub Copilot

GitHub 规范工具包通过 Visual Studio Code 的聊天界面与 GitHub Copilot 协同工作。 运行 specify init --ai copilot后，工具包将工作区配置为识别 /speckit.* 命令。

打开 GitHub Copilot 聊天并键入 /speckit.specify时，GitHub Copilot 会从目录中访问预定义的 .github/prompts/ 模板。 这些模板有助于构建 AI 的输出，以包含所有必要的规范部分：用户情景、验收条件、功能要求、非功能要求和边缘案例。

集成是无缝的， 你不会手动管理模板。 GitHub 规范工具包会自动处理模板加载和上下文注入。 你的工作是提供功能说明和回答澄清问题。 GitHub Copilot 负责处理规范的格式和完整性。

项目结构约定

GitHub Spec Kit 使用一致的目录结构组织项目：

my-project/
├── .github/
│   ├── agents/
│   └── prompts/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── SourceCode/ 
│   └── ...
├── specs/
│   └── 001-document-upload-feature/
│       ├── plan.md
│       ├── spec.md
│       └── tasks.md

此结构将规范项目与实现代码分开，同时将它们保存在同一存储库中。 特征按顺序编号（001,002,003），以跟踪开发顺序。

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

持续工作流支持

GitHub Spec Kit 支持通过命令链进行迭代开发。 生成初始规范后，可以逐步优化它们：

  1. 生成初始规范： /speckit.specify.
  2. 识别差距： /speckit.clarify.
  3. 根据答案更新规范。
  4. 创建实现计划： /speckit.plan。
  5. 验证一致性： /speckit.analyze。
  6. 生成任务： /speckit.tasks.
  7. 以增量方式实现： /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 数据库。
  • “规范需要审核日志记录，但计划不描述日志记录实现。
  • “任务列表省略计划中提到的数据库迁移脚本。

每个识别的不一致是一个会在实现或代码评审过程中浮现的问题。 在分析阶段捕获它们可防止返工。

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

该 /speckit.checklist 命令根据规范生成自定义质量清单。 这些清单有助于验证要求完整性、清晰度和一致性，例如“英语散文的单元测试”。

AI 分析您的规范并生成一份用于验证问题的检查清单：

  • “每个用户情景是否都有相应的接受条件？”
  • 所有错误情景是否都记录在案并包含特定的错误消息？
  • “非功能要求是否包括可衡量的成功标准？
  • “是否显式列出所有外部依赖项？”

你完成清单，回答每个问题。 任何“否”答案都表示需要解决的规范差距。

在与利益干系人共享或继续实施之前，此自我审查过程提高了规范质量。

将 GitHub 规范工具包应用于不同的开发方案

GitHub Spec Kit 支持各种开发方案，不仅限于从头开始构建新功能。

绿地开发

对于从无到有开始的新项目，GitHub Spec Kit 擅长将高级产品愿景转换为具体实现。 /speckit.constitution首先建立项目原则，然后在以迭代方式生成应用程序时对每个功能使用/speckit.specify。

此方案是 GitHub Spec Kit 的主要用例 -- 工作流专为 0 到 1 开发而设计，你正在创建尚不存在的内容。

棕地增强功能

对于现有应用程序，可以使用 GitHub Spec Kit 添加新功能，同时保持与现有代码库的一致性。 宪法记录了现有的体系结构模式和约束。 新功能规范引用这些已建立的模式。

将文档上传功能添加到现有员工门户时，规范会确认现有的 React 前端、.NET 后端和 Azure 基础结构。 该计划展示了新功能如何与当前体系结构集成，而不是提出单独的实现。

重构和现代化

GitHub 规范工具包可以通过将所需的结束状态视为规范来指导重构工作。 你记录重构代码应实现的内容（具有改进的结构的相同功能）、为重构方法创建计划，并为增量更改生成任务。

这种结构化的重构方法可以防止开始重构时出现的常见问题，以及在过程中丢失部分可工作的代码。

探索开发

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

可以使用 Azure Blob 存储生成一个计划，另一个计划使用 Azure 文件存储，这两者都来自相同的上传规范。 实现两者，比较结果，并根据实际体验而不是假设选择更好的方法。

概要

GitHub 规范工具包是一个功能强大的工具包，它通过集成结构化工作流、持久性项目和可重用 AI 命令模式，实现规范驱动的开发。 它通过提供一种将规范转化为实际实现的系统方法，改变你使用 AI 编码助手（如 GitHub Copilot）的方式。 通过使用 GitHub 规范工具包，可以确保在要求和代码之间保持一致，保持决策的可追溯性，并提高开发团队之间的协作。