Spec Kit 实战指南：用 Specify CLI 落地规范驱动开发（SDD）

Spec Kit 是 GitHub 出品的开源规范驱动开发（Spec-Driven Development, SDD）工具套件，它通过 specify CLI 将"规范 → 方案 → 任务 → 实现"的多步工作流注入任意 AI 编码助手。本文基于项目官方中文 README 逐章展开，并深入仓库源码验证模板解析栈、捆绑包机制与内置扩展/预设的真实实现，带你从零完成安装、初始化、斜杠命令工作流，再到用扩展、预设和捆绑包打造自己的团队级配置。

什么是规范驱动开发？

规范驱动开发颠覆了传统软件开发的思路。几十年来，代码一直是核心——规范只是编码这项"正事"开始前搭起、随后就被丢弃的脚手架。规范驱动开发改变了这一点：规范本身变得可执行，它不再只是引导实现，而是直接生成可运行的实现。

围绕这一目标，规范驱动开发强调四个核心理念：

• 意图驱动开发——让规范先定义"做什么"，再谈"怎么做"
• 丰富的规范撰写——借助护栏（guardrails）与组织准则来编写规范
• 多步精炼——而非从提示词一次性生成代码
• 充分依赖先进 AI 模型对规范的解读能力

完整的流程方法论请参阅仓库内的 规范驱动开发完整指南，棕地（存量）项目的迭代循环请参阅 规范演进指南。

环境要求

开始之前，请确认本地环境满足以下条件：

• Linux / macOS / Windows
• 任意一个受支持的 AI 编码助手（30 多个，见下文集成说明）
• uv 用于包管理（推荐），或 pipx 用于持久化安装
• Python 3.11+
• Git

这一要求可以从构建配置中得到印证：pyproject.toml 中声明了 requires-python = ">=3.11"，包名为 specify-cli，并注册了命令行入口 specify = "specify_cli:main"——也就是说安装完成后 specify 命令直接可用。

快速开始

1. 安装 Specify CLI

需要 uv（uv 的安装说明见 docs/install/uv.md）。将 vX.Y.Z 替换为最新发布标签——记得保留开头的 v（例如 v0.12.11，而不是 0.12.11）：

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

更倾向从 PyPI 安装？specify-cli 包同样发布在那里：

uv tool install specify-cli

其他安装方式、安装校验、升级以及故障排查，请参阅 安装指南。

2. 初始化项目

specify init my-project --integration copilot
cd my-project

--integration 指定要接入的 AI 编码助手。运行 specify integration list 可查看当前安装版本中所有可用的集成；从源码结构看，src/specify_cli/integrations/ 目录下为每个助手提供了独立实现模块（claude、codex、gemini、copilot、cursor_agent、opencode 等 38 个具名集成，外加一个 generic 兜底实现），与 README 中"可与 30 多个 AI 编码助手协作"的描述一致。

要检查更新或升级已安装的 CLI，可使用自管理命令。更详细的场景和自定义选项请参阅 升级指南：

# 检查是否有更新版本可用（只读操作 —— 不会修改任何内容）
specify self check

# 预览升级将执行的操作，但不实际升级
specify self upgrade --dry-run

# 就地升级到最新稳定版（自动识别 uv tool 与 pipx 安装方式）
specify self upgrade

# 或锁定到指定的发布标签（将 vX.Y.Z[suffix] 替换为你想要的标签）
specify self upgrade --tag vX.Y.Z[suffix]

直接运行 specify self upgrade 会立即执行，与 pip install -U、npm update 等命令一样无需额外确认。对于 uv tool 安装的情况，它在底层会执行 uv tool install specify-cli --force --from <git ref>，因此锁定的发布标签同样有效，包括 dev、alpha/beta/rc 或带构建元数据的后缀。uvx（临时运行）和源码检出会被自动识别，此时会给出针对具体路径的操作建议，而不会执行安装程序。可通过设置 SPECIFY_UPGRADE_TIMEOUT_SECS 来限制安装子进程的最长运行时间（默认无超时限制——必要时用 Ctrl+C 中断）。

3. 确立项目准则

在项目目录下启动你的编码助手。大多数助手将 spec-kit 暴露为 /speckit.* 斜杠命令；处于技能（skills）模式的 Codex CLI 则使用 $speckit-*；GitHub Copilot CLI 使用 /agents 来选择助手，或直接在提示词中指定它。

使用 /speckit.constitution 命令来创建项目的治理准则和开发指南，它们将指导后续所有开发工作：

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

4. 编写规范

使用 /speckit.specify 命令描述你想构建什么。聚焦于做什么和为什么做，而不是技术栈：

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

5. 制定技术实现方案

使用 /speckit.plan 命令提供你的技术栈和架构选择：

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

6. 拆解为任务

使用 /speckit.tasks 从实现方案生成一份可执行的任务清单：

/speckit.tasks

7. 执行实现

使用 /speckit.implement 执行所有任务，按方案构建你的功能：

/speckit.implement

详细的分步说明，请参阅我们的 完整指南。

可用的斜杠命令

运行 specify init 后，你的 AI 编码助手就能使用这些斜杠命令来进行结构化开发。对于支持技能模式的集成，传入 --integration <agent> --integration-options="--skills" 会安装助手技能，而不是斜杠命令的提示词文件。

核心命令

规范驱动开发工作流中必不可少的命令：

命令	助手技能	说明
/speckit.constitution	speckit-constitution	创建或更新项目的治理准则和开发指南
/speckit.specify	speckit-specify	定义你想构建什么（需求与用户故事）
/speckit.plan	speckit-plan	结合所选技术栈制定技术实现方案
/speckit.tasks	speckit-tasks	生成可执行的实现任务清单
/speckit.taskstoissues	speckit-taskstoissues	将生成的任务清单转换为 GitHub issue，便于跟踪与执行
/speckit.implement	speckit-implement	执行所有任务，按方案构建功能
/speckit.converge	speckit-converge	对照规范/方案/任务评估代码库，并将剩余工作追加为新任务

可选命令

用于提升质量与做校验的额外命令：

命令	助手技能	说明
/speckit.clarify	speckit-clarify	澄清描述不充分的部分（建议在 /speckit.plan 之前使用；旧称 /quizme）
/speckit.analyze	speckit-analyze	跨制品的一致性与覆盖度分析（在 /speckit.tasks 之后、/speckit.implement 之前运行）
/speckit.checklist	speckit-checklist	生成自定义质量清单，校验需求的完整性、清晰度与一致性（好比"为自然语言写单元测试"）

从源码结构看，这些命令的提示词模板就存放在 templates/commands/ 目录中（specify.md、plan.md、tasks.md、implement.md、clarify.md、analyze.md、checklist.md、converge.md 等），并配套 spec-template.md、plan-template.md、tasks-template.md、constitution-template.md、checklist-template.md 等制品模板。pyproject.toml 的 wheel 打包配置将这些模板与 scripts/ 下的 bash / powershell / python 三套脚本一并打入 specify_cli/core_pack/，因此 specify init 即使在没有网络的环境下也能离线完成项目初始化。

支持的 AI 编码助手集成

Spec Kit 可与 30 多个 AI 编码助手协作——既包括 CLI 工具，也包括基于 IDE 的助手。运行 specify integration list 可查看当前安装版本中所有可用的集成；如果你在使用某个助手时遇到问题，欢迎提交 issue 以便完善相应集成。

打造你自己的 Spec Kit：扩展、预设与本地覆盖

Spec Kit 可通过两套互补的机制进行深度定制——扩展（extensions）和预设（presets）——以及面向单个项目的本地覆盖，用于临时性调整：

优先级	组件类型	位置
⬆ 1	项目本地覆盖	.specify/templates/overrides/
2	预设 —— 定制核心与扩展	.specify/presets/templates/
3	扩展 —— 新增能力	.specify/extensions/templates/
⬇ 4	Spec Kit 核心 —— 内置 SDD 命令与模板	.specify/templates/

• 模板在运行时解析——Spec Kit 从高到低遍历优先级栈，使用第一个匹配项。
• 项目本地覆盖（.specify/templates/overrides/）允许对单个项目做一次性调整，无需创建完整的预设。
• 扩展/预设命令在安装时生效——当你运行 specify extension add 或 specify preset add 时，命令文件会被写入助手目录（如 .claude/commands/）。
• 若多个预设或扩展提供了同一命令，优先级最高的版本生效。移除时，次优先级的版本会自动恢复。
• 若不存在任何覆盖或自定义，Spec Kit 使用核心默认配置。

这套"运行时优先级栈"在源码中有直接对应：scripts/python/resolve_template.py 是模板解析入口，它调用 scripts/python/common.py 中的 resolve_template_content()，按"本地覆盖 → 预设 → 扩展 → 核心"的顺序查找第一个匹配的模板文件（overrides/ 目录即第一优先级）。此外，scripts/python/common.py 的 get_feature_paths() 负责解析当前功能目录：它优先读取环境变量 SPECIFY_FEATURE_DIRECTORY，其次读取 .specify/feature.json 中的 feature_directory 字段，最终派生出 spec.md、plan.md、tasks.md、research.md、data-model.md、quickstart.md、contracts/ 等一系列制品路径——这正是各斜杠命令读写文件的统一约定。

扩展 —— 新增能力

当你需要 Spec Kit 核心之外的功能时，使用扩展。扩展可引入新命令和模板——例如添加核心 SDD 命令未覆盖的领域特定工作流、集成外部工具，或新增全新的开发阶段。它们扩展了 Spec Kit 能做什么。

# 搜索可用扩展
specify extension search

# 安装扩展
specify extension add <extension-name>

举例来说，扩展可以添加 Jira 集成、实现后代码审查、V 模型测试追溯性，或项目健康诊断等功能。

仓库本身内置了四个扩展（在 pyproject.toml 中一并打包进 wheel，可直接 specify extension add <name> 安装）：git、agent-context、assess、bug。以 bug 扩展为例，其 extensions/bug/extension.yml 声明了三个命令——speckit.bug.assess（评估缺陷报告并给出可能的修复方案）、speckit.bug.fix（应用修复并记录变更）、speckit.bug.test（验证修复是否生效），构成一个可重复的"评估 → 修复 → 测试"流程，缺陷报告按 slug 存放在 .specify/bugs/<slug>/ 下。

预设 —— 定制现有工作流

当你想改变 Spec Kit 的工作方式而不是新增能力时，使用预设。预设会覆盖核心及已安装扩展中附带的模板和命令——例如强制使用面向合规的规范格式、采用领域特定术语，或对方案和任务应用组织规范。预设定制的是 Spec Kit 及其扩展生成的制品与指令。

# 搜索可用预设
specify preset search

# 安装预设
specify preset add <preset-name>

举例来说，预设可以重构规范模板以要求监管追溯性，将工作流适配为你所用的方法论（如敏捷、看板、瀑布、用户任务驱动或领域驱动设计），在方案中添加强制安全审查关卡，强制要求测试优先的任务排序，或将整个工作流本地化为其他语言。多个预设可按优先级叠加使用。

内置的 lean 预设是这一机制的典型样本：presets/lean/preset.yml 声明了 5 个 type: command 的模板条目（speckit.specify、speckit.plan、speckit.tasks、speckit.implement、speckit.constitution），每条都通过 replaces 字段指明它替换的是哪一个核心命令——其定位是"极简核心工作流：只有提示词与制品"。

何时用哪个

目标	使用
添加全新的命令或工作流	扩展
定制规范、方案或任务的格式	预设
集成外部工具或服务	扩展
强制执行组织或监管规范	预设
交付可复用的领域特定模板	均可 —— 预设用于模板覆盖，扩展用于随新命令一起打包的模板
用一条命令完成完整的角色配置	捆绑包

捆绑包：面向角色的一键配置

扩展和预设是独立的构建模块。而**捆绑包（bundle）**将一组精选的扩展、预设、步骤和工作流打包成一个带版本、面向角色的配置，从而可以用一条命令为整个团队角色（产品经理、业务分析师、安全研究员、开发者……）完成配置。

捆绑包由一份手写的 bundle.yml 清单描述。它将每个组件锁定到具体版本，并可选择性地面向特定集成；未指定 integration 的捆绑包是中立的，会沿用项目当前已使用的集成。

# 在当前激活的目录栈中发现捆绑包
specify bundle search [<query>]

# 查看捆绑包将添加的确切组件集合（与实际安装的内容一致）
specify bundle info <bundle-id>

# 一步安装捆绑包的完整组件集合
specify bundle install <bundle-id>

# 查看已安装内容，然后以非破坏性方式更新或移除
specify bundle list
specify bundle update <bundle-id>     # 或 --all
specify bundle remove <bundle-id>     # 仅移除此捆绑包的组件

捆绑包从一个按优先级排序的目录栈（项目 > 用户 > 内置）中解析。每个来源都带有安装策略：install-allowed 来源可用于安装，而 discovery-only 来源在 search/info 中可见但拒绝安装。可通过 specify bundle catalog list|add|remove 管理目录栈。

作者在本地校验并打包捆绑包。分发方式是托管构建产物并添加一个目录来源：

specify bundle validate --path ./my-bundle      # 结构与引用检查
specify bundle build --path ./my-bundle         # 生成带版本的 .zip 产物

examples/bundles/ 目录下有四份可直接阅读的示例清单（产品经理、业务分析师、安全研究员、开发者）。以 examples/bundles/developer/bundle.yml 为例，清单分为三大部分：bundle（id、名称、版本、角色、作者、许可证）、requires（要求的 speckit_version 最低版本、外部 tools 与 mcp 依赖）、provides（本包提供的 extensions、presets、steps、workflows 及各自的版本锁定）。开发者捆绑包声明了 speckit_version: ">=0.9.0"，并提供 agent-context 扩展、implementation-planning 预设（priority: 10、strategy: "append"）、plan-implementation / break-down-tasks 两个步骤以及 spec-to-implementation 工作流——注意它没有声明 integration，因此属于"中立"捆绑包，会继承项目当前激活的集成。

关键保证：info 展示的内容与 install 添加的内容完全一致（透明性）；安装是幂等的，且限定在项目根目录内；remove 绝不会触碰其他已安装捆绑包仍需要的组件；所有消费/创作命令都能针对本地或锁定的来源离线工作。

开发阶段与实验目标

开发阶段

阶段	侧重点	关键活动
从 0 到 1 开发（"绿地/Greenfield"）	从零生成	从高层需求出发 生成规范 规划实现步骤 构建生产就绪的应用
创意探索	并行实现	探索多样化的解决方案 支持多种技术栈与架构 试验不同的用户体验模式
迭代增强（"棕地/Brownfield"）	存量系统现代化	迭代式添加功能 现代化改造遗留系统 调整流程

对于已有项目，请将 Spec Kit 工具本身的更新与功能制品的演进分开处理：升级时刷新受管理的项目文件，而在预期行为发生变化时更新 specs/ 制品。规范演进指南介绍了推荐的棕地迭代循环。

实验目标

本项目的研究与实验聚焦于：

技术无关性

• 使用多样化的技术栈构建应用
• 验证这一假设：规范驱动开发是一套流程，不与特定技术、编程语言或框架绑定

企业级约束

• 展示关键业务应用的开发
• 纳入组织层面的约束（云服务商、技术栈、工程实践）
• 支持企业设计系统与合规要求

以用户为中心的开发

• 为不同的用户群体和偏好构建应用
• 支持多种开发方式（从"氛围编码"到 AI 原生开发）

创意与迭代流程

• 验证并行实现探索的理念
• 提供稳健的迭代式功能开发工作流
• 将流程扩展到升级与现代化改造任务

社区与贡献

社区贡献的资源覆盖五个方向：

• 扩展（Extensions）——命令、钩子与各类能力，见 docs/community/extensions.md
• 预设（Presets）——模板与术语覆盖，见 docs/community/presets.md
• 捆绑包（Bundles）——由现有组件组合而成的角色与团队技术栈，见 docs/community/bundles.md
• 实战演练（Walkthroughs）——端到端的 SDD 场景，见 docs/community/walkthroughs.md
• 伙伴项目（Friends）——扩展 Spec Kit 或基于它构建的项目，见 docs/community/friends.md

注意：社区贡献由各自的作者独立创建和维护。请在安装前审阅源代码，并自行斟酌使用。

想要参与贡献？请参阅 扩展发布指南、预设发布指南或 社区捆绑包指南。

支持、致谢与许可证

如需帮助，请提交 issue。项目欢迎缺陷报告、功能建议，以及关于使用规范驱动开发的各类问题。本项目深受 John Lam 的工作与研究的影响，并在其基础上构建；项目基于 MIT 开源许可证授权，完整条款请参阅 LICENSE 文件。

小结

Spec Kit 的价值在于把"先定义、后构建"落成一套可执行、可组合的工程流程：specify init 完成助手接入，/speckit.* 斜杠命令驱动 constitution → specify → plan → tasks → implement → converge 的完整链路，而模板优先级栈、扩展、预设与捆绑包四层机制则保证了从个人项目到团队角色的规模化定制。以上所有行为均可在当前仓库中交叉验证：模板解析见 scripts/python/common.py，核心模板见 templates/，内置扩展与预设见 extensions/ 与 presets/，捆绑包机制与示例见 src/specify_cli/bundler/ 与 examples/bundles/。