spec-kit-zh

目录

• 🤔 什么是规范驱动开发？
• ⚡ 快速开始
• 📽️ 视频概览
• 🚶 社区演练项目
• 🤖 支持的 AI 代理
• 🔧 specify-zh 命令参考
• 📚 核心理念
• 🌟 开发阶段
• 🎯 实验目标
• 🔧 前置要求
• 📖 延伸阅读
• 📋 详细流程
• 🔍 故障排除
• 💬 支持
• 🙏 致谢
• ⭐ Star History
• 📄 许可证

🤔 什么是规范驱动开发？

规范驱动开发（Spec-Driven Development）重新定义了软件开发的起点。过去几十年里，代码一直是开发过程中的主角，而规范常常只是编码开始前临时搭起来的脚手架。规范驱动开发改变了这一点：规范本身变得可执行，它不再只是指导实现，而是可以直接驱动计划、任务拆解与最终实现。

⚡ 快速开始

如果你希望先快速跑通一遍从需求到实现的完整流程，这一节可以帮助你在几分钟内建立起最小可用认知。

⏱️ 3 分钟上手

第 1 步：安装

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

[!IMPORTANT] 📦 安装包名：specify-cli-zh (用于 pip / uv install 下载)
🚀 执行命令：specify-zh (用于在终端执行工具)

第 2 步：初始化项目

specify-zh init my-project

第 3 步：验证

specify-zh check

🤷‍♂️ 我应该用哪个命令？ (FAQ)

• specify-cli-zh：这是本中文分支在 Python 包管理系统中的分发包名。但在运行工具本身时，请不要输入 specify-cli-zh。
• specify-zh：这是您真正在终端执行的命令名。所有的命令前缀都应为 specify-zh 以避免冲突。
• specify：这是上游英文原版的默认命令名。如果你只安装了本工具，并且环境中没有安装过冲突工具，你可以为其配置 alias，但在本项目文档和教程中，我们将始终称之为 specify-zh。

📌 安装方式速览

1. 安装 specify-cli-zh

请选择你偏好的安装方式：

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

安装一次，全局可用：

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

安装完成后即可直接使用：

# 创建新项目
specify-zh init <PROJECT_NAME>

# 或在现有项目中初始化
specify-zh init . --ai claude
# 或者
specify-zh init --here --ai claude

# 检查本机工具环境
specify-zh check

specify-cli-zh 默认安装的命令名是 specify-zh，这样可以避免与其他已安装的 specify 命令冲突。

升级 Specify 请参阅 升级指南。快速升级命令如下：

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

方式 2：一次性使用

无需安装，直接运行：

# 创建新项目
uvx --from git+https://github.com/loulanyue/spec-kit-zh.git specify-zh init <PROJECT_NAME>

# 或在现有项目中初始化
uvx --from git+https://github.com/loulanyue/spec-kit-zh.git specify-zh init . --ai claude
# 或者
uvx --from git+https://github.com/loulanyue/spec-kit-zh.git specify-zh init --here --ai claude

持久化安装的优势：

• 工具会保留在 PATH 中，随时可用
• 不需要额外维护 shell 别名
• 可以使用 uv tool list、uv tool upgrade、uv tool uninstall 做更完整的工具管理
• shell 配置更简洁

2. 验证安装

安装完成后，运行以下命令确认 CLI 正常工作：

specify-zh --help    # 显示命令帮助，且品牌名为 specify-cli-zh
specify-zh version   # 显示版本号和环境信息
specify-zh check     # 检测本机工具链（git、AI agent 等）

[!TIP] 安装包名 vs 执行命令名

用途	名称
pip/uv 安装时使用	specify-cli-zh
终端运行时使用	specify-zh

如果你是在已有仓库中接入 Spec Kit，建议优先使用 specify-zh init . 或 specify-zh init --here，这样可以直接在当前目录完成初始化。

3. 建立项目原则

在项目目录中启动你的 AI 助手。初始化完成后，助手中就会提供 Spec Kit 命令。

[!TIP] 对于 Codex CLI，自定义命令使用 /prompts: 命名空间。 正确调用方式为 /prompts:speckit-constitution、/prompts:speckit-specify 等。 不要输入 /speckit.constitution 或 /speckit:constitution，Codex 不支持该格式。

使用 /speckit.constitution 创建项目的治理原则与开发准则；如果你使用 Codex CLI，请输入 /prompts:speckit-constitution。这些原则会贯穿后续所有规范、计划与实现阶段。

# Claude / Gemini / 其他 agent
/speckit.constitution 创建强调代码质量、测试标准、用户体验一致性与性能要求的项目原则

# Codex CLI
/prompts:speckit-constitution 创建强调代码质量、测试标准、用户体验一致性与性能要求的项目原则

3. 创建规格说明

使用 /speckit.specify 描述你要构建什么；Codex CLI 对应命令为 /prompts:speckit-specify。此阶段应重点说明做什么与为什么做，而不是技术栈。

/speckit.specify 构建一个帮助我管理照片相册的应用。相册按日期分组，可在主页拖拽重排；相册之间不允许嵌套；每个相册中的照片以平铺预览方式展示。

4. 创建技术实施计划

使用 /speckit.plan 补充技术栈与架构选择；Codex CLI 对应命令为 /prompts:speckit-plan。

/speckit.plan 应用使用 Vite，并尽量减少外部依赖。优先使用原生 HTML、CSS 与 JavaScript。图片不上传到远端，元数据保存在本地 SQLite 数据库中。

5. 分解任务

使用 /speckit.tasks 将实施计划转成可执行的任务清单；Codex CLI 对应命令为 /prompts:speckit-tasks。

/speckit.tasks

6. 执行实现

使用 /speckit.implement 按计划执行任务并完成功能实现；Codex CLI 对应命令为 /prompts:speckit-implement。

/speckit.implement

如需查看完整分步说明，请阅读 Spec-Driven Development 全流程指南。

7. 常用工作流速查

首次接触时，推荐按 constitution -> specify -> plan -> tasks -> implement 的顺序推进；如果需求仍有模糊点，可以先运行 /speckit.clarify，Codex CLI 则使用 /prompts:speckit-clarify，再进入计划阶段。

📽️ 视频概览

想快速了解 Spec Kit 的工作方式？可以先看这个视频概览：

🚶 社区演练项目

下面这些社区项目展示了规范驱动开发在不同场景中的实际用法：

• Greenfield .NET CLI tool：从空目录出发，构建一个 .NET 单文件时区工具 CLI，完整覆盖 constitution、specify、plan、tasks 以及多轮 implement 流程。

• Greenfield Spring Boot + React platform：从零构建一个 LLM 性能分析平台，包含 REST API、图表、迭代跟踪，并演示 clarify 和跨文档一致性分析流程。

• Brownfield ASP.NET CMS extension：在已有 ASP.NET CMS 项目中追加两个功能，展示 spec-kit 如何适配已有代码库，而不要求项目一开始就有现成规范或 constitution。

🤖 支持的 AI 代理