Spec Kit 使用指南

Spec Kit 是 GitHub 开源的一套规范驱动开发（Spec-Driven Development）工具包，通过结构化的规范文档约束 AI 编码代理的输出，将需求、方案、任务形成可追溯的文档链。

一、项目简介

在 AI 辅助编码的场景中，一个常见的问题是：开发者用自然语言描述需求，AI 直接生成代码，中间缺少结构化的需求文档作为约束。当需求变更或需要复查时，只能重新阅读代码，缺乏可追溯的规范依据。

Spec Kit 的解决思路是规范驱动开发（Spec-Driven Development, SDD）：将规范文档作为主要产物，代码由规范生成。开发团队聚焦于"做什么"和"为什么做"，AI 编码代理负责"怎么做"。

核心组件

组件	说明
Specify CLI (`specify`)	Python 命令行工具，用于初始化项目和管理扩展
模板系统	规范的 Markdown 模板，约束 AI 输出格式
斜杠命令	在 AI 编码代理中使用的 `/speckit.*` 命令
扩展/预设/工作流/捆绑包	插件化架构，支持自定义工作流

工作流概览

/speckit.constitution   →   制定项目章程与原则
       ↓
/speckit.specify        →   编写功能规范（关注"做什么"，不关注技术栈）
       ↓
/speckit.clarify        →   澄清模糊需求（可选，但推荐）
       ↓
/speckit.plan           →   制定技术实现方案（指定技术栈）
       ↓
/speckit.checklist      →   生成质量检查清单（可选，但推荐）
       ↓
/speckit.tasks          →   拆解为可执行任务
       ↓
/speckit.analyze        →   跨产物一致性分析（可选，但推荐）
       ↓
/speckit.implement      →   执行实现

二、环境要求

依赖	说明
操作系统	Linux / macOS / Windows
Python	3.11 或更高版本
Git	用于版本控制
uv 或 pipx	Python 包管理工具（推荐使用 uv）
AI 编码代理	如 Claude Code、GitHub Copilot、Gemini CLI、Codex CLI 等

Spec Kit 支持 30+ 种 AI 编码代理，包括 Claude Code、GitHub Copilot、Gemini CLI、Codex CLI、Cursor、Windsurf、Cline 等。

三、安装方式

3.1 安装 uv（推荐）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

3.2 持久安装 Spec Kit

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

安装后可直接使用 specify 命令：

specify --version

3.3 一次性使用（无需安装）

uvx --from git+https://github.com/github/spec-kit.git specify init <项目名称>

3.4 使用 pipx 安装

pipx install git+https://github.com/github/spec-kit.git

3.5 验证安装

specify version

四、初始化项目

4.1 基本用法

# 创建新目录并初始化
specify init my-project --integration claude

# 在当前目录初始化
specify init --here --integration claude

# 强制合入已有目录（跳过确认）
specify init --here --force --integration claude

4.2 指定 AI 编码代理

specify init my-project --integration claude      # Claude Code
specify init my-project --integration copilot     # GitHub Copilot
specify init my-project --integration gemini      # Gemini CLI
specify init my-project --integration codex       # Codex CLI
specify init my-project --integration codex --integration-options="--skills"

4.3 指定脚本类型

specify init my-project --integration claude --script sh    # Bash 脚本
specify init my-project --integration claude --script ps    # PowerShell 脚本

4.4 跳过代理工具检查

specify init my-project --integration claude --ignore-agent-tools

4.5 初始化后的项目结构

my-project/
├── .specify/
│   ├── memory/
│   │   └── constitution.md      # 项目章程（初始为空）
│   ├── scripts/
│   │   └── bash/                # 自动化脚本
│   │       ├── check-prerequisites.sh
│   │       ├── common.sh
│   │       ├── create-new-feature.sh
│   │       ├── setup-plan.sh
│   │       └── setup-tasks.sh
│   └── templates/               # SDD 模板文件
│       ├── spec-template.md
│       ├── plan-template.md
│       └── tasks-template.md
├── specs/                       # 规范文档目录
│   └── .gitkeep
└── CLAUDE.md                    # 代理上下文文件（适用于 Claude Code）

五、核心工作流程

5.1 `/speckit.constitution` — 制定项目章程

定义项目的核心原则和开发准则，所有后续 AI 生成内容都必须遵循。

/speckit.constitution This project follows a "Library-First" approach.
All features must be implemented as standalone libraries first.
We use TDD strictly. We prefer functional programming patterns.

输出：.specify/memory/constitution.md，包含项目治理原则。

5.2 `/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.

自动完成的操作：

扫描已有规范，自动确定下一个功能编号（如 001、002）
根据描述创建语义化的 Git 分支（如 001-photo-albums）
基于模板生成规范文档
创建 specs/[分支名]/ 目录结构

输出：

specs/001-photo-albums/
└── spec.md         # 功能规范文档

5.3 `/speckit.clarify` — 澄清需求（可选）

在制定技术方案之前，识别并解决规范中的模糊之处。

/speckit.clarify Focus on security and performance requirements.

该命令会通过结构化问答方式，逐项覆盖规范中的模糊区域，并将澄清内容记录在规范的 Clarifications 章节中。

快速实验或探索性原型可以跳过此步骤，但需明确告知代理。

5.4 `/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.

输出：

specs/001-photo-albums/
├── spec.md
├── plan.md           # 实现方案
├── data-model.md     # 数据模型
├── research.md       # 技术调研
├── quickstart.md     # 快速启动指南
└── contracts/
    ├── api-spec.json # API 契约
    └── ...

5.5 `/speckit.checklist` — 生成质量检查清单（可选）

生成定制的质量检查清单，验证需求的完整性、清晰度和一致性。

/speckit.checklist

5.6 `/speckit.tasks` — 拆解为任务

将实现方案拆解为具体、可执行的任务列表。

/speckit.tasks

输出：tasks.md，包含：

按用户故事组织的任务拆解
任务依赖关系管理
可并行执行的任务标记 [P]
文件路径规格说明
检查点验证

5.7 `/speckit.analyze` — 一致性分析（可选）

在实现之前，检查规范、方案、任务三者之间的一致性，发现遗漏或矛盾。

/speckit.analyze

建议在实现前执行一次，实现后可作为额外复查再次执行。

5.8 `/speckit.implement` — 执行实现

按照方案和任务列表，自动执行所有实现步骤。

/speckit.implement

自动完成的操作：

验证前提条件（章程、规范、方案、任务是否就绪）
从 tasks.md 解析任务列表
按正确顺序执行任务，尊重依赖关系和并行标记
遵循 TDD 方式（如果任务列表中有测试要求）
提供进度更新并处理错误

六、CLI 命令参考

6.1 核心命令

命令	说明
`specify init [项目名]`	初始化新项目
`specify check`	检查已安装的工具和代理
`specify version`	显示版本信息
`specify --version` / `specify -V`	快速查看版本

`specify init` 选项

选项	说明
`--integration <key>`	指定 AI 编码代理（如 `claude`、`copilot`、`gemini`）
`--integration-options`	代理的附加选项
`--script sh\|ps`	脚本类型：bash 或 PowerShell
`--here`	在当前目录初始化
`--force`	强制合入已有目录
`--ignore-agent-tools`	跳过代理工具检查
`--preset <id>`	初始化时安装预设

6.2 自我管理命令

命令	说明
`specify self check`	检查是否有新版本（只读，不修改）
`specify self upgrade`	升级到最新版本
`specify self upgrade --dry-run`	预览升级操作
`specify self upgrade --tag vX.Y.Z`	升级到指定版本

6.3 扩展管理

命令	说明
`specify extension search`	搜索可用扩展
`specify extension list`	列出已安装扩展
`specify extension add <名称>`	安装扩展
`specify extension remove <名称>`	移除扩展
`specify extension info <名称>`	查看扩展详情
`specify extension enable <名称>`	启用扩展
`specify extension disable <名称>`	禁用扩展
`specify extension update <名称>`	更新扩展
`specify extension set-priority <名称> <优先级>`	设置扩展优先级

6.4 预设管理

命令	说明
`specify preset search`	搜索可用预设
`specify preset list`	列出已安装预设
`specify preset add <名称>`	安装预设
`specify preset remove <名称>`	移除预设
`specify preset info <名称>`	查看预设详情
`specify preset resolve`	解析预设优先级

6.5 工作流管理

命令	说明
`specify workflow list`	列出工作流
`specify workflow run <名称>`	运行工作流
`specify workflow resume <名称>`	恢复暂停的工作流
`specify workflow status <名称>`	查看工作流状态
`specify workflow add <名称>`	添加工作流
`specify workflow remove <名称>`	移除工作流
`specify workflow search`	搜索工作流
`specify workflow info <名称>`	查看工作流详情
`specify workflow step <名称>`	查看工作流步骤

6.6 捆绑包管理

命令	说明
`specify bundle search [查询]`	搜索可用捆绑包
`specify bundle list`	列出已安装捆绑包
`specify bundle install <ID>`	安装捆绑包
`specify bundle remove <ID>`	移除捆绑包
`specify bundle update <ID>`	更新捆绑包
`specify bundle update --all`	更新所有捆绑包
`specify bundle info <ID>`	查看捆绑包详情
`specify bundle validate --path <路径>`	验证捆绑包结构
`specify bundle build --path <路径>`	构建捆绑包
`specify bundle catalog list`	查看目录栈
`specify bundle catalog add <URL>`	添加目录源
`specify bundle catalog remove <URL>`	移除目录源

七、扩展、预设与捆绑包

7.1 扩展（Extensions）

为 Spec Kit 添加新功能，如集成外部工具、添加领域特定命令等。

specify extension search        # 搜索可用扩展
specify extension info <名称>   # 查看扩展详情
specify extension add <名称>    # 安装扩展

内置扩展：

git — Git 工作流集成
agent-context — 代理上下文管理
bug — Bug 修复工作流

7.2 预设（Presets）

在不添加新功能的前提下，自定义 Spec Kit 的工作方式。可以覆盖模板、命令文件等。

specify preset search        # 搜索可用预设
specify preset add <名称>    # 安装预设

预设优先级（从高到低）：

项目本地覆盖（.specify/templates/overrides/）
已安装的预设（.specify/presets/templates/）
已安装的扩展（.specify/extensions/templates/）
Spec Kit 核心模板（.specify/templates/）

7.3 捆绑包（Bundles）

将扩展、预设、工作流打包成一个完整的角色配置，一键安装。

specify bundle search              # 搜索可用捆绑包
specify bundle info <捆绑包ID>     # 查看捆绑包详情
specify bundle install <捆绑包ID>  # 安装捆绑包
specify bundle list                # 查看已安装的捆绑包
specify bundle update <捆绑包ID>   # 更新捆绑包
specify bundle remove <捆绑包ID>   # 移除捆绑包

内置捆绑包示例：

product-manager — 产品经理角色
business-analyst — 业务分析师角色
security-researcher — 安全研究员角色
developer — 开发人员角色

7.4 选型指南

目标	使用方式
添加新命令或工作流	扩展
自定义规范/方案/任务的格式	预设
集成外部工具或服务	扩展
强制组织或法规标准	预设
一键配置完整角色	捆绑包

八、完整示例

以下以构建一个名为 Taskify 的团队协作平台为例，演示完整的 SDD 流程。

8.1 初始化项目

specify init taskify --integration claude
cd taskify

8.2 制定章程

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

8.3 编写规范

/speckit.specify Develop Taskify, a team productivity platform.
It should allow users to create projects, add team members, assign tasks,
comment and move tasks between boards in Kanban style. In this initial phase,
let's have multiple users but the users will be declared ahead of time,
predefined. I want five users in two different categories, one product manager
and four engineers. Let's create three different sample projects. Let's have
the standard Kanban columns for the status of each task, such as "To Do,"
"In Progress," "In Review," and "Done." There will be no login for this
application as this is just the very first testing thing to ensure that our
basic features are set up.

8.4 澄清需求

/speckit.clarify I want to clarify the task card details. For each task in
the UI for a task card, you should be able to change the current status of
the task between the different columns in the Kanban work board. You should
be able to leave an unlimited number of comments for a particular card.
You should be able to, from that task card, assign one of the valid users.

8.5 制定技术方案

/speckit.plan We are going to generate this using .NET Aspire, using Postgres
as the database. The frontend should use Blazor server with drag-and-drop
task boards, real-time updates. There should be a REST API created with a
projects API, tasks API, and a notifications API.

8.6 生成检查清单

/speckit.checklist

8.7 拆解任务

/speckit.tasks

8.8 一致性分析

/speckit.analyze

8.9 执行实现

/speckit.implement

九、常见问题

9.1 如何切换功能？

Spec Kit 根据当前 Git 分支名自动检测活动功能（如 001-feature-name）。要切换功能，只需切换 Git 分支即可。

9.2 如何更新 CLI？

specify self check              # 检查新版本（只读）
specify self upgrade --dry-run  # 预览升级操作
specify self upgrade            # 执行升级

9.3 环境变量

变量	说明
`SPECIFY_INIT_DIR`	指定项目根目录（用于 monorepo 场景）
`SPECIFY_FEATURE_DIRECTORY`	覆盖当前活动功能目录
`SPECIFY_FEATURE`	非 Git 仓库中指定功能目录名
`SPECIFY_UPGRADE_TIMEOUT_SECS`	升级超时时间（秒）

9.4 如何分阶段实现复杂项目？

对于大型项目，建议分阶段实现，避免代理上下文溢出。先实现核心功能，验证通过后再增量添加功能。

9.5 如何安装 Git 扩展以启用 Git 工作流？

specify extension add git

9.6 如何切换 AI 编码代理？

specify integration list                # 查看可用代理
specify integration use <代理名称>      # 切换代理

适用场景

适用：

从零开始的新项目，需要统一的规范文档体系
团队协作场景，规范文档需要 review 和版本管理
需要 AI 生成代码具备可追溯性的场景

不适用：

单行修复或小型改动（流程开销大于收益）
已有大型存量代码库且不打算补写历史规范（可考虑 OpenSpec 等增量方案）

相关资源：

GitHub 仓库

官方文档

SDD 方法论详解

贡献指南

posted @ 2026-08-19 17:12 起飞的乌龟阅读(106) 评论(0) 收藏举报

刷新页面返回顶部

knight-gjf

Spec Kit 使用指南

Spec Kit 使用指南

一、项目简介

核心组件

工作流概览

二、环境要求

三、安装方式

3.1 安装 uv（推荐）

3.2 持久安装 Spec Kit

3.3 一次性使用（无需安装）

3.4 使用 pipx 安装

3.5 验证安装

四、初始化项目

4.1 基本用法

4.2 指定 AI 编码代理

4.3 指定脚本类型

4.4 跳过代理工具检查

4.5 初始化后的项目结构

五、核心工作流程

5.1 /speckit.constitution — 制定项目章程

5.2 /speckit.specify — 创建功能规范

5.3 /speckit.clarify — 澄清需求（可选）

5.4 /speckit.plan — 制定技术方案

5.5 /speckit.checklist — 生成质量检查清单（可选）

5.6 /speckit.tasks — 拆解为任务

5.7 /speckit.analyze — 一致性分析（可选）

5.8 /speckit.implement — 执行实现

六、CLI 命令参考

6.1 核心命令

specify init 选项

6.2 自我管理命令

6.3 扩展管理

6.4 预设管理

6.5 工作流管理

6.6 捆绑包管理

七、扩展、预设与捆绑包

7.1 扩展（Extensions）

7.2 预设（Presets）

7.3 捆绑包（Bundles）

7.4 选型指南

八、完整示例

8.1 初始化项目

8.2 制定章程

8.3 编写规范

8.4 澄清需求

8.5 制定技术方案

8.6 生成检查清单

8.7 拆解任务

8.8 一致性分析

8.9 执行实现

九、常见问题

9.1 如何切换功能？

9.2 如何更新 CLI？

9.3 环境变量

9.4 如何分阶段实现复杂项目？

9.5 如何安装 Git 扩展以启用 Git 工作流？

9.6 如何切换 AI 编码代理？

适用场景

公告

5.1 `/speckit.constitution` — 制定项目章程

5.2 `/speckit.specify` — 创建功能规范

5.3 `/speckit.clarify` — 澄清需求（可选）

5.4 `/speckit.plan` — 制定技术方案

5.5 `/speckit.checklist` — 生成质量检查清单（可选）

5.6 `/speckit.tasks` — 拆解为任务

5.7 `/speckit.analyze` — 一致性分析（可选）

5.8 `/speckit.implement` — 执行实现

`specify init` 选项