🌱 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 代理

[!TIP] 国内主流 AI 编码工具（通义灵码、DeepSeek Coder、百度 Comate、MarsCode 等）均可通过 --ai generic 模式接入。 详见 国内大模型接入指南。 如果团队内部有自定义提示模板或命令目录，也可以配合 --ai-commands-dir 统一接入现有工作流。

🔧 specify-zh 命令参考

specify-zh 命令支持以下能力与参数：

命令

specify-zh init 参数与选项

示例

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

# 指定 AI 助手初始化
specify-zh init my-project --ai claude

# 使用 Cursor 初始化
specify-zh init my-project --ai cursor-agent

# 使用 Qoder 初始化
specify-zh init my-project --ai qodercli

# 使用 Windsurf 初始化
specify-zh init my-project --ai windsurf

# 使用 Kiro CLI 初始化
specify-zh init my-project --ai kiro-cli

# 使用 Amp 初始化
specify-zh init my-project --ai amp

# 使用 SHAI 初始化
specify-zh init my-project --ai shai

# 使用 Mistral Vibe 初始化
specify-zh init my-project --ai vibe

# 使用 IBM Bob 初始化
specify-zh init my-project --ai bob

# 使用 Antigravity 初始化
specify-zh init my-project --ai agy

# 初始化未内置支持的代理（generic / bring your own agent）
specify-zh init my-project --ai generic --ai-commands-dir .myagent/commands/

# 强制使用 PowerShell 脚本
specify-zh init my-project --ai copilot --script ps

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

# Force merge into current (non-empty) directory without confirmation
specify-zh init . --force --ai copilot
# or
specify-zh init --here --force --ai copilot

# Skip git initialization
specify-zh init my-project --ai gemini --no-git

# Enable debug output for troubleshooting
specify-zh init my-project --ai claude --debug

# Use GitHub token for API requests (helpful for corporate environments)
specify-zh init my-project --ai claude --github-token ghp_your_token_here

# Install agent skills with the project
specify-zh init my-project --ai claude --ai-skills

# Initialize in current directory with agent skills
specify-zh init --here --ai gemini --ai-skills

# Codex + skills 模式
specify-zh init --here --ai codex --ai-skills

# Generic 模式下接入已有命令目录并安装 skills
specify-zh init my-project --ai generic --ai-commands-dir .myagent/commands/ --ai-skills

# Check system requirements
specify-zh check

可用斜杠命令 (Available Slash Commands)

默认情况下，运行 specify-zh init 后，你的 AI 代码代理将获得以下斜杠命令用于结构化开发。

[!IMPORTANT] 如果你使用了 --ai-skills，那么安装结果会变成 skills 形态，而不是 /speckit.* 斜杠命令形态。 尤其是 Codex：此时你通常会看到 .agents/skills/speckit-*，而不是 .codex/prompts/。

Codex CLI 的自定义命令运行格式为 /prompts:speckit-constitution（/prompts: + 文件名），而非 /speckit.constitution。

核心命令 (Core Commands)

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

推荐顺序：先用 /speckit.constitution 明确治理原则，再逐步进入 /speckit.specify、/speckit.plan、/speckit.tasks 与 /speckit.implement。如果你使用的是 Codex CLI，请把它们分别替换成 /prompts:speckit-constitution、/prompts:speckit-specify、/prompts:speckit-plan、/prompts:speckit-tasks 与 /prompts:speckit-implement。

可选命令 (Optional Commands)

用于增强质量与验证的附加命令：

[!TIP] 上表使用的是通用 slash command 写法。若你在 Codex CLI 中执行，请将 /speckit.<name> 换成 /prompts:speckit-<name>。

环境变量

📚 核心理念 (Core Philosophy)

规范驱动开发 (Spec-Driven Development) 是一个强调以下几点的结构化流程：

• 意图驱动开发：规范优于实现，先定义"做什么"(what)，再定义"怎么做"(how)
• 丰富的规范创建：使用护栏 (guardrails) 和组织原则进行约束
• 多步迭代细化：而不是指望通过提示词生成一次性代码
• 高度依赖高级 AI 模型对规范的解读能力

🌟 开发阶段 (Development Phases)

🎯 实验目标 (Experimental Goals)

我们的研究与实验主要集中在以下方面：

技术栈独立

• 使用不同的技术栈创建应用程序
• 验证"规范驱动开发是一种不绑定于特定技术、编程语言或框架的流程"这一假设

企业级约束

• 演示关键业务应用程序的开发
• 结合组织架构约束（云提供商、技术栈、工程实践）
• 支持企业设计系统与合规性要求

以用户为中心的开发

• 为不同的用户群体和偏好构建应用程序
• 支持多种开发方式（从 vibe-coding 到 AI 原生开发）

创新性与迭代流程

• 验证并行实验与对比实施概念的可行性
• 提供稳健的迭代式功能开发工作流
• 扩展流程以处理升级和现代化重构任务

🔧 前置要求

• Linux / macOS / Windows
• 支持的 AI 编码代理
• 用于包管理的 uv
• Python 3.11+
• Git

如果你的网络环境受限，建议提前准备好 GitHub 访问代理或在安装阶段配置镜像源，以减少初始化与升级时的等待成本。

如果在与 Agent 工具的集成中遇到任何问题，请提交 issue，以便我们不断优化集成体验。

📖 了解更多

• 完整的规范驱动开发方法论 - 深入了解整个工作流
• 详细演练流程 - 分步操作指南
• 从旧版本迁移 - 从原版 spec-kit 等的迁移指南
• 升级指南 - 查看版本升级建议与常见变更处理方式

📋 详细流程 (Detailed Process)

specify-zh init <project_name>

specify-zh init .
# 或者使用 --here 标志
specify-zh init --here
# 当目录非空时跳过确认操作
specify-zh init . --force
# 或者
specify-zh init --here --force

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

# 或在当前目录中：
specify-zh init . --ai claude
specify-zh init . --ai codex

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

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

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

specify-zh init <project_name> --ai claude --ignore-agent-tools

ls -la ~/.codex/prompts/

speckit-constitution.md
speckit-specify.md
speckit-plan.md
speckit-tasks.md
speckit-implement.md

specify-zh codex-sync --project .

ls -la .agents/skills/

speckit-constitution/
speckit-specify/
speckit-plan/
speckit-tasks/
speckit-implement/

使用 speckit-constitution 这个 skill，创建强调代码质量、测试标准、用户体验一致性与性能要求的项目原则。

# Codex CLI
/prompts:speckit-constitution 建立专注于代码质量、测试标准、用户体验一致性及性能要求的项目章程。

# Claude / Gemini / 其他 agent
/speckit.constitution 建立专注于代码质量、测试标准、用户体验一致性及性能要求的项目章程。

开发 Taskify，一个团队生产力平台。允许用户建立项目、添加团队成员、分配任务、跨看板评论与拖拽任务（看板模式）。在此特性的初始开发阶段（我们就叫它“创建 Taskify”吧），先预设五名固定用户：一名产品经理和四名工程师。建立三个样本项目。需要包含标准的看板状态列，例如“待办”、“进行中”、“审核中”与“完成”。第一版不用做登录模块。在任务卡片 UI 中，能够更改状态（在不同列中拖拽或切换）。能够为任意卡片留下无限数量的评论并允许分配用户。...

└── .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

阅读并逐项检查验收标准 checklist。如果当前规范文档已充分满足该检查项的判定要求则打勾。若未满足则保持留空。

我期望使用 .NET Aspire 与 Postgres 数据库搭建这个项目。前端应用 Blazor Server，利用拖拽组件进行任务看板交互，并达成实时渲染更新。建立一套包含对 projects/tasks/notifications 支持的 REST 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

我希望你通读一下 plan.md（实施计划）与各个实现细节文档，找出能够从外部搜索研究中获益的技术细节，因为 .NET Aspire 的库改动往往非常快。找出这些有待深挖的细节任务后，更新研究文档 (research.md)，对这版应用即将采纳的精确框架版本进行调研核实。请就此孵化出对应的研究分任务，并发启动研究工作。

我觉得得给你拆成几个步骤。首先，列出行将开发却不甚明朗、需要作进一步调研的子任务清单（比如只写下来需要查什么API）。然后再针对清单内容开启各自独立的研究任务。总而言之，我们只要把每个专门的不确定点各自查清就行了。你刚刚查半天的泛泛而谈全都是些没头苍蝇式的没用信息。调研必须帮你解答针对性极强的开发疑惑，而不是一揽子概述。

现在去审计一轮前前后后的实施计划跟所有的附属文件资料。仔细阅读以判断那些原本看似不言自明的隐含操作是否其实有断档隐患（因为我无法确信这计划能照章实施）。比方说：如果核心层里写了某某功能，而对应文档里却压根找不到落地的相关条文，这就麻烦了。去审计。

/speckit.tasks

/speckit.implement
# Codex CLI:
/prompts:speckit-implement

🔍 故障排除 (Troubleshooting)

请查阅 常见问题与排障指南 (Troubleshooting Docs) 获取更全面的解决方案，包含：

• 安装包冲突或执行失败策略
• GitHub API 时不时挂掉或限流的配置手段
• 初始化网络超时打结

（参考样例）Linux 上由于 Git 凭据引起报错时的修复脚本

如果你使用的是 Linux 原生环境，它大概率在卡 GitHub 时会触发鉴权弹框问题，这时你大可以上一个 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

📝 README 实践提示

下面整理一些面向新团队和日常协作的实践建议，便于在初始化、规划、实施与排障时快速对齐使用方式。

💬 支持 (Support)

如果需要技术支持、报告错误或是交流有关规范驱动开发的火花思路，请尽情到仓库里提 GitHub Issue。别客气，我们很期待听听大家的声音。

项目优先级见 ROADMAP.md，决策、响应目标与发布方式见 GOVERNANCE.md。提交代码前请阅读 CONTRIBUTING.md；安全问题请按 SECURITY.md 私密报告。

🙏 致谢 (Acknowledgements)

此系统深深致敬、并承接于开源前驱 John Lam 和背后社区团体内那些关于 Agent 上限探索的才华结晶与辛勤耕耘的杰出工作。

📄 许可证 (License)

本项目开源授权基于 MIT 许可证。详阅随附的 LICENSE 全本合约。

⭐ Star History