检查 GitHub Spec Kit 开发环境

  • 7 分钟

GitHub 规范工具包需要正确配置的开发环境来支持规范驱动的开发工作流。 正确配置的环境包括指定 CLI、AI 编码助手、代码编辑器和版本控制系统。 请务必了解构成 GitHub Spec Kit 开发环境、支持的配置以及安装和初始化概念的组件。

开发环境组件

GitHub 规范工具包开发环境由多个基本组件组成，这些组件协同工作以支持规范驱动的开发过程：

  • 指定 CLI：用于初始化项目、创建模板结构和管理规范驱动的工作流的命令行接口工具。 指定 CLI 基于 Python，需要 Python 3.11 或更高版本，并充当设置 GitHub Spec Kit 项目的基础。

  • uv 包管理器：用于安装和管理 Specify CLI 的建议工具。 该工具 uv 为指定 CLI 提供持久性安装、版本管理和升级功能。

  • 代码编辑器与 AI 集成：GitHub Spec Kit 旨在与支持通过聊天界面和斜杠命令的 AI 编码助手的代码编辑器配合使用。 Visual Studio Code 与 GitHub Copilot 是主要支持的配置，但工具包支持其他 AI 代理。

  • 版本控制系统：GitHub Spec Kit 项目（规范、计划、任务和宪法文件）作为 markdown 文件存储在版本控制的存储库中。 Git 是标准版本控制系统，支持 GitHub、GitHub Enterprise Server 和 Azure Repos。

  • AI 编码助手：规范驱动的工作流依赖于 AI 模型来解释规范并生成实现计划和代码。 GitHub Copilot 是推荐用于此培训的 AI 助手，尽管 GitHub Spec Kit 支持多个 AI 代理。

  • 编程运行时（依赖于上下文）：虽然 GitHub Spec Kit 本身不需要特定的编程运行时，但你需要适当的运行时来实现基于所选技术堆栈的功能（如 .NET SDK、Node.js或 Python）。

支持的 AI 代理和模型

GitHub Spec Kit 旨在与支持聊天界面和自定义斜杠命令的各种 AI 编码助手配合使用。 了解支持的选项有助于为开发工作流选择合适的配置：

  • GitHub Copilot：GitHub 规范工具包支持的主要 AI 助手，可通过 Visual Studio Code 的 GitHub Copilot 聊天扩展获得。 GitHub Copilot 提供集成的聊天体验、内联代码建议，并支持自定义斜杠命令以触发 GitHub Spec Kit 工作流。

  • 广泛的 AI 代理支持：GitHub Spec Kit 支持超过 15 个 AI 编码助手，包括 Claude Code、Cursor、风帆板、Gemini CLI、Qwen Code、Kilo Code、Auggie CLI、CodeBuddy CLI、Roo Code、Codex CLI 和 Amp。 每个代理都通过类似的模式与 GitHub Spec Kit 集成，使用聊天接口，这些接口可以识别 /speckit.* 斜杠命令，并可以读取项目工件来指导实现。

  • 特定于代理的限制：虽然大多数代理完全支持 GitHub 规范工具包，但有些限制。 例如，Amazon Q Developer CLI 不支持斜杠命令的自定义参数，这可能会影响某些工作流自定义。

  • 模型要求：GitHub 规范工具包工作流依赖于能够理解复杂规范、跨多个项目维护上下文以及生成结构化输出的 AI 模型。 具有广泛上下文窗口的现代大型语言模型最适合解释规格并生成全面的实施计划。

技术堆栈和语言支持

GitHub Spec Kit 的核心原则之一是技术独立性，规范驱动的方法适用于各种技术堆栈、编程语言和框架：

  • 语言不可知：规范描述要生成的内容，而不是如何生成它。 可以在 .NET、Node.js、Python、Java 或任何其他语言中实现相同的规范。 技术栈的选择是在规划阶段进行，而不是在制定规范时。

  • 框架灵活性：GitHub 规范工具包支持适用于项目的任何框架或库。 无论是使用 React、Angular 或 Blazor 构建 Web 应用程序、使用 Express 或 ASP.NET Core 的后端服务，还是使用 .NET MAUI 或 React Native 构建移动应用，规范驱动过程仍保持一致。

  • 云平台中立性：尽管规范可以包括体系结构约束（如“使用 Azure 服务”或“部署到 AWS”），但 GitHub Spec Kit 不会强制实施特定的云提供商。 在宪法文件中定义的组织标准指导云平台的选择。

  • 多个同时实现：高级 GitHub 规范工具包工作流支持使用不同的技术堆栈创建相同规范的多个并行实现，从而在提交最终方法之前探索不同的解决方案。

平台和操作系统支持

GitHub 规范工具包适用于主要作系统，确保开发团队可以使用其首选平台：

  • Windows 支持：在 Windows 10 及更高版本上完全支持 PowerShell 和命令提示符兼容性。 Specify CLI 包括用于初始化和配置的特定于 Windows 的脚本。

  • macOS 和 Linux 支持：在 macOS 和 Linux 发行版上提供原生支持，并兼容 bash 和 zsh shell。 安装遵循使用包管理器和 pip 的标准 Unix 约定。

  • 跨平台一致性：GitHub 规范工具包项目（Markdown 文件、提示模板和配置）使用独立于平台的格式，确保规范和计划在不同作系统中的工作方式相同。

企业环境注意事项

组织通常具有影响开发环境配置的特定要求、策略和基础结构：

  • 企业网络限制：企业环境可能使用代理服务器、自定义证书颁发机构或影响包安装和 Git作的防火墙规则。 开发环境必须通过代理配置和证书信任设置来考虑这些约束。

  • 扩展和软件审批：某些组织将 Visual Studio Code 扩展安装限制为已批准的市场或需要安全评审。 了解这些策略有助于规划环境设置时间线。

  • 托管开发环境：许多组织提供预配置的开发虚拟机、容器或基于云的开发环境。 这些托管环境通常包括预安装的 Python、Git 和 Visual Studio Code，简化了设置并确保符合组织标准。

  • Azure DevOps 集成：对于使用 Azure DevOps 而不是 GitHub 的团队，GitHub Spec Kit 项目与 Azure Repos 无缝集成。 任务可以链接到 Azure Boards 工作项，规范充当拉取请求中的文档。

  • GitHub Enterprise Server：使用 GitHub Enterprise Server（自承载 GitHub）的组织可以将 GitHub Spec Kit 与特定于企业的身份验证、合规性控制和组织策略配合使用。

安装和初始化概念

了解如何安装和初始化 GitHub 规范工具包有助于了解环境设置过程。

关键安装和初始化概念包括：

  • Specify CLI 安装：可以使用 uv 工具将 Specify CLI 持久安装，使 specify 命令在系统范围内可用，或者通过 uvx 进行一次性使用，而无需永久安装。 建议进行持久性安装以支持持续开发工作，并通过uv tool list、uv tool upgrade和uv tool uninstall命令来更好地管理工具。

  • 环境验证：该 specify check 命令验证所需的工具是否已安装和访问，包括 Git 和所选的 AI 编码代理。 此验证步骤有助于在开始开发工作之前诊断环境问题。

  • 项目初始化：该 specify init 命令创建用于规范驱动开发的项目结构。 此过程生成提示模板目录、项目模板文件和配置，使 AI 助手能够识别和响应 /speckit.* 斜杠命令。

  • 高级初始化选项：该specify init命令支持企业和专用方案的各种标志，包括跳过 Git 初始化的选项（--no-git）、使用现有目录（--here、--force）、为公司环境指定 GitHub 令牌（--github-token）、跳过代理方案的 TLS 验证（），并启用详细的调试输出（--skip-tls--debug）。

  • AI 代理选择：在初始化期间，选择使用的 AI 编码助手（例如 GitHub Copilot、Claude 或其他）。 此选项确定配置了哪些提示模板和集成脚本。

  • 版本控制集成：GitHub Spec Kit 默认会初始化 Git 存储库（除非明确禁用），确保从一开始就对所有工件进行版本控制。 版本控制集成支持团队共享规范和跟踪随时间变化的协作工作流。

初始化后的项目结构

初始化后，GitHub Spec Kit 将创建标准化项目结构：

  • .github/prompts/ 目录：包含提示模板文件，指导 AI 助手完成规范驱动工作流的每个阶段。 文件包括constitution.prompt.md、specify.prompt.md、、clarify.prompt.md、plan.prompt.md、tasks.prompt.md、implement.prompt.md和analyze.prompt.mdchecklist.prompt.md。

  • 制品模板文件：GitHub Spec Kit 在项目根目录创建了constitution.md、spec.md、plan.md和tasks.md的模板版本。 这些模板提供了使用于工作流过程中会被填充的章节占位符的起始点。

  • 配置文件：根据所选的 AI 代理，GitHub Spec Kit 可能会创建与编码助手环境集成的其他配置文件。

  • 脚本变体：对于跨平台支持，GitHub Spec Kit 可以生成 bash/zsh 脚本（.sh 文件）和 PowerShell 脚本（.ps1 文件），确保与不同的作系统和 shell 兼容。

斜杠命令架构

/speckit.* AI 编码助手中显示的命令通过 GitHub Spec Kit 的提示模板架构启用：

  • 命令识别：键入 /speckit AI 聊天界面时，助手会根据中的 .github/prompts/提示模板识别自定义命令。

  • 核心工作流命令：规范驱动开发工作流的基本命令包括 /speckit.constitution （创建项目原则）、（定义要求）、 /speckit.specify （创建技术计划）、 /speckit.plan/speckit.tasks （生成任务列表）和 /speckit.implement （执行实现）。

  • 质量增强命令：其他命令支持迭代优化和验证，包括 /speckit.clarify （明确指定区域）、 /speckit.analyze （跨项目一致性分析）和 /speckit.checklist （生成质量验证清单）。

  • 模板驱动指南：每个斜杠命令对应于提示模板文件，指示 AI 如何生成或更新特定项目。 例如， specify.prompt.md 指导 AI 创建结构化规范，其中包含“摘要”、“要求”、“验收条件”和“边缘案例”部分。

  • 上下文感知：提示模板引用项目中的其他项目，使 AI 能够保持一致性。 例如，生成技术计划时， /speckit.plan 引用 constitution.md （对于约束）和 spec.md （要求）。

  • 自定义潜力：组织可以自定义提示模板以强制实施特定文档标准、添加所需部分或合并特定于域的术语。

环境验证概念

正确配置的环境可实现流畅的规范驱动开发工作流。

关键验证点包括：

  • CLI 辅助功能：命令 specify 应在终端路径中可用，指示 CLI 安装成功。

  • Visual Studio Code 扩展激活：应安装、激活和验证 GitHub Copilot Chat 扩展，从而启用用于斜杠命令的聊天界面。

  • 项目识别：初始化后，在 Visual Studio Code 中打开项目应使 /speckit.* 命令在 GitHub Copilot Chat 自动完成中可用。

  • 版本控制就绪情况：应配置 Git，并初始化存储库，从而允许项目提交和协作。

  • 环境变量：GitHub 规范工具包支持通过环境变量进行配置。 例如，变量 SPECIFY_FEATURE 可以覆盖非 Git 存储库中的功能检测，以便在不使用 Git 分支时启用特定功能。

常见环境注意事项

不同的开发方案带来了不同的环境挑战：

  • 企业代理和防火墙：企业网络通常需要代理配置以进行包安装和 Git 操作。 在信任公司 HTTPS 拦截之前，证书颁发机构可能需要配置。

  • 扩展审批流程：具有安全策略的组织可能需要批准，然后才能安装 Visual Studio Code 扩展，从而影响设置时间线。

  • Python 版本管理：单个计算机上的多个 Python 版本可能会导致路径冲突。 了解哪些 Python 解释器处于活动状态有助于排查安装问题。

  • PATH 配置：通过 pip 或 uv 安装的 CLI 工具需要在系统 PATH 中安装其安装目录。 不同的作系统和 shell 以不同的方式处理 PATH 配置。

  • 托管环境和自助服务环境：预配置的开发 VM 简化了设置，但自定义可能受到限制。 自助服务本地安装提供灵活性，但需要更多单独的配置。

概要

GitHub 规范工具包开发环境结合了指定 CLI、AI 编码助手、代码编辑器和版本控制系统等基本组件，以实现有效的规范驱动开发工作流。 了解斜杠命令架构、项目结构及环境验证过程，可以确保您能够设置和维护高效的开发环境。 通过解决企业设置中的常见注意事项，可以调整 GitHub 规范工具包以满足组织要求，同时使用 AI 支持的编码帮助实现一致且可跟踪的实现。