spec-kit 开发指南：高效构建高质量软件

本章我们要解决的问题是如何安装 spec-kit 并指定 CLI 工具，这样你就可以开始使用这个强大的软件开发工具包了。读完这章后，你应该能够在你的机器上成功安装 spec-kit，并能够启动它的命令行界面。

首先，我们需要确保你已经安装了 uv 工具。你可以通过点击 这里 来查看详细的安装指南。如果没有安装的话，请先按照指引完成安装，因为后续的操作都需要依赖于它。

接下来，我们需要找到 spec-kit 的最新版本号。你可以在 GitHub 发布页面 查看最新的发布标签。记住版本号的时候要带上前面的那个字母 v，比如应该是 v0.12.11 而不是 0.12.11。

我们先打开终端或者命令行工具，然后输入以下命令来安装 specify-cli：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

别担心，你需要将上面命令中的 vX.Y.Z 替换为你刚才查到的最新版本号。例如，如果最新版本是 v0.12.11，那么完整的命令就是：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.11

预期的结果是你会在终端看到一些关于下载和安装的信息，并且最后会显示安装成功的消息。

如果你遇到错误信息提示找不到 uv 或者权限不足，可以检查一下是否正确安装了 uv 工具，并确认你在终端中有足够的权限来执行这些操作。

接着，为了验证我们的 CLI 是否正常工作，我们可以尝试运行一个简单的命令来看看效果。假设你想初始化一个新的项目并且选择 Claude 作为集成工具，你可以使用下面的命令：

specify init demo-project --integration claude --ignore-agent-tools --script sh

这条命令会创建一个名为 demo-project 的新项目，并且设置了一些初始选项。完成后你会在当前目录下看到一个叫做 demo-project 的文件夹。

如果你对这些选项感到好奇为什么需要它们：

• --integration claude: 指定使用的 AI 集成工具为 Claude。
• --ignore-agent-tools: 忽略任何默认的代理工具。
• --script sh: 使用 shell 脚本来处理脚本部分的内容。

通过以上步骤，我们就完成了 spec-kit 的安装以及 CLI 工具的指定。你现在应该能够在本地环境中顺利地使用 spec-kit 进行项目的开发和管理了。

本章小结

• 我们学习了如何通过 uv 工具来安装 specify-cli。
• 掌握了查找并替换版本号的方法。
• 尝试了一个初始化项目的简单命令，并理解了其中的一些参数含义。

本章我们要继续探索如何使用 specify CLI 来初始化一个新的项目，并选择合适的集成工具。完成这一步后，你将能够在一个新的项目环境中开始你的开发工作。

在开始之前，请确保你已经按照上一章的指导成功安装了 specify-cli 并验证了它的功能。你应该有一个可以运行基本命令的环境。

我们先来初始化一个新的项目。假设你想创建一个名为 photo-organizer 的项目，并且希望使用 GitHub Copilot 作为集成工具。你可以使用以下命令：

specify init photo-organizer --integration copilot --ignore-agent-tools --script sh

这条命令会创建一个名为 photo-organizer 的新项目文件夹，并设置一些初始选项。完成后你会在当前目录下看到一个叫做 photo-organizer 的文件夹。

如果你遇到错误信息，比如找不到命令或者权限问题，可能是因为 specify-cli 没有正确安装或者路径没有添加到系统变量中。检查一下上一章的操作步骤，确保一切无误。

接着，我们进入刚刚创建的项目目录：

cd photo-organizer

在这个目录中，你会发现一系列自动生成的文件和文件夹，这些都是 spec-kit 为我们准备的基础结构。

你可能会好奇为什么我们需要这些选项：

• --integration copilot: 指定使用的 AI 集成工具为 GitHub Copilot。
• --ignore-agent-tools: 忽略任何默认的代理工具。
• --script sh: 使用 shell 脚本来处理脚本部分的内容。

这些选项帮助我们更好地控制项目的初始化过程，确保生成的项目符合我们的需求和期望。

为了让你更好地理解这个过程，我们可以来看一个小例子。假设你在一家摄影工作室工作，需要开发一个应用程序来帮助客户组织他们的照片。你可以使用上面的命令来快速启动这个项目，并利用 GitHub Copilot 提供的帮助来加速开发过程。

本章小结

• 我们学习了如何使用 specify init 命令来初始化一个新的项目。
• 理解了不同参数的作用及其重要性。
• 成功进入了新项目的目录，并看到了自动生成的基本结构。

在本章中，我们要制定项目的指导原则和开发规范。通过这一步骤，我们可以确保整个团队朝着同一个方向努力，提高代码质量和开发效率。完成之后，你会有一个清晰的项目愿景和一套详细的开发规则。

在开始之前，请确保你已经按照上一章的步骤成功初始化了一个项目，并且当前所在的目录是你项目的根目录。

首先，我们需要启动你的编码助手（AI 集成工具），以便输入一些指令来创建项目的原则和规范。如果你选择了 GitHub Copilot 作为集成工具，那么你需要在终端或者支持 GitHub Copilot 的编辑器中使用以下命令：

/speckit.constitution 创建项目原则，包括代码质量标准、测试规范、用户体验一致性要求以及性能指标

预期结果：这将会生成一个名为 CONSTITUTION.md 的文件，在其中记录下你设定的项目原则和开发规范。

你可能会好奇为什么我们需要这些原则：

• 代码质量标准：确保所有提交的代码都遵循一致的格式和最佳实践。
• 测试规范：定义编写单元测试、集成测试的标准流程。
• 用户体验一致性要求：保证用户界面的一致性和易用性。
• 性能指标：设立应用响应速度和其他性能方面的目标。

如果不这样做的话，团队成员可能会各自为战，导致最终的产品质量参差不齐。

举个例子来说，假设我们在前面创建的照片整理应用项目中。这时我们就可以这样设置我们的项目原则：

/speckit.constitution 创建项目原则如下：
1. 所有新增功能需经过至少两个同事审查后才能合并到主分支。
2. 每次提交代码前必须通过所有的自动化测试。
3. 用户界面应简洁明了，并提供直观的操作指引。
4. 应用启动时间不超过两秒。

这样做的好处是明确了每个人的责任和期望的结果，减少了沟通成本并且提高了工作效率。

本章小结

• 我们学习了如何使用 /speckit.constitution 命令来创建项目的治理原则和发展指南。
• 理解了为什么需要这些具体的开发规范。
• 通过一个实际的例子加深了对这些概念的理解。

编写项目规范和实施计划是为了确保我们的开发过程井然有序，每个人都知道自己应该做什么以及如何做。通过这一章的学习，你将能够使用 spec-kit 工具来详细描述你的项目需求和技术实现路径。

在开始之前，请确保你已经完成了以下步骤：

• 成功安装了 specify-cli
• 初始化了一个项目并选择了合适的集成（例如 Copilot）
• 创建了项目的治理原则和发展指南（即 CONSTITUTION.md 文件）

我们先从编写详细的项目规范开始。这个规范不仅包括我们要实现的功能，还包括技术栈的选择和架构设计。

第一步：编写项目规范

使用 /speckit.specify 命令来描述你想要构建的应用程序。这里的关键是要专注于“是什么”而不是“怎么实现”。

/speckit.specify 构建一个可以帮助我管理照片的应用程序。应用程序允许用户创建不同的相册，并根据日期自动分组。用户可以通过拖放重新组织相册顺序。每个相册中的照片将以网格形式显示。

预期结果：这将会生成一个名为 SPECIFICATION.md 的文件，在其中记录下你设定的项目规范。

第二步：创建技术实施计划

接下来，我们需要制定具体的技术实现细节，比如使用的框架、库以及其他基础设施。

/speckit.plan 应用程序将使用 React.js 作为前端框架，并且采用 TypeScript 来提高代码质量和可维护性。数据库方面，我们将使用 Firebase Realtime Database 来存储用户的相册信息和照片元数据。

预期结果：这将会生成一个名为 PLAN.md 的文件，在其中记录下你的技术实施计划。

可能遇到的问题及解决方法

如果你在执行上述命令时遇到问题，可以尝试以下方法：

• 检查是否正确安装了 specify-cli：你可以通过运行 specify --version 来确认版本号。
• 确认你在正确的目录下执行命令：所有命令都需要在初始化后的项目根目录中执行。
• 查看错误日志：如果出现错误信息，仔细阅读并理解错误提示有助于快速定位问题所在。

实际案例分析

假设我们在继续上面的照片整理应用项目。我们可以这样描述我们的需求和技术选择：

/speckit.specify 构建一个可以帮助我管理照片的应用程序。应用程序允许用户创建不同的相册，并根据日期自动分组。用户可以通过拖放重新组织相册顺序。每个相册中的照片将以网格形式显示。
/speckit.plan 应用程序将使用 React.js 作为前端框架，并且采用 TypeScript 来提高代码质量和可维护性。数据库方面，我们将使用 Firebase Realtime Database 来存储用户的相册信息和照片元数据。

这样的描述既明确了我们要实现的功能，又指出了具体的技术方案，为后续的任务分解和开发工作打下了坚实的基础。

本章小结

• 学习了如何使用 /speckit.specify 命令来详细描述项目需求。
• 掌握了如何通过 /speckit.plan 命令制定技术实施计划。
• 了解了可能遇到的问题及其解决方案，并掌握了相应的排查方法。
• 通过实际案例加深了对这两个命令的理解和运用能力。

现在我们要开始将之前制定的技术实施计划分解成具体的任务，并逐一执行这些任务来实现我们的照片整理应用。通过这种方式，我们可以确保每个部分都按计划进行，最终顺利完成整个项目的开发。

前置条件

• 你已经安装并初始化了一个 spec-kit 项目。
• 你已经在项目中使用 /speckit.specify 描述了你的需求。
• 你已经使用 /speckit.plan 制定了技术实施计划。
• 确认你在正确的项目根目录下执行命令。

第一步：分解任务

我们需要将之前制定的技术实施计划进一步细化成具体的任务列表。这一步骤非常重要，因为它能帮助我们更好地管理和跟踪进度。

我们先使用 /speckit.tasks 命令来生成任务列表：

/speckit.tasks

预期结果：这个命令会根据你的技术实施计划自动生成一系列的具体任务，并列出它们的状态（例如待完成、正在进行等）。你可以通过查看终端输出或者打开生成的文件来查看这些任务。

第二步：检查和调整任务列表

有时候自动生成的任务列表可能不够详细或者有些地方需要调整。这时候你需要手动编辑任务列表，使其更加符合实际需求。

打开 tasks.json 文件（默认情况下在这个路径下可以找到），你会看到类似如下的内容：

[
    {
        "id": "task_1",
        "description": "设置 React.js 和 TypeScript 的开发环境",
        "status": "pending"
    },
    {
        "id": "task_2",
        "description": "集成 Firebase Realtime Database",
        "status": "pending"
    }
]

你可以根据实际情况添加新的任务项、修改现有任务的描述或者删除不需要的任务。确保每一项都是明确且可操作的。

第三步：执行任务

现在我们有了详细的任务列表，接下来就是按照顺序一一完成这些任务了。这里我们会介绍如何使用 /speckit.implement 命令来自动化地完成这些任务。

首先，我们尝试执行第一个待办事项：

/speckit.implement task_1

预期结果：这个命令会根据 tasks.json 中定义的内容自动执行相应的工作。比如对于上面的例子，它可能会帮你安装所需的依赖包、配置 Webpack 或者 Babel 等。

如果你遇到任何错误信息，请仔细阅读错误日志，并尝试解决问题。常见的错误包括缺少必要的依赖库或者是配置文件格式不正确等。查阅相关的文档或者社区资源通常能找到解决方案。

示例：逐步实现照片整理应用的功能

假设我们现在要实现的第一个功能是“设置 React.js 和 TypeScript 的开发环境”，那么对应的 tasks.json 可能包含如下内容：

{
    "id": "setup_env",
    "description": "设置 React.js 和 TypeScript 的开发环境",
    "status": "pending"
}

然后我们运行以下命令来处理这个任务：

/speckit.implement setup_env

spec-kit 会自动为我们搭建好所需的开发环境，包括创建项目结构、安装 npm 包以及配置 TypeScript 支持等。

接着我们可以继续处理下一个任务，比如“集成 Firebase Realtime Database”：

/speckit.implement integrate_firebase_db

同样地，spec-kit 会帮助我们完成这项工作，包括安装 Firebase SDK、配置数据库连接以及其他必要的步骤。

通过不断地分解和执行这些小的任务单元，我们可以有条不紊地推进整个项目的进展。

本章小结

• 学习了如何使用 /speckit.tasks 命令将技术实施计划分解成具体的操作步骤。
• 掌握了如何检查和调整生成的任务列表以适应实际需求。
• 理解了如何利用 /speckit.implement 命令来自动化地完成各项具体的工作。
• 通过一个实际的例子展示了如何一步步地实现项目的各个功能模块。

定制 spec-kit 让我们的开发流程更加灵活和高效。通过使用扩展和预设，我们可以根据项目的特定需求进行个性化的配置，从而更好地满足不同的开发场景。

在开始之前，请确保你已经完成了前面的步骤，并且你的项目已经被初始化并且设置了相应的开发环境。具体来说，你需要有一个基于 spec-kit 创建的项目目录，并且已经安装好了所有必要的依赖包。

我们先来看看如何添加扩展。扩展可以为 spec-kit 提供额外的功能或者增强现有功能的表现力。

添加扩展

假设我们要添加一个用于代码格式化的扩展 prettier。首先我们需要找到这个扩展在社区中的名称或者仓库地址。这里我们假定它的仓库地址是 https://github.com/github/prettier-extension。

接着我们运行以下命令来安装这个扩展：

specify extension add prettier-extension --from https://github.com/github/prettier-extension.git

预期的结果是在你的项目中会新增一个关于 prettier 的配置文件，同时可能还会有一些脚本被添加到你的 package.json 文件中以便于后续使用。

如果你遇到错误信息类似于 Extension not found at URL... 这样的情况，请确认提供的仓库地址是否正确无误，并且该仓库确实包含了一个有效的 spec-kit 扩展。

配置预设

预设则是一些预先定义好的模板或者规则集合，可以帮助我们在启动新项目的时候快速应用一些最佳实践。例如，如果我们希望在项目中采用一种标准的编码风格和命名约定，我们可以选择一个相关的预设来进行配置。

假设我们要使用的预设叫做 standard-style 并且它位于 https://github.com/github/standard-style-preset 上面。我们可以按照下面的方式将其添加到我们的项目当中：

specify preset apply standard-style --from https://github.com/github/standard-style-preset.git

这将会下载并应用该预设的所有设置到当前项目之中。你可以打开 .spec-kit/config.yaml 文件来查看具体的改动内容。

需要注意的是，在应用某个预设之后，如果发现某些默认设置不符合你的团队规范，你可以手动编辑上述配置文件来进行适当的调整。

实际案例

为了更好地理解如何使用扩展和预设，让我们来看一个小例子。假设我们正在开发一款社交媒体应用程序，并且希望在整个项目中保持一致的代码风格，并且能够自动检测潜在的代码质量问题。

首先我们会选择一个流行的代码质量检查工具作为扩展，比如 ESLint：

specify extension add eslint-extension --from https://github.com/github/eslint-extension.git

然后为了保证团队成员都遵循相同的编码规范，我们可以选用一个常见的样式指南作为预设：

specify preset apply airbnb-styleguide --from https://github.com/github/airbnb-styleguide-preset.git

这样我们就能够在每次提交代码时自动运行 ESLint 来查找问题，并且所有开发者都会遵循 Airbnb 的编码风格进行编程了。

本章小结

• 学习了如何通过 specify extension add 命令来增加新的功能模块给 spec-kit。
• 掌握了利用 specify preset apply 命令来自定义项目的初始设置。
• 了解了如何结合实际业务场景选择合适的扩展和预设组合以优化开发效率。
• 通过一个实例演示了如何逐步地将这些自定义选项整合进现有的工作流之中。

管理 spec-kit 的更新和版本控制对于确保你的项目始终保持最新并且稳定至关重要。通过本章的学习，你将掌握如何检查更新、升级 spec-kit 以及使用版本控制系统来管理代码变更。

在开始之前，请确保你已经按照上一章的指导安装并初始化了 spec-kit，并且已经在项目中集成了所需的扩展和预设。

第一步：检查是否有可用更新

首先，我们需要确认当前安装的 spec-kit 是否有最新的版本发布。你可以使用以下命令来进行检查：

specify self check

预期结果： 这个命令会告诉你当前安装的版本号以及是否有更高版本可用。如果没有新版本，则会显示类似“Already up to date”的信息。

第二步：预览升级过程

在决定升级之前，最好先看看将会发生哪些变化。可以使用下面的命令来模拟升级过程：

specify self upgrade --dry-run

预期结果： 这个命令会列出所有即将应用的更改，包括下载的新文件和可能被覆盖的现有文件。这有助于你在正式升级前做好准备。

第三步：执行实际升级

当你确认没有问题后，就可以进行实际的升级操作了。以下是具体的命令：

specify self upgrade

或者如果你想指定某个特定版本进行升级，可以这样做：

specify self upgrade --tag v0.12.11

预期结果： 系统会自动下载并安装最新版或指定版本的 spec-kit。如果一切顺利，你会看到一条表示成功完成的消息。

第四步：集成版本控制系统

为了更好地管理和追踪代码的变化历史，建议使用 Git 进行版本控制。如果你还没有初始化 Git 仓库，可以通过以下步骤来创建一个新的仓库：

git init
git add .
git commit -m "Initial commit"

预期结果： 以上命令依次完成了以下几个动作：

• 初始化一个新的 Git 仓库。
• 将当前目录下的所有文件添加到暂存区。
• 提交暂存区的内容，并附带了一条描述性的消息“Initial commit”。

接下来，你可以继续使用 Git 来记录每一次重要的修改，并且可以在需要的时候回滚到之前的版本。

实际案例演示

假设我们在开发一个社交媒体应用程序的过程中发现了一个严重的安全漏洞，并且 spec-kit 已经发布了修复该问题的新版本。我们可以按照上述步骤来进行处理：

1. 首先检查是否有新版本：

   specify self check

2. 如果有新版本，则预览一下升级内容：

   specify self upgrade --dry-run

3. 确认无误后执行实际升级：

   specify self upgrade

4. 升级完成后，在本地对项目进行测试以确保问题已得到解决。
5. 最后将修复后的代码提交到 Git 仓库：

   git add .
   git commit -m "Fix security vulnerability by upgrading spec-kit"

通过这样的流程，我们可以有效地管理和维护我们的项目依赖项，并且能够快速响应各种紧急情况。

本章小结

• 学习了如何使用 specify self check 和 specify self upgrade 命令来检查和应用 spec-kit 的更新。
• 掌握了如何使用 Git 对项目进行版本控制的基本操作。
• 了解了如何在发现重要 bug 后及时升级依赖项并记录变更历史的重要性。

问题：在安装 Specify CLI 时遇到错误提示 command not found: uv

解答：请确保已正确安装 uv 工具。根据文档中的说明，您可以通过访问 uv 安装指南 来获取详细的安装步骤。

问题：如何检查和升级 Specify CLI 到最新版本？

解答：您可以使用以下命令来检查是否有可用更新，并进行升级：

# 检查更新
specify self check

# 升级到最新稳定版
specify self upgrade

如果您需要指定特定版本，请使用 --tag 参数，例如：

specify self upgrade --tag v0.12.11

问题：初始化项目时选择了错误的集成选项，该如何更改？

解答：如果在初始化项目时选择了错误的集成选项（如 Copilot），可以在项目的根目录下手动编辑 .specify/config.yaml 文件，修改 integration 字段为您想要使用的集成名称。

问题：如何创建一个符合特定技术栈的应用程序规范？

解答：首先使用 /speckit.specify 命令定义应用程序的功能需求，然后通过 /speckit.plan 命令提供您的技术栈选择。例如：

/speckit.specify 构建一个用于管理个人照片的应用程序。
/speckit.plan 应用程序使用 Vite 和最少数量的库构建。尽可能多地使用纯 HTML、CSS 和 JavaScript。图像不上传到任何地方，元数据存储在本地 SQLite 数据库中。

问题：Spec Kit 是否支持其他编程语言或框架？

解答：Spec Kit 主要支持基于文本的规范驱动开发流程，理论上可以适用于多种编程语言和框架。不过具体的实现细节可能需要用户自定义扩展或预设来完成适配。

问题：与其他类似工具相比，Spec Kit 的优势是什么？

解答：Spec Kit 的核心优势在于其将规格化提升到了可执行级别，可以直接从规格生成工作实现而不是仅仅作为指导。此外，它还提供了丰富的社区资源和支持多样的AI编码代理集成能力。

问题：我在使用过程中遇到了一些难以解决的问题怎么办？

解答：您可以参考官方提供的 详细过程文档，或者访问 GitHub 社区页面 提出您的疑问。社区成员会尽力帮助您解决问题。