
🌱 Spec Kit
Build high-quality software faster.
借助 Spec-Driven Development,让组织能够专注于产品场景,而不是编写无差异化的代码。
🤔 什么是 Spec-Driven Development? 🔗
Spec-Driven Development 颠覆了传统的软件开发方式。在过去的几十年里,代码一直是核心——规范只是辅助的脚手架,一旦“真正的工作”开始,规范便被丢弃。Spec-Driven Development 改变了这一点:规范变为可执行的,它们直接生成可工作的实现,而不仅仅是指导实现。
⚡ 快速开始 🔗
1. 安装 Specify 🔗
根据所使用的编码代理来初始化你的项目:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
2. 建立项目原则 🔗
使用 /constitution
命令来创建项目的指导原则和开发准则,这些将引导后续的所有开发。
/constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
3. 创建规范(spec) 🔗
使用 /specify
命令描述你要构建的内容。重点放在 做什么 和 为什么,而不是技术栈。
/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. 创建技术实现计划 🔗
使用 /plan
命令提供技术栈和架构选择。
/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. 分解为任务 🔗
使用 /tasks
将实现计划拆解为可执行的任务列表。
/tasks
6. 执行实现 🔗
使用 /implement
来执行所有任务,并根据计划构建功能。
/implement
更多分步骤的详细说明,请查看我们的完整指南。
📽️ 视频概览 🔗
想看看 Spec Kit 的实际运行效果吗?请观看我们的视频概览!
🤖 支持的 AI Agents 🔗
Agent | 支持情况 | 备注 |
---|---|---|
Claude Code | ✅ | |
GitHub Copilot | ✅ | |
Gemini CLI | ✅ | |
Cursor | ✅ | |
Qwen Code | ✅ | |
opencode | ✅ | |
Windsurf | ✅ | |
Kilo Code | ✅ | |
Auggie CLI | ✅ | |
Roo Code | ✅ | |
Codex CLI | ⚠️ | Codex 不支持 自定义 slash 命令参数 |
🔧 Specify CLI 参考 🔗
specify
命令支持以下选项:
Commands 🔗
命令 | 描述 |
---|---|
init |
从最新模板初始化一个新的 Specify 项目 |
check |
检查已安装的工具(git 、claude 、gemini 、code /code-insiders 、cursor-agent 、windsurf 、qwen 、opencode 、codex ) |
specify init
参数与选项 🔗
参数/选项 | 类型 | 描述 |
---|---|---|
<project-name> |
参数 | 新项目目录名称(使用 --here 时可省略) |
--ai |
选项 | 指定使用的 AI 助手:claude 、gemini 、copilot 、cursor 、qwen 、opencode 、codex 、windsurf 、kilocode 、auggie 或 roo |
--script |
选项 | 使用的脚本类型:sh (bash/zsh) 或 ps (PowerShell) |
--ignore-agent-tools |
标志 | 跳过对 AI agent 工具(如 Claude Code)的检查 |
--no-git |
标志 | 跳过 Git 仓库初始化 |
--here |
标志 | 在当前目录初始化项目,而不是新建目录 |
--skip-tls |
标志 | 跳过 SSL/TLS 校验(不推荐) |
--debug |
标志 | 启用详细调试输出,便于故障排查 |
--github-token |
选项 | 用于 API 请求的 GitHub token(或设置 GH_TOKEN/GITHUB_TOKEN 环境变量) |
示例 🔗
# 基础项目初始化
specify init my-project
# 使用指定 AI 助手初始化
specify init my-project --ai claude
# 使用 Cursor 支持初始化
specify init my-project --ai cursor
# 使用 Windsurf 支持初始化
specify init my-project --ai windsurf
# 使用 PowerShell 脚本(适用于 Windows/跨平台)
specify init my-project --ai copilot --script ps
# 在当前目录初始化
specify init --here --ai copilot
# 跳过 Git 初始化
specify init my-project --ai gemini --no-git
# 启用调试输出以便排查问题
specify init my-project --ai claude --debug
# 使用 GitHub token 进行 API 请求(企业环境常用)
specify init my-project --ai claude --github-token ghp_your_token_here
# 检查系统要求
specify check
可用的 Slash 命令 🔗
在运行 specify init
后,你的 AI 编码代理可以使用以下 slash 命令来进行结构化开发:
命令 | 描述 |
---|---|
/constitution |
创建或更新项目的指导原则和开发准则 |
/specify |
定义要构建的内容(需求和用户故事) |
/plan |
根据所选技术栈创建技术实现方案 |
/tasks |
生成可执行的任务列表 |
/implement |
执行所有任务并根据计划构建功能 |
环境变量 🔗
变量 | 描述 |
---|---|
SPECIFY_FEATURE |
为非 Git 仓库覆盖功能检测。将其设置为功能目录名称(例如 001-photo-albums ),即可在未使用 Git 分支时处理特定功能。必须在使用 /plan 或后续命令之前,在所用 agent 的上下文中设置。 |
📚 核心理念 🔗
Spec-Driven Development 是一种强调结构化流程的方法,重点在于:
- 意图驱动的开发:先由规范定义“做什么”,再决定“怎么做”
- 丰富的规范创建:通过护栏和组织原则来生成高质量规范
- 多步骤迭代:不是一次性从提示生成代码,而是逐步细化
- 高度依赖先进 AI 模型的能力来解释和实现规范
🌟 开发阶段 🔗
阶段 | 重点 | 关键活动 |
---|---|---|
0-to-1 开发(“从零到一”) | 从零开始构建 |
|
创造性探索 | 并行实现 |
|
迭代增强(“存量改造”) | 现代化改造 |
|
🎯 实验目标 🔗
我们的研究与实验聚焦于:
技术独立性 🔗
- 使用多样化的技术栈来创建应用
- 验证 Spec-Driven Development 是一种与具体技术、编程语言或框架无关的流程
企业级约束 🔗
- 演示任务关键型应用的开发
- 融合组织约束(云服务商、技术栈、工程实践)
- 支持企业级设计系统与合规性要求
以用户为中心的开发 🔗
- 为不同用户群体和偏好构建应用
- 支持多样化的开发方式(从“灵感驱动编码”到“AI 原生开发”)
创造性与迭代性流程 🔗
- 验证并行实现探索的概念
- 提供健壮的迭代式功能开发工作流
- 扩展流程以支持升级与现代化改造任务
🔧 前置条件 🔗
- Linux/macOS(或 Windows 上的 WSL2)
- AI 编码代理:Claude Code、GitHub Copilot、Gemini CLI、Cursor、Qwen CLI、opencode、Codex CLI、Windsurf
- uv(包管理工具)
- Python 3.11+
- Git
如果在使用某个代理时遇到问题,请提交 issue,以便我们改进集成。
📖 深入学习 🔗
- 完整的 Spec-Driven Development 方法论 —— 深入了解整个流程
- 详细演练 —— 分步骤的实现指南
📋 详细流程 🔗
点击展开分步骤演练
你可以使用 Specify CLI 来引导项目初始化,它会将所需的构件带入你的环境。运行:
specify init <project_name>
或者在当前目录中初始化:
specify init --here
系统会提示你选择正在使用的 AI 代理。你也可以直接在终端中主动指定:
specify init <project_name> --ai claude
specify init <project_name> --ai gemini
specify init <project_name> --ai copilot
specify init <project_name> --ai cursor
specify init <project_name> --ai qwen
specify init <project_name> --ai opencode
specify init <project_name> --ai codex
specify init <project_name> --ai windsurf
# 或在当前目录:
specify init --here --ai claude
specify init --here --ai codex
CLI 会检查你是否已安装 Claude Code、Gemini CLI、Cursor CLI、Qwen CLI、opencode 或 Codex CLI。
如果未安装,或者你希望在不检查这些工具的情况下直接获取模板,可以在命令中使用 --ignore-agent-tools
:
specify init <project_name> --ai claude --ignore-agent-tools
步骤 1:建立项目原则 🔗
进入项目文件夹并运行你的 AI 代理。在示例中,我们使用的是 claude
。
如果你看到 /constitution
、/specify
、/plan
、/tasks
和 /implement
命令可用,就说明配置正确。
第一步是使用 /constitution
命令来建立项目的治理原则。这有助于确保在后续所有开发阶段中保持一致的决策:
/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.
此步骤会创建或更新 /memory/constitution.md
文件,作为项目的基础指南,AI 代理会在规范、规划和实现阶段参考它。
步骤 2:创建项目规范 🔗
有了项目原则后,就可以创建功能规范了。使用 /specify
命令,并提供项目的具体需求。
[!IMPORTANT] 尽可能明确说明你要构建的 是什么 以及 为什么。此时不要关注技术栈。
示例提示:
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 会启动规划和规范起草过程,并触发内置脚本来设置仓库。
完成后,你会得到一个新分支(例如 001-create-taskify
),以及 specs/001-create-taskify
目录下的规范文件。
其中应包含用户故事和功能需求。
项目文件夹结构大致如下:
├── memory
│ ├── constitution.md
│ └── constitution_update_checklist.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:澄清功能规范 🔗
在生成初始规范后,你可以进一步澄清未被准确捕捉的需求。例如:
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:生成实现计划 🔗
现在可以明确技术栈和其他技术需求了。使用 /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
│ └── constitution_update_checklist.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
,确保技术栈符合要求。
如果框架变化快(如 .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 验证计划 🔗
计划生成后,让 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 再次执行 checklist 检查。 如果安装了 GitHub CLI,还可以让 Claude Code 创建 PR,方便跟踪。
[!NOTE] 在实施前,值得让 Claude Code 检查是否有“过度设计”。如有,应让它调整,并确保遵循 constitution。
步骤 6:实施 🔗
准备就绪后,使用 /implement
命令执行实现计划:
/implement
/implement
命令会:
- 验证所有前置条件是否具备(constitution、spec、plan、tasks)
- 解析
tasks.md
中的任务分解 - 按正确顺序执行任务,处理依赖和并行任务
- 遵循任务计划中定义的 TDD 方法
- 提供进度更新,并在错误时正确处理
[!IMPORTANT] AI 代理会执行本地 CLI 命令(如
dotnet
、npm
等)——请确保已安装所需工具。
实现完成后,测试应用并解决可能的运行时错误(如浏览器控制台错误),可以将这些错误复制粘贴回 AI 代理进行修复。
🔍 故障排查 🔗
Linux 上的 Git Credential Manager 🔗
如果你在 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
👥 维护者 🔗
💬 支持 🔗
如需支持,请提交 GitHub issue。我们欢迎错误报告、功能请求以及关于使用 Spec-Driven Development 的问题。
🙏 致谢 🔗
本项目深受 John Lam 的研究和工作启发与影响。
📄 许可证 🔗
本项目采用 MIT 开源许可证。完整条款请参阅 LICENSE 文件。