Spec Kit 快速上手：从 specify init 到 /speckit.converge 的完整 SDD 工作流

Spec Kit（Specify CLI）是一套面向 Spec-Driven Development（规格驱动开发）的工具包：它通过 specify init 在项目中铺设模板、脚本与集成命令，再由一系列 /speckit.* 斜杠命令驱动“规格 → 澄清 → 计划 → 任务 → 实现 → 收敛”的完整闭环。本文以官方快速上手指南为主线，全程用一个示例项目 Taskify（一个小型团队生产力平台）演示每一步的真实输入，并结合 specify init 的源码实现与脚本层代码，解释各步骤背后的工程细节，帮助你从零跑通第一条特性。

准备工作：安装 Specify 并初始化项目

自动化脚本提供 Bash（.sh）、PowerShell（.ps1）和 Python（.py）三种变体。交互式 specify init 会提示你选择其中一种；非交互运行（无 TTY，或显式传入 --non-interactive）会按操作系统默认选择一种 shell 变体（Windows 为 ps，其他平台为 sh）。你也可以用 --script sh|ps|py 显式指定。

命令在下文中以 /speckit.* 形式书写，但实际调用形式取决于你所用的 Agent。部分基于 skills 的 Agent 使用 $speckit-*（如 Codex、ZCode）或 /skill:speckit-*（如 Kimi）。使用你的 Agent 暴露的形式即可——步骤本身完全一致。

安装 CLI 并初始化项目

在终端中，先从 PyPI 安装 CLI（需要 uv），然后初始化项目：

uv tool install specify-cli
specify init taskify   # 或：specify init .   使用当前目录

init 会让你交互式地选择编码 Agent，也可以用 --integration 显式传入（例如 --integration copilot）。对于 CI 和 AI Agent 编排场景，加上 --non-interactive，使未指定的选项使用文档化的默认值，而不是卡在方向键选择器上。

其他安装方式（pipx、一次性 uvx 运行、固定版本、离线/内网环境）见 安装指南。如果要把 Spec Kit 加入一个已有代码的仓库，请先阅读 在既有项目中采用 Spec Kit，再开始下面的工作流。

specify init 背后做了什么：源码视角

阅读 init 命令实现 可以确认文档中的行为细节：

• 集成选择：传入 --integration 时会在注册表中校验（init.py 中，未知集成名会报错并列出全部可用集成）；非交互会话（无 TTY 或 --non-interactive）默认落到内置的默认集成（如 Copilot），并打印提示。Agent 编排器即使分配了 PTY（isatty() 为真）也无法发送方向键输入，因此 _prompts_allowed()（init.py）专门处理了这种"伪交互"场景，避免挂起。
• 脚本类型：未显式传 --script 时，默认为 ps（Windows）或 sh（其他平台），交互模式下用方向键选择器（init.py）。
• 初始化步骤：命令会依次安装集成、共享基础设施（模板与脚本）、内置 speckit 工作流、初始化 constitution 文件，并把 feature_numbering: sequential、集成、脚本类型等写入 init 选项（init.py）。项目脚手架来自 CLI 包内捆绑的资源，因此初始化本身不需要网络，且模板版本与已安装 CLI 严格一致。
• 失败清理：如果初始化中途失败且项目目录是本次命令新建的，源码会清理该目录（init.py），避免留下半成品。

初始化完成后，脚本会安装到与所选脚本类型对应的子目录：

• .specify/scripts/bash/ — .sh 脚本（Linux/macOS 默认）
• .specify/scripts/powershell/ — .ps1 脚本（Windows 默认）
• .specify/scripts/python/ — .py 脚本（--script py 选择，同时安装平台 shell 回退）

上下文感知：当前特性是怎么被定位的

Spec Kit 通过记录在 .specify/feature.json 中的特性目录来跟踪当前活动特性（可用环境变量 SPECIFY_FEATURE_DIRECTORY 覆盖）。各命令从该状态解析特性，而不是从当前签出的 Git 分支解析——也就是说整个流程不强制要求 Git。可选的 git 扩展会添加带编号的特性分支（如 001-feature-name）用于在版本控制中组织工作，但"当前活动特性"始终是状态文件指向的那个目录；单独执行 git checkout 不会改变它。要把命令指向另一个特性，更新 .specify/feature.json（或设置 SPECIFY_FEATURE_DIRECTORY）即可。

这个解析逻辑在三套脚本实现中完全一致。以 Bash 公共库为例，get_feature_paths() 的解析优先级为（见 common.sh）：

1. 环境变量 SPECIFY_FEATURE_DIRECTORY（显式覆盖，相对路径会被归一化到仓库根目录下）；
2. .specify/feature.json 中的 feature_directory 键（由 specify 命令持久化）；
3. 两者都没有则报错退出。

Python 变体在 common.py 中实现了相同逻辑，并且读取 feature.json 时按 jq → python3 → grep/sed 的顺序降级解析（common.sh），保证在缺少 jq 的机器上也能工作。解析成功后脚本会输出 FEATURE_DIR、FEATURE_SPEC、IMPL_PLAN、TASKS 等路径变量，供各 /speckit.* 命令定位 spec.md、plan.md、tasks.md 等产物。

推荐流程：短路径与完整路径

安装 Spec Kit 后，下面每条命令都是流程中的一步。常见的有两条路径：

短路径 —— 适用于较小的特性：

1. /speckit.specify
2. /speckit.plan
3. /speckit.tasks
4. /speckit.implement
5. /speckit.converge

完整路径 —— 适用于生产级特性，额外加入 /speckit.clarify、/speckit.checklist、/speckit.analyze 作为质量门禁：

1. /speckit.constitution
2. /speckit.specify
3. /speckit.clarify
4. /speckit.plan
5. /speckit.checklist
6. /speckit.tasks
7. /speckit.analyze
8. /speckit.implement
9. /speckit.converge

Step 1：/speckit.constitution — 确立项目原则

建立项目的指导原则，后续每一步都会对照它进行评估。开头运行一次即可，把原则作为参数传入：

/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.

Step 2：/speckit.specify — 描述要构建什么

从自然语言描述创建特性规格。聚焦 what 和 why，而不是技术栈：

/speckit.specify Develop Taskify, a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users (one product manager, four engineers), three sample projects, no login for this first phase.

Step 3：/speckit.clarify — 消除歧义

针对规格中任何欠明确之处提出有针对性的问题，并把你的回答折叠回规格，避免"在歧义之上做计划"。在计划之前运行，可以附带一个聚焦领域：

/speckit.clarify Focus on task card behavior — status changes, comment permissions, and user assignment.

Step 4：/speckit.plan — 选择技术栈

从规格生成设计产物。实现细节应该出现在这里——提供技术栈与架构：

/speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications.

Step 5：/speckit.checklist — 验证规格

生成自定义质量清单——相当于"针对需求的单元测试"——确认规格在拆解工作之前是完整、清晰、一致的。这些自定义清单是评审者持有（reviewer-owned）的需求质量评审产物：只有当评审者认定某条需求质量准则被满足时才把条目标记为 [x]。已勾选的自定义条目不代表实现工作已完成：

/speckit.checklist

Step 6：/speckit.tasks — 拆解工作

从设计产物生成可执行、按依赖排序的 tasks.md：

/speckit.tasks

从 tasks 命令模板 对应的参考文档看，任务按阶段组织：Setup、Foundational（阻塞性前置），然后每个用户故事一个阶段（按优先级排序），最后是跨切面关注的 Polish 阶段；任务在可行处会被标记为可并行执行。

Step 7：/speckit.analyze — 检查一致性

在 spec.md、plan.md、tasks.md 之间报告冲突、缺口与歧义。它是只读的——如果它标记出问题，请在源头修复后重跑，再去实现：

/speckit.analyze

Step 8：/speckit.implement — 构建

按依赖顺序执行 tasks.md 中的任务。实现前，它会读取清单（checklist）的复选框状态作为门禁：如果有任何清单项未勾选，会先询问你是否继续；它不会修改任何清单文件或其标记。内置的 checklists/requirements.md 清单由 /speckit.specify 和 /speckit.clarify 维护，而自定义清单保持评审者持有。可以一次运行构建全部内容，也可以在大型特性中按阶段逐次限定范围：

/speckit.implement

模板层面可以验证这个门禁：implement 命令模板 明确要求扫描 checklists/ 目录下所有清单文件——全部勾选为 PASS，存在未勾选项则为 FAIL，并停下来询问"Do you want to proceed with implementation anyway? (yes/no)"，且明确说明自定义清单的 [x] 只表示需求质量准则已被评审满足，不表示实现工作完成。

Step 9：/speckit.converge — 验证完整性

对照规格、计划与任务检查代码库。如果发现缺口，它会向 tasks.md 追加新任务；再运行 /speckit.implement 并重复 converge，直到它报告"已收敛"。否则就大功告成——进入评审或提交 PR：

/speckit.converge

converge 命令模板 的 frontmatter 显示，它会先调用 check-prerequisites 脚本（check-prerequisites.sh 及其 .ps1/.py 变体）并传入 --require-spec --require-tasks --include-tasks，即强制要求规格与任务文件存在，再把当前任务状态交给收敛逻辑。implement 模板类似，只要求 --require-tasks --include-tasks。

可选：把整个流程编排为工作流

Spec Kit 在初始化时会安装内置的 speckit 工作流（"Full SDD Cycle"，见 workflow.yml）。它以声明式 YAML 把 specify → plan → tasks → implement 串起来，并在 specify 之后、plan 之后各插入一个 gate 步骤（approve/reject，拒绝即中止），对应短路径流程的人工评审点。工作流要求 speckit_version >= 0.8.5，integration 输入默认 auto（使用项目初始化时的集成），scope 可取 full / backend-only / frontend-only。

关键原则

• 显式表达你要构建什么、为什么
• 在规格阶段不要聚焦技术栈（技术栈属于 /speckit.plan）
• 在实现之前迭代打磨规格
• 在开始编码前验证需求与计划
• 让编码 Agent 处理实现细节

深入阅读

• Agentic SDD 参考：每个 /speckit.* 命令的完整参考——参数、产物、分阶段实现方式以及它们如何交互
• 完整方法论：对 Spec-Driven Development 的深入指导
• 对比 核心模板 与 社区实战走查，看规格驱动开发在真实项目中的用法
• 安装细节：uv 安装、pipx 安装、PyPI 安装、一次性 uvx 运行