Spec-kit 工具套件

🤔 什么是规范驱动开发（Spec-Driven Development）？

规范驱动开发彻底颠覆了传统软件开发模式。数十年来，代码一直占据核心地位——而规格说明书不过是我们搭建的临时框架，一旦真正的编码工作开始，就会被抛之脑后。规范驱动开发改变了这一现状：规格说明具备可执行性，不再仅仅是开发指引，而是能直接生成可运行的实现代码。

⚡ 快速开始

1. 安装 Specify 命令行工具（CLI）

选择你偏好的安装方式：

方式一：持久化安装（推荐）

一次安装，全局可用：

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

安装后即可直接使用该工具：

specify init <项目名称>
specify check

如需升级 Specify 工具，请查看《升级指南》获取详细说明。快速升级命令：

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

方式二：一次性使用

无需安装，直接运行：

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

持久化安装的优势：

• 工具常驻系统，可在系统环境变量（PATH）中全局调用
• 无需创建 Shell 别名
• 可通过 uv tool list、uv tool upgrade、uv tool uninstall 便捷管理工具
• 简化 Shell 配置，避免冗余

2. 确立项目准则

在项目目录中启动你的 AI 辅助工具，助手将支持 /speckit.* 系列命令。

使用 /speckit.constitution 命令创建项目的核心治理准则和开发规范，这些内容将指导后续所有开发工作：

/speckit.constitution 制定以代码质量、测试标准、用户体验一致性和性能要求为核心的项目准则

3. 创建规格说明

使用 /speckit.specify 命令描述你想要构建的功能，重点说明要实现什么和为什么要实现，而非具体技术栈：

/speckit.specify 开发一款可帮助我将照片整理到不同相册的应用。相册按日期分组，可在主页面通过拖放方式重新整理。相册不支持嵌套层级。每个相册内的照片以平铺卡片式界面展示预览。

4. 制定技术实现方案

使用 /speckit.plan 命令明确技术栈和架构选型：

/speckit.plan 该应用基于 Vite 构建，尽可能减少第三方库依赖。优先使用原生 HTML、CSS 和 JavaScript 开发。图片不上传至任何服务器，元数据存储在本地 SQLite 数据库中。

5. 拆解任务

使用 /speckit.tasks 命令将实现方案拆解为可执行的任务列表：

/speckit.tasks

6. 执行开发实现

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

/speckit.implement

如需详细的分步操作指南，请查阅《完整使用指南》。

📽️ 视频介绍

想直观了解 Spec Kit 的使用流程？观看我们的视频介绍！

🤖 支持的 AI 智能体

智能体名称	支持状态	备注
Qoder CLI	✅ 支持
Amazon Q Developer CLI	⚠️ 部分支持	Amazon Q Developer CLI 不支持 为斜杠命令配置自定义参数。
Amp	✅ 支持
Auggie CLI	✅ 支持
Claude Code	✅ 支持
CodeBuddy CLI	✅ 支持
Codex CLI	✅ 支持
Cursor	✅ 支持
Gemini CLI	✅ 支持
GitHub Copilot	✅ 支持
IBM Bob	✅ 支持	基于 IDE 的智能体，支持斜杠命令
Jules	✅ 支持
Kilo Code	✅ 支持
opencode	✅ 支持
Qwen Code	✅ 支持
Roo Code	✅ 支持
SHAI (OVHcloud)	✅ 支持
Windsurf	✅ 支持

🔧 Specify CLI 参考手册

specify 命令支持以下选项：

核心命令

命令	说明
init	从最新模板初始化新的 Specify 项目
check	检查已安装的工具（git、claude、gemini、code/code-insiders、cursor-agent、windsurf、qwen、opencode、codex、shai、qoder）

specify init 参数与选项

参数/选项	类型	说明
<project-name>	必选参数	新项目目录名称（若使用 --here 则可选，或使用 . 表示当前目录）
--ai	可选参数	指定使用的 AI 辅助工具：claude、gemini、copilot、cursor-agent、qwen、opencode、codex、windsurf、kilocode、auggie、roo、codebuddy、amp、shai、q、bob 或 qoder
--script	可选参数	指定脚本类型：sh（bash/zsh）或 ps（PowerShell）
--ignore-agent-tools	标志参数	跳过对 AI 智能体工具（如 Claude Code）的检查
--no-git	标志参数	跳过 Git 仓库初始化
--here	标志参数	在当前目录初始化项目，不创建新目录
--force	标志参数	在当前目录初始化时强制合并/覆盖文件（跳过确认步骤）
--skip-tls	标志参数	跳过 SSL/TLS 验证（不推荐使用）
--debug	标志参数	启用详细调试输出，便于故障排查
--github-token	可选参数	用于 API 请求的 GitHub 令牌（也可通过设置 GH_TOKEN/GITHUB_TOKEN 环境变量实现）

使用示例

# 基础项目初始化
specify init my-project

# 指定 AI 辅助工具初始化
specify init my-project --ai claude

# 初始化支持 Cursor 的项目
specify init my-project --ai cursor-agent

# 初始化支持 Qoder 的项目
specify init my-project --ai qoder

# 初始化支持 Windsurf 的项目
specify init my-project --ai windsurf

# 初始化支持 Amp 的项目
specify init my-project --ai amp

# 初始化支持 SHAI 的项目
specify init my-project --ai shai

# 初始化支持 IBM Bob 的项目
specify init my-project --ai bob

# 使用 PowerShell 脚本初始化（Windows/跨平台）
specify init my-project --ai copilot --script ps

# 在当前目录初始化
specify init . --ai copilot
# 或使用 --here 标志
specify init --here --ai copilot

# 强制合并到当前非空目录（无需确认）
specify init . --force --ai copilot
# 或
specify init --here --force --ai copilot

# 跳过 Git 初始化
specify init my-project --ai gemini --no-git

# 启用调试输出排查问题
specify init my-project --ai claude --debug

# 使用 GitHub 令牌进行 API 请求（适用于企业环境）
specify init my-project --ai claude --github-token ghp_your_token_here

# 检查系统依赖
specify check

可用的斜杠命令

运行 specify init 后，你的 AI 编码助手将支持以下结构化开发斜杠命令：

核心命令

规范驱动开发流程的必备命令：

命令	说明
/speckit.constitution	创建或更新项目治理准则与开发规范
/speckit.specify	定义待开发功能（需求与用户故事）
/speckit.plan	结合选定技术栈制定技术实现方案
/speckit.tasks	生成可执行的开发任务列表
/speckit.implement	执行所有任务，按方案构建功能

可选命令

提升开发质量与验证能力的扩展命令：

命令	说明
/speckit.clarify	澄清规格说明中描述不清晰的部分（建议在 /speckit.plan 前使用；原 /quizme 命令）
/speckit.analyze	跨工件一致性与覆盖度分析（在 /speckit.tasks 后、/speckit.implement 前运行）
/speckit.checklist	生成自定义质量检查清单，验证需求的完整性、清晰度和一致性（如“英文版本单元测试”）

环境变量

变量名	说明
SPECIFY_FEATURE	为非 Git 仓库覆盖功能检测逻辑。设置为功能目录名称（如 001-photo-albums），可在不使用 Git 分支时专注开发特定功能。 使用要求：必须在调用 /speckit.plan 或后续命令前，在所用智能体的运行环境中配置该变量。

📚 核心理念

规范驱动开发是一套结构化流程，核心强调：

• 意图驱动开发：先通过规格说明定义“要做什么”，再确定“怎么做”
• 高质量规格创建：基于约束规则和组织准则编写完善的规格说明
• 多阶段精细化：摒弃单次提示词生成代码的方式，采用分阶段迭代优化
• 深度依赖 AI 能力：依托先进 AI 模型的规格解读能力完成开发

🌟 开发阶段

阶段	核心目标	关键活动
从0到1开发（全新项目）	从零构建完整应用	从高层级需求出发 生成标准化规格说明 规划实现步骤 构建生产级可用应用
创新探索阶段	多方案并行实现	探索多样化解决方案 支持多技术栈与架构选型 试验不同用户体验模式
迭代增强阶段（存量项目）	存量系统现代化改造	迭代式新增功能 改造遗留系统 适配优化开发流程

🎯 实验目标

我们的研究与实验聚焦于以下方向：

技术无关性

• 支持基于不同技术栈开发应用
• 验证规范驱动开发是一套独立于具体技术、编程语言或框架的通用流程

企业级约束适配

• 演示关键业务系统的开发能力
• 融入企业级约束条件（云服务商、技术栈、工程规范）
• 支持企业级设计系统与合规要求

以用户为中心的开发

• 面向不同用户群体和使用偏好构建应用
• 适配多种开发模式（从自由编码到 AI 原生开发）

创新与迭代流程

• 验证并行实现方案探索的可行性
• 提供健壮的迭代式功能开发流程
• 扩展流程以支持系统升级与现代化改造

🔧 前置条件

• 操作系统：Linux/macOS/Windows
• AI 工具：支持上述列表中的任意一款 AI 编码智能体
• 包管理工具：uv
• Python 版本：3.11 及以上（下载地址）
• 版本控制：Git

若使用某款智能体时遇到问题，请提交 issue 帮助我们优化集成方案。

📖 更多学习资源

• 规范驱动开发完整方法论 - 深入理解全流程细节
• 详细操作指南 - 分步实现教程

---

📋 详细流程

点击展开详细分步操作指南

你可以使用 Specify CLI 快速搭建项目基础框架，该工具会在你的开发环境中生成所需文件。执行以下命令：

specify init <项目名称>

或在当前目录初始化：

specify init .
# 或使用 --here 标志
specify init --here
# 目录已有文件时跳过确认步骤
specify init . --force
# 或
specify init --here --force

工具会提示你选择所用的 AI 智能体，也可直接在命令中指定：

specify init <项目名称> --ai claude
specify init <项目名称> --ai gemini
specify init <项目名称> --ai copilot

# 或在当前目录初始化：
specify init . --ai claude
specify init . --ai codex

# 或使用 --here 标志
specify init --here --ai claude
specify init --here --ai codex

# 强制合并到非空当前目录
specify init . --force --ai claude

# 或
specify init --here --force --ai claude

CLI 会检查是否已安装 Claude Code、Gemini CLI、Cursor CLI、Qwen CLI、opencode、Codex CLI、Qoder CLI 或 Amazon Q Developer CLI。若未安装，或你希望仅获取模板而跳过工具检查，可在命令中添加 --ignore-agent-tools：

specify init <项目名称> --ai claude --ignore-agent-tools

第一步：确立项目准则

进入项目文件夹并启动 AI 智能体（本文以 claude 为例）。

若能看到 /speckit.constitution、/speckit.specify、/speckit.plan、/speckit.tasks 和 /speckit.implement 命令可用，说明配置成功。

首要步骤是通过 /speckit.constitution 命令确立项目治理准则，确保后续所有开发阶段的决策保持一致：

/speckit.constitution 制定以代码质量、测试标准、用户体验一致性和性能要求为核心的项目准则。包含准则如何指导技术决策和实现选型的治理规则。

该步骤会在 .specify/memory/constitution.md 文件中创建/更新项目基础规范，AI 智能体在规格编写、方案规划和开发实现阶段都会参考这些内容。

第二步：创建项目规格说明

确立项目准则后，即可编写功能规格说明。使用 /speckit.specify 命令，并提供待开发项目的具体需求。

[!重要提示]
尽可能清晰说明要构建什么和为什么构建。此阶段无需关注技术栈。

示例提示词：

开发团队生产力平台 Taskify。支持用户创建项目、添加团队成员、分配任务、添加评论，并以看板（Kanban）形式在不同面板间移动任务。
该功能初始版本（命名为「创建 Taskify」）支持多用户，但用户需预先定义。
设置5个用户，分为两类：1名产品经理和4名工程师。创建3个示例项目。
为每个任务状态设置标准看板列：「待办」「进行中」「审核中」「已完成」。
该应用暂不实现登录功能，仅验证基础功能是否正常。
任务卡片UI需支持修改任务状态（在不同看板列间切换）、添加无限条评论、分配指定用户。
启动 Taskify 时显示5个预设用户列表（无需密码），点击用户后进入项目列表主视图，
点击项目打开对应看板，可拖放任务卡片在不同列间移动。
当前登录用户的任务卡片需用不同颜色高亮显示，便于快速识别。
用户可编辑/删除自己的评论，但无法修改他人评论。

输入该提示词后，Claude Code 会启动规划和规格起草流程，并触发内置脚本完成代码库初始化。

完成后会创建新分支（如 001-create-taskify），并在 specs/001-create-taskify 目录生成规格说明文件。

生成的规格说明应包含模板中定义的用户故事和功能需求。

此时项目目录结构如下：

└── .specify
    ├── memory
    │  └── constitution.md
    ├── scripts
    │  ├── check-prerequisites.sh
    │  ├── common.sh
    │  ├── create-new-feature.sh
    │  ├── setup-plan.sh
    │  └── update-claude-md.sh
    ├── specs
    │  └── 001-create-taskify
    │      └── spec.md
    └── templates
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

第三步：功能规格澄清（规划前必做）

基础规格说明完成后，需澄清首次编写时未完善的需求点。

在制定技术方案前，应执行结构化澄清流程，减少后续返工：

推荐流程：

1. 使用 /speckit.clarify（结构化）—— 按顺序进行覆盖式提问，答案记录在「澄清说明」章节
2. 若仍有模糊点，可补充自由形式的细化提问

若有意跳过澄清步骤（如快速原型开发），需明确告知智能体，避免因缺少澄清信息导致流程阻塞。

示例自由形式细化提示词（在 /speckit.clarify 后补充）：

每个示例项目需包含5-15个任务，随机分配至不同完成状态，且每个状态至少包含1个任务。

还可要求 Claude Code 验证「评审与验收清单」，勾选符合要求的项，未满足项留空：

阅读评审与验收清单，若功能规格满足对应标准则勾选，未满足项保持空白。

需注意：应将与 Claude Code 的交互作为澄清和质询规格的机会——切勿将首次生成结果视为最终版本。

第四步：生成实现方案

此时可明确技术栈和其他技术要求，使用项目模板内置的 /speckit.plan 命令，示例提示词：

基于 .NET Aspire 框架开发，使用 Postgres 数据库。前端采用 Blazor Server 实现拖放式任务看板和实时更新功能。
需创建 REST API，包含项目 API、任务 API 和通知 API。

该步骤会生成多个实现细节文档，目录结构如下：

.
├── CLAUDE.md
├── memory
│  └── constitution.md
├── scripts
│  ├── check-prerequisites.sh
│  ├── common.sh
│  ├── create-new-feature.sh
│  ├── setup-plan.sh
│  └── update-claude-md.sh
├── specs
│  └── 001-create-taskify
│      ├── contracts
│      │  ├── api-spec.json
│      │  └── signalr-spec.md
│      ├── data-model.md
│      ├── plan.md
│      ├── quickstart.md
│      ├── research.md
│      └── spec.md
└── templates
    ├── CLAUDE-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

检查 research.md 文档，确认技术栈符合要求；若有偏差，可要求 Claude Code 修正，或验证本地安装的框架版本（如 .NET）。

若所选技术栈迭代较快（如 .NET Aspire、前端 JS 框架），可要求 Claude Code 补充相关调研：

梳理实现方案和细节，找出因 .NET Aspire 快速迭代需补充调研的部分。
针对这些部分，更新调研文档，明确 Taskify 应用使用的具体版本，并生成并行调研任务，通过网络调研澄清细节。

过程中若发现 Claude Code 调研方向偏差，可引导其聚焦具体问题：

建议拆解为以下步骤：
1. 列出实现过程中不确定或需深入调研的任务
2. 为每个任务生成独立调研项，确保所有具体问题都能并行调研
此前观察到你在泛化调研 .NET Aspire，这对当前场景帮助有限，调研需聚焦具体问题。

[!注意]
Claude Code 可能会主动添加未要求的组件，需要求其说明新增理由和依据。

第五步：验证实现方案

方案完成后，需让 Claude Code 审核完整性：

审核实现方案和细节文档，梳理明确的任务执行顺序（当前文档可能不够清晰）。
例如，在核心实现部分，需关联实现细节中对应信息的位置。

这一步可优化实现方案，避免 Claude Code 在规划阶段遗漏潜在问题。初步优化后，再次要求其核对清单，确认无误后进入开发阶段。

若已安装 GitHub CLI，可要求 Claude Code 从当前分支向 main 分支创建 Pull Request 并添加详细描述，确保开发过程可追溯。

[!注意]
在执行开发前，建议要求 Claude Code 交叉检查方案，确认是否存在过度设计的部分（智能体可能存在此类倾向）。
若存在过度设计，需要求其修正，并确保方案严格遵循项目准则。

第六步：使用 /speckit.tasks 生成任务拆解

验证实现方案后，可将其拆解为具体可执行的任务（按正确顺序）。
使用 /speckit.tasks 命令从实现方案自动生成详细任务清单：

/speckit.tasks

该步骤会在功能规格目录中创建 tasks.md 文件，包含：

• 按用户故事组织的任务拆解 - 每个用户故事对应独立实现阶段及任务
• 依赖管理 - 任务按组件依赖关系排序（如先模型、后服务、再接口）
• 并行执行标记 - 可并行执行的任务标注 [P]，优化开发流程
• 文件路径指定 - 每个任务明确实现对应的文件路径
• 测试驱动开发结构 - 若要求编写测试，测试任务会前置安排
• 检查点验证 - 每个用户故事阶段包含独立功能验证检查点

生成的 tasks.md 为 /speckit.implement 命令提供清晰执行路线，确保开发过程系统化，兼顾代码质量与用户故事的增量交付。

第七步：执行开发实现

准备就绪后，使用 /speckit.implement 命令执行实现方案：

/speckit.implement

该命令会：

• 验证前置条件（项目准则、规格说明、实现方案、任务清单）是否完备
• 解析 tasks.md 中的任务拆解
• 按正确顺序执行任务，遵循依赖关系和并行标记
• 按照任务计划中的 TDD 流程开发
• 实时反馈进度，并妥善处理执行错误

[!重要提示]
AI 智能体会执行本地 CLI 命令（如 dotnet、npm 等）—— 请确保本地已安装所需工具。

开发完成后，需测试应用并修复 CLI 日志中未显示的运行时错误（如浏览器控制台错误），可将错误信息复制给 AI 智能体协助解决。

---

🔍 故障排除

Linux 系统下的 Git 凭据管理器问题

若在 Linux 系统中遇到 Git 认证问题，可安装 Git 凭据管理器：

#!/usr/bin/env bash
set -e
echo "正在下载 Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "正在安装 Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "配置 Git 使用 GCM..."
git config --global credential.helper manager
echo "清理安装文件..."
rm gcm-linux_amd64.2.6.1.deb