user — -zsh — 80x24
specify
███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝ 
╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝  
███████║██║     ███████╗╚██████╗██║██║        ██║   
╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝   
GitHub Spec Kit - Spec-Driven Development Toolkit
Run 'specify --help' for usage information
~/project specify init

🌱 Spec Kit 规范驱动开发套件

更快地构建高质量软件 Build high-quality software faster

这是一款开源的工具套件,它使您能够聚焦于产品场景与可预测的成果,而非从零开始进行 vibe coding。

Release GitHub stars License Documentation


🤔 何为规范驱动开发 (Spec-Driven Development)?

规范驱动开发(Spec-Driven Development)颠覆了传统软件开发的既定范式。数十年来,“代码为王”的理念始终占据主导地位——规范(Specifications)曾一度被视为临时脚手架,一旦所谓的“真正”编码工作开始,便被弃之不用。 规范驱动开发则彻底扭转了这一局面:规范本身成为一种“可执行”的资产,它能够直接生成可工作的实现(Implementations),其角色不再仅仅是提供指导。

⚡ 快速开始 (Get Started)

1. 安装 Specify CLI

选择你喜欢的安装方式:

选项 1: 持久化安装 (推荐)

一次安装,随处使用:

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

然后直接使用该工具:

specify init <PROJECT_NAME>
specify check

要升级 Specify,请查看 升级指南 (Upgrade Guide) 获取详细说明。 快速升级:

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

选项 2: 一次性使用

无需安装直接运行:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

持久化安装的好处:

2. 建立项目原则 (Establish project principles)

在项目目录中启动你的 AI 助手 (AI assistant)。助手可以使用 /speckit.* 命令。

使用 /speckit.constitution 命令创建项目的管理原则和开发指南,这将指导后续的所有开发工作。

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

3. 创建规范 (Create the spec)

使用 /speckit.specify 命令描述你想构建的内容。关注于 what (做什么)why (为什么),而不是技术栈。

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

4. 创建技术实施计划 (Create a technical implementation plan)

使用 /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.

5. 分解任务 (Break down into tasks)

使用 /speckit.tasks 根据实施计划创建一个可执行的任务列表。

/speckit.tasks

6. 执行实施 (Execute implementation)

使用 /speckit.implement 执行所有任务并根据计划构建你的功能。

/speckit.implement

有关详细的分步说明,请参阅我们的 综合指南 (comprehensive guide)

📽️ 视频概览 (Video Overview)

想看看 Spec Kit 的实际效果吗?观看我们的 视频概览

🤖 支持的 AI 代理 (Supported AI Agents)

代理 (Agent) 支持 (Support) 备注 (Notes)
Qoder CLI
Amazon Q Developer CLI ⚠️ Amazon Q Developer CLI 不支持 slash 命令的自定义参数。
Amp
Auggie CLI
Claude Code
CodeBuddy CLI
Codex CLI
Cursor
Gemini CLI
GitHub Copilot
IBM Bob 基于 IDE 的代理,支持 slash 命令
Jules
Kilo Code
opencode
Qwen Code
Roo Code
SHAI (OVHcloud)
Windsurf

🔧 Specify CLI 参考 (Specify CLI Reference)

specify 命令支持以下选项:

命令 (Commands)

命令 (Command) 描述 (Description)
init 从最新模板初始化一个新的 Specify 项目
check 检查已安装的工具 (git, claude, gemini, code/code-insiders, cursor-agent, windsurf, qwen, opencode, codex, shai, qoder)

specify init 参数与选项 (Arguments & Options)

参数/选项 (Argument/Option) 类型 (Type) 描述 (Description)
<project-name> Argument 新项目目录的名称 (如果使用 --here 则可选,或使用 . 表示当前目录)
--ai Option 使用的 AI 助手: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, bob, 或 qoder
--script Option 使用的脚本变体: sh (bash/zsh) 或 ps (PowerShell)
--ignore-agent-tools Flag 跳过对 AI 代理工具 (如 Claude Code) 的检查
--no-git Flag 跳过 git 仓库初始化
--here Flag 在当前目录初始化项目,而不是创建新目录
--force Flag 在当前目录 (非空) 初始化时强制合并/覆盖 (跳过确认)
--skip-tls Flag 跳过 SSL/TLS 验证 (不推荐)
--debug Flag 启用详细的调试输出以进行故障排除
--github-token Option 用于 API 请求的 GitHub 令牌 (或设置 GH_TOKEN/GITHUB_TOKEN 环境变量)

示例 (Examples)

# 基本项目初始化
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

可用的 Slash 命令 (Available Slash Commands)

运行 specify init 后,你的 AI 编码代理将可以使用这些 slash 命令进行结构化开发:

核心命令 (Core Commands)

规范驱动开发 (Spec-Driven Development) 工作流的基本命令:

命令 (Command) 描述 (Description)
/speckit.constitution 创建或更新项目管理原则和开发指南
/speckit.specify 定义你想构建的内容 (需求和用户故事)
/speckit.plan 使用你选择的技术栈创建技术实施计划
/speckit.tasks 生成可执行的任务列表以进行实施
/speckit.implement 执行所有任务以根据计划构建功能

可选命令 (Optional Commands)

用于增强质量和验证的附加命令:

命令 (Command) 描述 (Description)
/speckit.clarify 澄清未详细说明的领域 (建议在 /speckit.plan 之前使用;原为 /quizme)
/speckit.analyze 跨工件一致性和覆盖率分析 (在 /speckit.tasks 之后,/speckit.implement 之前运行)
/speckit.checklist 生成自定义质量检查清单,验证需求的完整性、清晰度和一致性 (如 "英语单元测试")

环境变量 (Environment Variables)

变量 (Variable) 描述 (Description)
SPECIFY_FEATURE 覆盖非 Git 仓库的功能检测。设置为功能目录名称 (例如 001-photo-albums) 以在不使用 Git 分支时处理特定功能。
**必须在使用 /speckit.plan 或后续命令之前,在与其工作的代理上下文中设置。

📚 核心理念 (Core Philosophy)

规范驱动开发 (Spec-Driven Development) 是一种结构化的流程,强调:

🌟 开发阶段 (Development Phases)

阶段 (Phase) 重点 (Focus) 关键活动 (Key Activities)
从 0 到 1 开发 (0-to-1 Development) ("Greenfield") 从头生成
  • 从高层需求开始
  • 生成规范
  • 规划实施步骤
  • 构建生产就绪的应用程序
创造性探索 (Creative Exploration) 并行实施
  • 探索多样化的解决方案
  • 支持多种技术栈和架构
  • 尝试 UX 模式
迭代增强 (Iterative Enhancement) ("Brownfield") 棕地现代化
  • 迭代添加功能
  • 现代化遗留系统
  • 调整流程

🎯 实验目标 (Experimental Goals)

我们的研究和实验重点在于:

技术独立性 (Technology independence)

企业约束 (Enterprise constraints)

以用户为中心的开发 (User-centric development)

创造性和迭代流程 (Creative & iterative processes)

🔧 先决条件 (Prerequisites)

如果你遇到代理的问题,请提交 issue 以便我们改进集成。

📖 了解更多 (Learn More)


📋 详细流程 (Detailed Process)

点击展开详细的分步演练 (Click to expand the detailed step-by-step walkthrough)

你可以使用 Specify CLI 来引导你的项目,这将在你的环境中引入所需的工件。运行:

specify init <project_name>

或者在当前目录初始化:

specify init .
# or use the --here flag
specify init --here
# Skip confirmation when the directory already has files
specify init . --force
# or
specify init --here --force

Specify CLI bootstrapping a new project in the terminal

系统会提示你选择使用的 AI 代理。你也可以直接在终端中主动指定它:

specify init <project_name> --ai claude
specify init <project_name> --ai gemini
specify init <project_name> --ai copilot

# Or in current directory:
specify init . --ai claude
specify init . --ai codex

# or use --here flag
specify init --here --ai claude
specify init --here --ai codex

# Force merge into a non-empty current directory
specify init . --force --ai claude

# or
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 <project_name> --ai claude --ignore-agent-tools

步骤 1: 建立项目原则 (Establish project principles)

进入项目文件夹并运行你的 AI 代理。在我们的示例中,我们使用 claude

Bootstrapping Claude Code environment

如果你看到 /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, 和 /speckit.implement 命令可用,则说明配置正确。

第一步应该是使用 /speckit.constitution 命令建立项目的管理原则。这有助于确保在随后的所有开发阶段中决策的一致性:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.

此步骤将创建或更新 .specify/memory/constitution.md 文件,其中包含项目的基本准则,AI 代理将在规范、规划和实施阶段参考这些准则。

步骤 2: 创建项目规范 (Create project specifications)

建立了项目原则后,你现在可以创建功能规范。使用 /speckit.specify 命令,然后提供你想开发的项目的具体需求。

[!IMPORTANT]
尽可能明确你要构建 什么 (what) 以及 为什么 (why)此时不要关注技术栈

示例提示词:

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 for this feature,
let's call it "Create Taskify," 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. 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. When you first launch Taskify, it's going to give you a list of the five users to pick
from. There will be no password required. When you click on a user, you go into the main view, which displays the list of
projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.
You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are
assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly
see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can
delete any comments that you made, but you can't delete comments anybody else made.

输入此提示词后,你应该会看到 Claude Code 启动规划和规范起草流程。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

步骤 3: 功能规范澄清 (规划前必须) (Functional specification clarification)

创建基线规范后,你可以继续澄清在第一次尝试中未正确捕获的任何需求。

你应该在创建技术计划 之前 运行结构化澄清工作流,以减少下游的返工。

首选顺序:

  1. 使用 /speckit.clarify (结构化) – 顺序的、基于覆盖率的提问,将答案记录在澄清部分。
  2. 如果仍然感觉模糊,可以选择进行后续的临时自由形式细化。

如果你想有意跳过澄清 (例如 spike 或探索性原型),请明确说明,以便代理不会因缺少澄清而阻塞。

自由形式细化提示词示例 (如果需要,在 /speckit.clarify 之后):

For each sample project or project that you create there should be a variable number of tasks between 5 and 15
tasks for each one randomly distributed into different states of completion. Make sure that there's at least
one task in each stage of completion.

你还应该要求 Claude Code 验证 审查与验收清单 (Review & Acceptance Checklist),勾选已验证/通过需求的项目,并保留未通过的项目不勾选。可以使用以下提示词:

Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.

重要的是利用与 Claude Code 的互动作为澄清和围绕规范提问的机会 - 不要将其第一次尝试视为最终结果

步骤 4: 生成计划 (Generate a plan)

你现在可以具体说明技术栈和其他技术要求。你可以使用项目模板中内置的 /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.

此步骤的输出将包含许多实施细节文档,你的目录树类似于:

.
├── 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 研究有关该技术栈的详细信息,提示词如下:

I want you to go through the implementation plan and implementation details, looking for areas that could
benefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify that
require further research, I want you to update the research document with additional details about the specific
versions that we are going to be using in this Taskify application and spawn parallel research tasks to clarify
any details using research from the web.

在此过程中,你可能会发现 Claude Code 卡在研究错误的事情上 - 你可以使用如下提示词帮助将其推向正确的方向:

I think we need to break this down into a series of steps. First, identify a list of tasks
that you would need to do during implementation that you're not sure of or would benefit
from further research. Write down a list of those tasks. And then for each one of these tasks,
I want you to spin up a separate research task so that the net results is we are researching
all of those very specific tasks in parallel. What I saw you doing was it looks like you were
researching .NET Aspire in general and I don't think that's gonna do much for us in this case.
That's way too untargeted research. The research needs to help you solve a specific targeted question.

[!NOTE]
Claude Code 可能会过于急切并添加你未要求的组件。要求它澄清理由和变更来源。

步骤 5: 让 Claude Code 验证计划 (Have Claude Code validate the plan)

计划到位后,你应该让 Claude Code 检查一遍,确保没有遗漏的部分。你可以使用如下提示词:

Now I want you to go and audit the implementation plan and the implementation detail files.
Read through it with an eye on determining whether or not there is a sequence of tasks that you need
to be doing that are obvious from reading this. Because I don't know if there's enough here. For example,
when I look at the core implementation, it would be useful to reference the appropriate places in the implementation
details where it can find the information as it walks through each step in the core implementation or in the refinement.

这有助于完善实施计划,并帮助你避免 Claude Code 在其规划周期中错过的潜在盲点。一旦初始细化通过完成,要求 Claude Code 在你开始实施之前再次检查清单。

你也可以要求 Claude Code (如果你安装了 GitHub CLI) 继续创建一个从当前分支到 main 的 pull request,并附上详细描述,以确保工作得到正确跟踪。

[!NOTE]
在让代理实施之前,也值得提示 Claude Code 交叉检查细节,看看是否有任何过度设计的部分 (记住 - 它可能会过于急切)。如果存在过度设计的组件或决策,你可以要求 Claude Code 解决它们。确保 Claude Code 遵循 constitution 作为制定计划时必须遵守的基础部分。

步骤 6: 使用 /speckit.tasks 生成任务分解 (Generate task breakdown)

验证实施计划后,你现在可以将计划分解为可以按正确顺序执行的具体、可操作的任务。使用 /speckit.tasks 命令从你的实施计划自动生成详细的任务分解:

/speckit.tasks

此步骤在你的功能规范目录中创建一个 tasks.md 文件,其中包含:

  • 按用户故事组织的任务分解 - 每个用户故事成为一个单独的实施阶段,拥有自己的一组任务
  • 依赖管理 - 任务按顺序排列以尊重组件之间的依赖关系 (例如,模型在服务之前,服务在端点之前)
  • 并行执行标记 - 可以并行运行的任务标记为 [P] 以优化开发工作流
  • 文件路径规范 - 每个任务都包含实施应发生的确切文件路径
  • 测试驱动开发结构 - 如果要求测试,测试任务将包含在内,并排序为在实施之前编写
  • 检查点验证 - 每个用户故事阶段都包含检查点以验证独立功能

生成的 tasks.md 为 /speckit.implement 命令提供了清晰的路线图,确保系统化实施,保持代码质量并允许增量交付用户故事。

步骤 7: 实施 (Implementation)

准备就绪后,使用 /speckit.implement 命令执行你的实施计划:

/speckit.implement

/speckit.implement 命令将:

  • 验证所有先决条件是否到位 (constitution, spec, plan, 和 tasks)
  • 解析 tasks.md 中的任务分解
  • 按正确顺序执行任务,尊重依赖关系和并行执行标记
  • 遵循任务计划中定义的 TDD 方法
  • 提供进度更新并适当处理错误

[!IMPORTANT]
AI 代理将执行本地 CLI 命令 (如 dotnet, npm 等) - 确保你的机器上安装了所需的工具。

实施完成后,测试应用程序并解决任何可能在 CLI 日志中不可见的运行时错误 (例如,浏览器控制台错误)。你可以将此类错误复制并粘贴回 AI 代理以进行解决。


🔍 故障排除 (Troubleshooting)

Linux 上的 Git 凭据管理器 (Git Credential Manager on Linux)

如果你在 Linux 上遇到 Git 身份验证问题,可以安装 Git Credential Manager:

#!/usr/bin/env bash
set -e
echo "Downloading 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 "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

👥 维护者 (Maintainers)

💬 支持 (Support)

如需支持,请打开 GitHub issue。我们欢迎错误报告、功能请求以及关于使用规范驱动开发的问题。

🙏 致谢 (Acknowledgements)

本项目深受 John Lam 的工作和研究的影响并基于此。

📄 许可证 (License)

本项目根据 MIT 开源许可证的条款获得许可。有关完整条款,请参阅 LICENSE 文件。