README.zh-CN.md
<h1>🌱 Spec Kit</h1>
<h3><em>在动手编码之前，先定义要构建什么 —— 适配任意 AI 编码助手。</em></h3>
规范驱动开发（Spec-Driven Development）颠覆了传统软件开发的思路。几十年来，代码一直是核心 —— 规范只是编码这项"正事"开始前搭起、随后就被丢弃的脚手架。规范驱动开发改变了这一点：规范本身变得可执行，它不再只是引导实现，而是直接生成可运行的实现。
需要 uv（安装 uv）。将 vX.Y.Z 替换为 Releases 中最新的发布标签 —— 记得保留开头的 v（例如 v0.12.11，而不是 0.12.11）：
uv tool install specify-cli --from git+https://github.com/github/[email protected]
更倾向从 PyPI 安装？specify-cli 包同样发布在那里：
uv tool install specify-cli
其他安装方式、安装校验、升级以及故障排查，请参阅安装指南。
specify init my-project --integration copilot
cd my-project
要检查更新或升级已安装的 CLI，可使用自管理命令。更详细的场景和自定义选项请参阅升级指南。
# 检查是否有更新版本可用（只读操作 —— 不会修改任何内容）
specify self check
# 预览升级将执行的操作，但不实际升级
specify self upgrade --dry-run
# 就地升级到最新稳定版（自动识别 uv tool 与 pipx 安装方式）
specify self upgrade
# 或锁定到指定的发布标签（将 vX.Y.Z[suffix] 替换为你想要的标签）
specify self upgrade --tag vX.Y.Z[suffix]
直接运行 specify self upgrade 会立即执行，与 pip install -U、npm update 等命令一样无需额外确认。对于 uv tool 安装的情况，它在底层会执行 uv tool install specify-cli --force --from <git ref>，因此锁定的发布标签同样有效，包括 dev、alpha/beta/rc 或带构建元数据的后缀。uvx（临时运行）和源码检出会被自动识别，此时会给出针对具体路径的操作建议，而不会执行安装程序。可通过设置 SPECIFY_UPGRADE_TIMEOUT_SECS 来限制安装子进程的最长运行时间（默认无超时限制 —— 必要时用 Ctrl+C 中断）。
在项目目录下启动你的编码助手。大多数助手将 spec-kit 暴露为 /speckit.* 斜杠命令；处于技能（skills）模式的 Codex CLI 则使用 $speckit-*；GitHub Copilot CLI 使用 /agents 来选择助手，或直接在提示词中指定它。
使用 /speckit.constitution 命令来创建项目的治理准则和开发指南，它们将指导后续所有开发工作。
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
使用 /speckit.specify 命令描述你想构建什么。聚焦于做什么和为什么做，而不是技术栈。
/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.
使用 /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.
使用 /speckit.tasks 从实现方案生成一份可执行的任务清单。
/speckit.tasks
使用 /speckit.implement 执行所有任务，按方案构建你的功能。
/speckit.implement
详细的分步说明，请参阅我们的完整指南。
想看看 Spec Kit 的实际效果？观看我们的视频概览！
在 Spec Kit 文档站点上探索由社区贡献的资源：
[!NOTE] 社区贡献由各自的作者独立创建和维护。请在安装前审阅源代码，并自行斟酌使用。
想要参与贡献？请参阅扩展发布指南、预设发布指南或社区捆绑包指南。
Spec Kit 可与 30 多个 AI 编码助手协作 —— 既包括 CLI 工具，也包括基于 IDE 的助手。完整列表以及相关说明和使用细节，请参阅支持的 AI 编码助手集成指南。
运行 specify integration list 可查看当前安装版本中所有可用的集成。
运行 specify init 后，你的 AI 编码助手就能使用这些斜杠命令来进行结构化开发。对于支持技能模式的集成，传入 --integration <agent> --integration-options="--skills" 会安装助手技能，而不是斜杠命令的提示词文件。
规范驱动开发工作流中必不可少的命令：
| 命令 | 助手技能 | 说明 |
|---|---|---|
/speckit.constitution | speckit-constitution | 创建或更新项目的治理准则和开发指南 |
/speckit.specify | speckit-specify | 定义你想构建什么（需求与用户故事） |
/speckit.plan | speckit-plan | 结合所选技术栈制定技术实现方案 |
/speckit.tasks | speckit-tasks | 生成可执行的实现任务清单 |
/speckit.taskstoissues | speckit-taskstoissues | 将生成的任务清单转换为 GitHub issue，便于跟踪与执行 |
/speckit.implement | speckit-implement | 执行所有任务，按方案构建功能 |
/speckit.converge | speckit-converge | 对照规范/方案/任务评估代码库，并将剩余工作追加为新任务 |
用于提升质量与做校验的额外命令：
| 命令 | 助手技能 | 说明 |
|---|---|---|
/speckit.clarify | speckit-clarify | 澄清描述不充分的部分（建议在 /speckit.plan 之前使用；旧称 /quizme） |
/speckit.analyze | speckit-analyze | 跨制品的一致性与覆盖度分析（在 /speckit.tasks 之后、/speckit.implement 之前运行） |
/speckit.checklist | speckit-checklist | 生成自定义质量清单，校验需求的完整性、清晰度与一致性（好比"为自然语言写单元测试"） |
完整的命令详情、选项与示例，请参阅 CLI 参考文档。
Spec Kit 可通过两套互补的机制进行深度定制 —— 扩展（extensions） 和 预设（presets） —— 以及面向单个项目的本地覆盖，用于临时性调整：
| 优先级 | 组件类型 | 位置 |
|---|---|---|
| ⬆ 1 | 项目本地覆盖 | .specify/templates/overrides/ |
| 2 | 预设 —— 定制核心与扩展 | .specify/presets/templates/ |
| 3 | 扩展 —— 新增能力 | .specify/extensions/templates/ |
| ⬇ 4 | Spec Kit 核心 —— 内置 SDD 命令与模板 | .specify/templates/ |
.specify/templates/overrides/）允许对单个项目做一次性调整，无需创建完整的预设。specify extension add 或 specify preset add 时，命令文件会被写入助手目录（如 .claude/commands/）。当你需要 Spec Kit 核心之外的功能时，使用扩展。扩展可引入新命令和模板 —— 例如添加核心 SDD 命令未覆盖的领域特定工作流、集成外部工具，或新增全新的开发阶段。它们扩展了 Spec Kit 能做什么。
# 搜索可用扩展
specify extension search
# 安装扩展
specify extension add <extension-name>
举例来说，扩展可以添加 Jira 集成、实现后代码审查、V 模型测试追溯性，或项目健康诊断等功能。
当你想改变 Spec Kit 的工作方式而不是新增能力时，使用预设。预设会覆盖核心及已安装扩展中附带的模板和命令 —— 例如强制使用面向合规的规范格式、采用领域特定术语，或对方案和任务应用组织规范。预设定制的是 Spec Kit 及其扩展生成的制品与指令。
# 搜索可用预设
specify preset search
# 安装预设
specify preset add <preset-name>
举例来说，预设可以重构规范模板以要求监管追溯性，将工作流适配为你所用的方法论（如敏捷、看板、瀑布、用户任务驱动或领域驱动设计），在方案中添加强制安全审查关卡，强制要求测试优先的任务排序，或将整个工作流本地化为其他语言。海盗语演示充分展示了定制的深度。多个预设可按优先级叠加使用。
完整命令指南以及解析顺序和优先级叠加说明，请参阅预设参考文档。
扩展和预设是独立的构建模块。而**捆绑包（bundle）**将一组精选的扩展、预设、步骤和工作流打包成一个带版本、面向角色的配置，从而可以用一条命令为整个团队角色（产品经理、业务分析师、安全研究员、开发者……）完成配置。
捆绑包由一份手写的 bundle.yml 清单描述。它将每个组件锁定到具体版本，并可选择性地面向特定集成；未指定 integration 的捆绑包是中立的，会沿用项目当前已使用的集成。
# 在当前激活的目录栈中发现捆绑包
specify bundle search [<query>]
# 查看捆绑包将添加的确切组件集合（与实际安装的内容一致）
specify bundle info <bundle-id>
# 一步安装捆绑包的完整组件集合
specify bundle install <bundle-id>
# 查看已安装内容，然后以非破坏性方式更新或移除
specify bundle list
specify bundle update <bundle-id> # 或 --all
specify bundle remove <bundle-id> # 仅移除此捆绑包的组件
捆绑包从一个按优先级排序的目录栈（项目 > 用户 > 内置）中解析。每个来源都带有安装策略：install-allowed 来源可用于安装，而 discovery-only 来源在 search/info 中可见但拒绝安装。可通过 specify bundle catalog list|add|remove 管理目录栈。
作者在本地校验并打包捆绑包。分发方式是托管构建产物并添加一个目录来源；社区捆绑包投稿请使用 Bundle Submission issue 模板，以便对所需的组件目录和安装证据进行审阅：
specify bundle validate --path ./my-bundle # 结构与引用检查
specify bundle build --path ./my-bundle # 生成带版本的 .zip 产物
examples/bundles/ 目录下有四份可直接阅读的示例清单（产品经理、业务分析师、安全研究员、开发者）。
关键保证：info 展示的内容与 install 添加的内容完全一致（透明性）；安装是幂等的，且限定在项目根目录内；remove 绝不会触碰其他已安装捆绑包仍需要的组件；所有消费/创作命令都能针对本地或锁定的来源离线工作。
| 目标 | 使用 |
|---|---|
| 添加全新的命令或工作流 | 扩展 |
| 定制规范、方案或任务的格式 | 预设 |
| 集成外部工具或服务 | 扩展 |
| 强制执行组织或监管规范 | 预设 |
| 交付可复用的领域特定模板 | 均可 —— 预设用于模板覆盖，扩展用于随新命令一起打包的模板 |
| 用一条命令完成完整的角色配置 | 捆绑包 |
规范驱动开发是一套结构化流程，它强调：
| 阶段 | 侧重点 | 关键活动 |
|---|---|---|
| 从 0 到 1 开发（"绿地/Greenfield"） | 从零生成 | <ul><li>从高层需求出发</li><li>生成规范</li><li>规划实现步骤</li><li>构建生产就绪的应用</li></ul> |
| 创意探索 | 并行实现 | <ul><li>探索多样化的解决方案</li><li>支持多种技术栈与架构</li><li>试验不同的用户体验模式</li></ul> |
| 迭代增强（"棕地/Brownfield"） | 存量系统现代化 | <ul><li>迭代式添加功能</li><li>现代化改造遗留系统</li><li>调整流程</li></ul> |
对于已有项目，请将 Spec Kit 工具本身的更新与功能制品的演进分开处理：升级时刷新受管理的项目文件，而在预期行为发生变化时更新 specs/ 制品。规范演进指南介绍了推荐的棕地迭代循环。
我们的研究与实验聚焦于：
如果你在使用某个助手时遇到问题，欢迎提交 issue，以便我们完善相应集成。
如需帮助，请提交 GitHub issue。我们欢迎缺陷报告、功能建议，以及关于使用规范驱动开发的各类问题。
本项目深受 John Lam 的工作与研究的影响，并在其基础上构建。
本项目基于 MIT 开源许可证的条款授权。完整条款请参阅 LICENSE 文件。