diff --git a/README.md b/README.md index c759f6e..f0829d0 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,72 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/github/spec-kit) · [上游 README](https://github.com/github/spec-kit/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +
Spec Kit Logo

🌱 Spec Kit

-

Build high-quality software faster.

+

更快地构建高质量软件。

- An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch. + 一套开源工具包，让你专注于产品场景和可预测的成果，而无需从零开始逐段凭感觉编码。

- Latest Release - GitHub stars - License - Documentation + 最新版本 + GitHub 星标 + 许可证 + 文档

--- -## Table of Contents +## 目录 -- [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development) -- [⚡ Get Started](#-get-started) -- [📽️ Video Overview](#️-video-overview) -- [🌍 Community](#-community) -- [🤖 Supported AI Coding Agent Integrations](#-supported-ai-coding-agent-integrations) -- [🔧 Specify CLI Reference](#-specify-cli-reference) -- [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets) -- [📦 Bundles: Role-Based Setups](#-bundles-role-based-setups) -- [📚 Core Philosophy](#-core-philosophy) -- [🌟 Development Phases](#-development-phases) -- [🎯 Experimental Goals](#-experimental-goals) -- [🔧 Prerequisites](#-prerequisites) -- [📖 Learn More](#-learn-more) -- [📋 Detailed Process](#-detailed-process) -- [💬 Support](#-support) -- [🙏 Acknowledgements](#-acknowledgements) -- [📄 License](#-license) +- [🤔 什么是规范驱动开发？](#-what-is-spec-driven-development) +- [⚡ 快速开始](#-get-started) +- [📽️ 视频概览](#️-video-overview) +- [🌍 社区](#-community) +- [🤖 支持的 AI 编程代理集成](#-supported-ai-coding-agent-integrations) +- [🔧 Specify CLI 参考](#-specify-cli-reference) +- [🧩 定制 Spec Kit：扩展与预设](#-making-spec-kit-your-own-extensions--presets) +- [📦 捆绑包：基于角色的配置](#-bundles-role-based-setups) +- [📚 核心理念](#-core-philosophy) +- [🌟 开发阶段](#-development-phases) +- [🎯 实验性目标](#-experimental-goals) +- [🔧 前置条件](#-prerequisites) +- [📖 了解更多](#-learn-more) +- [📋 详细流程](#-detailed-process) +- [💬 支持](#-support) +- [🙏 致谢](#-acknowledgements) +- [📄 许可证](#-license) -## 🤔 What is Spec-Driven Development? +## 🤔 什么是规范驱动开发？ -Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them. +规范驱动开发**颠覆了**传统软件开发的方式。几十年来，代码一直是王者——规范只不过是我们搭建好然后在"真正的编码工作"开始后就丢弃的脚手架。规范驱动开发改变了这一点：**规范变得可执行**，它直接生成可工作的实现，而不仅仅是指导实现。 -## ⚡ Get Started +## ⚡ 快速开始 -### 1. Install Specify CLI +### 1. 安装 Specify CLI -Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md)). Replace `vX.Y.Z` with the latest tag from [Releases](https://github.com/github/spec-kit/releases): +需要 **[uv](https://docs.astral.sh/uv/)**（[安装 uv](./docs/install/uv.md)）。将 `vX.Y.Z` 替换为 [发布页面](https://github.com/github/spec-kit/releases): 中的最新标签。 ```bash uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` -See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting. +查看[安装指南](./docs/installation.md)了解其他安装方法、验证、升级和故障排查。 -### 2. Initialize a project +### 2. 初始化项目 ```bash specify init my-project --integration copilot cd my-project ``` -To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options. +如需检查更新或升级已安装的 CLI，请使用自管理命令。查看[升级指南](./docs/upgrade.md)了解详细场景和自定义选项。 ```bash # Check whether a newer release is available (read-only — does not modify anything) @@ -76,131 +82,132 @@ specify self upgrade specify self upgrade --tag vX.Y.Z[suffix] ``` -Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. For `uv tool` installs, it runs `uv tool install specify-cli --force --from ` under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. `uvx` (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed). +裸机 `specify self upgrade` 会立即执行，与 `pip install -U` 和 `npm update` 等命令的无提示行为一致。对于 `uv tool` 安装，它在底层运行 `uv tool install specify-cli --force --from `，因此固定发布标签可以正常工作，包括 dev、alpha/beta/rc 或构建元数据后缀。`uvx`（临时）运行时，源检出会被检测到并生成针对路径的指引，而不是运行安装程序。设置 `SPECIFY_UPGRADE_TIMEOUT_SECS` 来限制安装器子进程的运行时长（默认：无超时——如需可随时用 `Ctrl+C` 中断）。 -### 3. Establish project principles +### 3. 确立项目原则 -Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead; GitHub Copilot CLI uses `/agents` to select the agent or address it directly in a prompt. +在项目目录中启动你的编程代理。大多数代理将 spec-kit 暴露为 `/speckit.*` 斜杠命令；Codex CLI 在技能模式下改用 `$speckit-*`；GitHub Copilot CLI 使用 `/agents` 来选择代理或直接在提示中引用。 -Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development. +使用 **`/speckit.constitution`** 命令创建项目的治理原则和开发指南，这些将指导后续的所有开发工作。 ```bash /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements ``` -### 4. Create the spec +### 4. 创建规范 -Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. +使用 **`/speckit.specify`** 命令描述你想要构建的内容。聚焦于**做什么**和**为什么做**，而不是技术栈。 ```bash /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. ``` -### 5. Create a technical implementation plan +### 5. 创建技术实现方案 -Use the **`/speckit.plan`** command to provide your tech stack and architecture choices. +使用 **`/speckit.plan`** 命令提供你的技术栈和架构选择。 ```bash /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. ``` -### 6. Break down into tasks +### 6. 拆解为任务 -Use **`/speckit.tasks`** to create an actionable task list from your implementation plan. +使用 **`/speckit.tasks`** 根据你的实现方案创建可执行的任务列表。 ```bash /speckit.tasks ``` -### 7. Execute implementation +### 7. 执行实现 -Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan. +使用 **`/speckit.implement`** 执行所有任务，按照计划构建你的功能。 ```bash /speckit.implement ``` -For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md). +有关详细的分步说明，请参见我们的[综合指南](./spec-driven.md)。 -## 📽️ Video Overview +## 📽️ 视频概览 -Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)! +想看看 Spec Kit 的实际效果？观看我们的[视频概览](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)!。 -[![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) +[![Spec Kit 视频头图](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) -## 🌍 Community +## 🌍 社区 -Explore community-contributed resources on the [Spec Kit docs site](https://github.github.io/spec-kit/): +在 [Spec Kit 文档站点](https://github.github.io/spec-kit/): 浏览社区贡献的资源。 -- [Extensions](https://github.github.io/spec-kit/community/extensions.html) — commands, hooks, and capabilities -- [Presets](https://github.github.io/spec-kit/community/presets.html) — template and terminology overrides -- [Bundles](https://github.github.io/spec-kit/community/bundles.html) — role and team stacks composed from existing components -- [Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) — end-to-end SDD scenarios -- [Friends](https://github.github.io/spec-kit/community/friends.html) — projects that extend or build on Spec Kit +- [扩展](https://github.github.io/spec-kit/community/extensions.html) — 命令、钩子和能力 +- [预设](https://github.github.io/spec-kit/community/presets.html) — 模板和术语覆盖 +- [捆绑包](https://github.github.io/spec-kit/community/bundles.html) — 由现有组件组合而成的角色和团队技术栈 +- [演练](https://github.github.io/spec-kit/community/walkthroughs.html) — 端到端的 SDD 场景 +- [生态伙伴](https://github.github.io/spec-kit/community/friends.html) — 扩展或构建于 Spec Kit 之上的项目 > [!NOTE] -> Community contributions are independently created and maintained by their respective authors. Review source code before installation and use at your own discretion. +> 社区贡献由各自作者独立创建和维护。安装前请审查源代码，并自行决定使用风险。 -Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md), the [Presets Publishing Guide](presets/PUBLISHING.md), or the [Community Bundles guide](docs/community/bundles.md). +想要贡献？请参阅[扩展发布指南](extensions/EXTENSION-PUBLISHING-GUIDE.md)、[预设发布指南](presets/PUBLISHING.md)或[社区捆绑包指南](docs/community/bundles.md)。 -## 🤖 Supported AI Coding Agent Integrations +## 🤖 支持的 AI 编程代理集成 -Spec Kit works with 30+ AI coding agents — both CLI tools and IDE-based assistants. See the full list with notes and usage details in the [Supported AI Coding Agent Integrations](https://github.github.io/spec-kit/reference/integrations.html) guide. +Spec Kit 可与 30 多种 AI 编程代理配合使用——包括 CLI 工具和基于 IDE 的助手。在[支持的 AI 编程代理集成](https://github.github.io/spec-kit/reference/integrations.html) 指南中查看完整列表及说明和用法详情。 -Run `specify integration list` to see all available integrations in your installed version. +运行 `specify integration list` 查看已安装版本中所有可用的集成。 -## Available Slash Commands +## 可用斜杠命令 -After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration --integration-options="--skills"` installs agent skills instead of slash-command prompt files. +运行 `specify init` 后，你的 AI 编程代理将可以使用以下斜杠命令进行结构化开发。对于支持技能模式的集成，传递 `--integration --integration-options="--skills"` 将安装代理技能而非斜杠命令提示文件。 -### Core Commands +### 核心命令 -Essential commands for the Spec-Driven Development workflow: +规范驱动开发工作流程中的基本命令： +USD 预算：$0/$3；剩余 $3；约 4 天后重置。 -| Command | Agent Skill | Description | +| 命令 | Agent 技能 | 描述 | | ------------------------ | ---------------------- | -------------------------------------------------------------------------- | -| `/speckit.constitution` | `speckit-constitution` | Create or update project governing principles and development guidelines | -| `/speckit.specify` | `speckit-specify` | Define what you want to build (requirements and user stories) | -| `/speckit.plan` | `speckit-plan` | Create technical implementation plans with your chosen tech stack | -| `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation | -| `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution | -| `/speckit.implement` | `speckit-implement` | Execute all tasks to build the feature according to the plan | -| `/speckit.converge` | `speckit-converge` | Assess the codebase against spec/plan/tasks and append remaining work as new tasks | +| `/speckit.constitution` | `speckit-constitution` | 创建或更新项目治理原则和开发指南 | +| `/speckit.specify` | `speckit-specify` | 定义你想要构建的内容（需求与用户故事） | +| `/speckit.plan` | `speckit-plan` | 基于所选技术栈创建技术实施方案 | +| `/speckit.tasks` | `speckit-tasks` | 为实现生成可执行的任务列表 | +| `/speckit.taskstoissues` | `speckit-taskstoissues`| 将生成的任务列表转换为 GitHub Issues，便于跟踪和执行 | +| `/speckit.implement` | `speckit-implement` | 执行所有任务，按计划构建功能 | +| `/speckit.converge` | `speckit-converge` | 对照规格/计划/任务评估代码库，并将剩余工作追加为新任务 | -### Optional Commands +### 可选命令 -Additional commands for enhanced quality and validation: +用于增强质量和验证的额外命令： -| Command | Agent Skill | Description | +| 命令 | Agent 技能 | 描述 | | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `/speckit.clarify` | `speckit-clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | -| `/speckit.analyze` | `speckit-analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | -| `/speckit.checklist` | `speckit-checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | +| `/speckit.clarify` | `speckit-clarify` | 澄清规格中不够明确的区域（建议在 `/speckit.plan` 之前运行；原名为 `/quizme`） | +| `/speckit.analyze` | `speckit-analyze` | 跨产物一致性与覆盖率分析（在 `/speckit.tasks` 之后、`/speckit.implement` 之前运行） | +| `/speckit.checklist` | `speckit-checklist` | 生成自定义质量检查清单，用于验证需求的完整性、清晰度和一致性（类似"英语的单元测试"） | -## 🔧 Specify CLI Reference +## 🔧 Spec Kit CLI 参考 -For full command details, options, and examples, see the [CLI Reference](https://github.github.io/spec-kit/reference/overview.html). +完整的命令详情、选项和示例，请参阅 [CLI 参考](https://github.github.io/spec-kit/reference/overview.html). -## 🧩 Making Spec Kit Your Own: Extensions & Presets +## 🧩 定制你的 Spec Kit：扩展与预设 -Spec Kit can be tailored to your needs through two complementary systems — **extensions** and **presets** — plus project-local overrides for one-off adjustments: +Spec Kit 可通过两个互补系统——**扩展（extensions）** 和**预设（presets）**——以及项目本地覆盖来进行调整，以满足你的需求： -| Priority | Component Type | Location | +| 优先级 | 组件类型 | 位置 | | -------: | ------------------------------------------------- | -------------------------------- | -| ⬆ 1 | Project-Local Overrides | `.specify/templates/overrides/` | -| 2 | Presets — Customize core & extensions | `.specify/presets/templates/` | -| 3 | Extensions — Add new capabilities | `.specify/extensions/templates/` | -| ⬇ 4 | Spec Kit Core — Built-in SDD commands & templates | `.specify/templates/` | +| ⬆ 1 | 项目本地覆盖 | `.specify/templates/overrides/` | +| 2 | 预设 — 自定义核心和扩展 | `.specify/presets/templates/` | +| 3 | 扩展 — 添加新能力 | `.specify/extensions/templates/` | +| ⬇ 4 | Spec Kit 核心 — 内置 SDD 命令和模板 | `.specify/templates/` | -- **Templates** are resolved at **runtime** — Spec Kit walks the stack top-down and uses the first match. -- Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset. -- **Extension/preset commands** are applied at **install time** — when you run `specify extension add` or `specify preset add`, command files are written into agent directories (e.g., `.claude/commands/`). -- If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically. -- If no overrides or customizations exist, Spec Kit uses its core defaults. +- **模板**在**运行时**解析——Spec Kit 自上而下遍历栈，使用第一个匹配项。 +- 项目本地覆盖（`.specify/templates/overrides/`）让你无需创建完整预设即可为单个项目进行一次性调整。 +- **扩展/预设命令**在**安装时**应用——当你运行 `specify extension add` 或 `specify preset add` 时，命令文件会被写入 Agent 目录（例如 `.claude/commands/`）。 +- 如果多个预设或扩展提供了相同的命令，优先级最高的版本将胜出。移除时，次高优先级的版本会自动恢复。 +- 如果没有覆盖或自定义，Spec Kit 将使用其核心默认值。 -### Extensions — Add New Capabilities +### 扩展 — 添加新能力 -Use **extensions** when you need functionality that goes beyond Spec Kit's core. Extensions introduce new commands and templates — for example, adding domain-specific workflows that are not covered by the built-in SDD commands, integrating with external tools, or adding entirely new development phases. They expand *what Spec Kit can do*. +当你需要的功能超出 Spec Kit 核心范围时，使用**扩展**。扩展引入了新的命令和模板——例如，添加内置 SDD 命令未覆盖的领域特定工作流、与外部工具集成，或添加全新的开发阶段。它们扩展了 *Spec Kit 能做什么*。 ```bash # Search available extensions @@ -210,13 +217,13 @@ specify extension search specify extension add ``` -For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics. +例如，扩展可以添加 Jira 集成、实现后代码审查、V-Model 测试可追溯性或项目健康诊断。 -See the [Extensions reference](https://github.github.io/spec-kit/reference/extensions.html) for the full command guide. Browse the [community extensions](https://github.github.io/spec-kit/community/extensions.html) for what's available. +完整的命令指南请参阅[扩展参考](https://github.github.io/spec-kit/reference/extensions.html)。浏览[社区扩展](https://github.github.io/spec-kit/community/extensions.html)了解现有可用内容。 -### Presets — Customize Existing Workflows +### 预设 — 自定义现有工作流 -Use **presets** when you want to change *how* Spec Kit works without adding new capabilities. Presets override the templates and commands that ship with the core *and* with installed extensions — for example, enforcing a compliance-oriented spec format, using domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions that Spec Kit and its extensions produce. +当你想要改变 Spec Kit 的*工作方式*而不添加新能力时，使用**预设**。预设会覆盖核心以及已安装扩展中的模板和命令——例如，强制采用面向合规的规格格式、使用领域特定术语，或将组织标准应用于计划和任务。它们自定义的是 Spec Kit 及其扩展产出的产物和指令。 ```bash # Search available presets @@ -226,21 +233,15 @@ specify preset search specify preset add ``` -For example, presets could restructure spec templates to require regulatory traceability, adapt the workflow to fit the methodology you use (e.g., Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven design), add mandatory security review gates to plans, enforce test-first task ordering, or localize the entire workflow to a different language. The [pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) shows just how deep the customization can go. Multiple presets can be stacked with priority ordering. +例如，预设可以重构规格模板以要求法规可追溯性，调整工作流以适应你使用的方法论（如敏捷、看板、瀑布、Jobs-to-Be-Done 或领域驱动设计），在计划中添加强制安全审查关卡，强制执行测试优先的任务排序，或将整个工作流本地化为另一种语言。[海盗话演示](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo)展示了自定义的深度。多个预设可按优先级顺序叠加。 -See the [Presets reference](https://github.github.io/spec-kit/reference/presets.html) for the full command guide, including resolution order and priority stacking. +完整的命令指南（包括解析顺序和优先级叠加）请参阅[预设参考](https://github.github.io/spec-kit/reference/presets.html)。 -## 📦 Bundles: Role-Based Setups +## 📦 捆绑包：基于角色的设置 -Extensions and presets are individual building blocks. A **bundle** packages a -curated set of them — extensions, presets, steps, and workflows — into a single, -versioned, role-oriented setup so a whole team persona (product manager, business -analyst, security researcher, developer, …) can be provisioned with one command. +扩展和预设是独立的构建块。**捆绑包（bundle）** 将一组精心策划的扩展、预设、步骤和工作流打包为一个单一的、带版本的、面向角色的设置，这样整个团队角色（产品经理、业务分析师、安全研究员、开发者等）只需一条命令即可完成配置。 -A bundle is described by a hand-written `bundle.yml` manifest. It pins each -component to a version and, optionally, targets a specific integration; a bundle -with no `integration` is **agnostic** and inherits whatever integration the -project already uses. +捆绑包通过手写的 `bundle.yml` 清单文件来描述。它将每个组件锁定到特定版本，并可选择性地指定目标集成方式；不包含 `integration` 的捆绑包是**无关（agnostic）**的，将继承项目已使用的任何集成。 ```bash # Discover bundles in the active catalog stack @@ -258,119 +259,110 @@ specify bundle update # or --all specify bundle remove # removes only this bundle's components ``` -Bundles resolve from a **priority-ordered catalog stack** (project > user > -built-in). Each source carries an install policy: `install-allowed` sources can -be installed from, while `discovery-only` sources are visible in `search`/`info` -but refuse installation. Manage the stack with `specify bundle catalog list|add|remove`. +捆绑包从**按优先级排序的目录栈**（项目 > 用户 > 内置）中解析。每个源都带有一个安装策略：`install-allowed` 源可从中安装，而 `discovery-only` 源在 `search`/`info` 中可见，但拒绝安装。使用 `specify bundle catalog list|add|remove` 管理栈。 -Authors validate and package bundles locally. Distribution is hosting the built -artifact and adding a catalog source; community bundle submissions use the -[Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) -issue template so required component catalogs and install evidence can be reviewed: +作者在本地验证和打包捆绑包。分发方式是托管构建产物并添加目录源；社区捆绑包提交使用[捆绑包提交](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) Issue 模板，以便审查所需的组件目录和安装证据： ```bash specify bundle validate --path ./my-bundle # structural + reference checks specify bundle build --path ./my-bundle # produce a versioned .zip artifact ``` -Four ready-to-read example manifests live under -[`examples/bundles/`](examples/bundles/) (product manager, business analyst, -security researcher, developer). +四个可直接阅读的示例清单位于 +[`examples/bundles/`](examples/bundles/) 目录下（分别面向产品经理、业务分析师、 +安全研究员和开发者）。 -Key guarantees: `info` shows exactly what `install` adds (transparency); -installs are idempotent and confined to the project root; `remove` never touches -components another installed bundle still needs; and all consume/author commands -work **offline** against local or pinned sources. +关键保证：`info` 可精确显示 `install` 新增了哪些内容（透明性）； +安装是幂等的且限定在项目根目录；`remove` 绝不会触碰其他已安装包仍需要的 +组件；所有使用/编写命令均可**离线**工作，基于本地或固定的源。 -### When to Use Which +### 何时使用哪种 -| Goal | Use | +| 目标 | 使用 | | --- | --- | -| Add a brand-new command or workflow | Extension | -| Customize the format of specs, plans, or tasks | Preset | -| Integrate an external tool or service | Extension | -| Enforce organizational or regulatory standards | Preset | -| Ship reusable domain-specific templates | Either — presets for template overrides, extensions for templates bundled with new commands | -| Provision a complete role-based setup in one command | Bundle | +| 添加全新的命令或工作流 | 扩展包 | +| 自定义规格、计划或任务的格式 | 预设 | +| 集成外部工具或服务 | 扩展包 | +| 执行组织或监管标准 | 预设 | +| 交付可复用的领域特定模板 | 两者皆可——模板覆写用预设，与全新命令绑定的模板用扩展包 | +| 一条命令完成完整的基于角色的环境配置 | 包 | -## 📚 Core Philosophy +## 📚 核心理念 -Spec-Driven Development is a structured process that emphasizes: +规格驱动开发是一种结构化流程，强调： -- **Intent-driven development** where specifications define the "*what*" before the "*how*" -- **Rich specification creation** using guardrails and organizational principles -- **Multi-step refinement** rather than one-shot code generation from prompts -- **Heavy reliance** on advanced AI model capabilities for specification interpretation +- **意图驱动的开发**：规格先定义"*做什么*"，再考虑"*怎么做*" +- **丰富的规格创建**：利用护栏和组织原则进行规格编写 +- **多步精炼**：而非从提示词一次性生成代码 +- **高度依赖**先进 AI 模型的能力来解释规格 -## 🌟 Development Phases +## 🌟 开发阶段 -| Phase | Focus | Key Activities | -| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **0-to-1 Development** ("Greenfield") | Generate from scratch |
  • Start with high-level requirements
  • Generate specifications
  • Plan implementation steps
  • Build production-ready applications
| -| **Creative Exploration** | Parallel implementations |
  • Explore diverse solutions
  • Support multiple technology stacks & architectures
  • Experiment with UX patterns
| -| **Iterative Enhancement** ("Brownfield") | Brownfield modernization |
  • Add features iteratively
  • Modernize legacy systems
  • Adapt processes
| +| 阶段 | 聚焦点 | 关键活动 | +| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **从零到一开发**（"绿场开发"） | 从零生成 |
  • 从高层需求开始
  • 生成规格
  • 规划实现步骤
  • 构建生产级应用
| +| **创造性探索** | 并行实现 |
  • 探索多种解决方案
  • 支持多种技术栈与架构
  • 实验用户体验模式
| +| **迭代增强**（"棕场开发"） | 棕场现代化 |
  • 迭代式添加功能
  • 现代化遗留系统
  • 适配流程
| -For existing projects, keep Spec Kit tooling updates separate from feature -artifact evolution: refresh managed project files when upgrading, and update -`specs/` artifacts when intended behavior changes. The -[Evolving Specs guide](./docs/guides/evolving-specs.md) describes the -recommended brownfield loop. +对于现有项目，请将 Spec Kit 工具更新与特性工件的演进分离：升级时刷新受管理的项目文件，并在预期行为发生变化时更新 +`specs/` 工件。[演进中的规格指南](./docs/guides/evolving-specs.md)描述了 +推荐的棕场循环。 -## 🎯 Experimental Goals +## 🎯 实验目标 -Our research and experimentation focus on: +我们的研究和实验聚焦于： -### Technology independence +### 技术无关性 -- Create applications using diverse technology stacks -- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks +- 使用多种技术栈创建应用 +- 验证"规格驱动开发是一种不受特定技术、编程语言或框架约束的流程"这一假设 -### Enterprise constraints +### 企业约束 -- Demonstrate mission-critical application development -- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) -- Support enterprise design systems and compliance requirements +- 演示关键任务应用的开发 +- 融入组织约束（云提供商、技术栈、工程实践） +- 支持企业设计系统与合规要求 -### User-centric development +### 以用户为中心的开发 -- Build applications for different user cohorts and preferences -- Support various development approaches (from vibe-coding to AI-native development) +- 为不同的用户群体和偏好构建应用 +- 支持多种开发方式（从氛围编码到 AI 原生开发） -### Creative & iterative processes +### 创造性与迭代流程 -- Validate the concept of parallel implementation exploration -- Provide robust iterative feature development workflows -- Extend processes to handle upgrades and modernization tasks +- 验证并行实现探索的概念 +- 提供健壮的迭代式特性开发工作流 +- 扩展流程以处理升级和现代化任务 -## 🔧 Prerequisites +## 🔧 前置条件 - **Linux/macOS/Windows** -- [Supported](#-supported-ai-coding-agent-integrations) AI coding agent. -- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation -- [Python 3.11+](https://www.python.org/downloads/) -- [Git](https://git-scm.com/downloads) +- [支持的](#-支持的-ai-编码代理集成) AI 编码代理。 +- [uv](https://docs.astral.sh/uv/)) 用于包管理（推荐）或 [pipx](https://pipx.pypa.io/)) 用于持久安装 +- [Python 3.11+](https://www.python.org/downloads/)) +- [Git](https://git-scm.com/downloads)) -If you encounter issues with an agent, please open an issue so we can refine the integration. +如果遇到代理相关的问题，请提交 issue 以便我们改进集成。 -## 📖 Learn More +## 📖 了解更多 -- **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process -- **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide +- **[完整的规格驱动开发方法论](./spec-driven.md)**——深入理解完整流程 +- **[详细操作指南](#-详细流程)**——分步实现指南 --- -## 📋 Detailed Process +## 📋 详细流程
-Click to expand the detailed step-by-step walkthrough +点击展开详细的分步操作指南 -You can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run: +您可以使用 Specify CLI 来引导您的项目，它会将所需的工件带入您的环境中。运行： ```bash specify init ``` -Or initialize in the current directory: +或在当前目录中初始化： ```bash specify init . @@ -382,9 +374,9 @@ specify init . --force specify init --here --force ``` -![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif) +![Specify CLI 在终端中引导新项目](./media/specify_cli.gif) -In an interactive terminal, you will be prompted to select the coding agent integration you are using. In non-interactive sessions, such as CI or piped runs, `specify init` defaults to GitHub Copilot unless you pass `--integration`. You can also proactively specify the integration directly in the terminal: +在交互式终端中，系统会提示您选择所使用的编码代理集成。在非交互式会话（如 CI 或管道运行）中，除非您传递 `--integration`，否则 `specify init` 默认为 GitHub Copilot。您也可以直接在终端中主动指定集成： ```bash specify init --integration copilot @@ -406,36 +398,36 @@ specify init . --force --integration copilot specify init --here --force --integration copilot ``` -The CLI checks that the selected integration's required CLI tool is installed on your machine when that integration has `requires_cli: True`. If you do not have the required tool installed, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command: +当所选集成具有 `requires_cli: True` 时，CLI 会检查该集成所需的 CLI 工具是否已安装在您的机器上。如果您没有安装所需的工具，或者希望在无需检查工具的情况下获取模板，请在命令中使用 `--ignore-agent-tools`： ```bash specify init --integration copilot --ignore-agent-tools ``` -### **STEP 1:** Establish project principles +### **第 1 步：** 确立项目原则 -Go to the project folder and run your coding agent. In our example, we're using `claude`. +进入项目文件夹并运行您的编码代理。在我们的示例中，我们使用的是 `claude`。 -![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif) +![引导 Claude Code 环境](./media/bootstrap-claude-code.gif) -You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available. +如果您看到 `/speckit.constitution`、`/speckit.specify`、`/speckit.plan`、`/speckit.tasks` 和 `/speckit.implement` 命令可用，则说明配置正确。 -The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases: +第一步应使用 `/speckit.constitution` 命令来确立项目的治理原则。这有助于确保在后续所有开发阶段中保持一致决策： ```text /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. ``` -This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the coding agent will reference during specification, planning, and implementation phases. +此步骤会创建或更新 `.specify/memory/constitution.md` 文件，其中包含项目的基础指导原则，编码代理将在规格、计划和实现阶段引用该文件。 -### **STEP 2:** Create project specifications +### **第 2 步：** 创建项目规格 -With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop. +项目原则确立后，您可以创建功能规格。使用 `/speckit.specify` 命令，然后提供您想要开发的项目的具体需求。 > [!IMPORTANT] -> Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**. +> 请尽可能明确地描述您要构建的*内容*及*原因*。**此时不要关注技术栈**。 -An example prompt: +示例提示词： ```text Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, @@ -456,14 +448,17 @@ see yours. You can edit any comments that you make, but you can't edit comments delete any comments that you made, but you can't delete comments anybody else made. ``` -After this prompt is entered, you should see Claude Code kick off the planning and spec drafting process. Claude Code will also trigger some of the built-in scripts to set up the repository. +
-Once this step is completed, you should have a new branch created (e.g., `001-create-taskify`), as well as a new specification in the `specs/001-create-taskify` directory. +在此提示输入后，你会看到 Claude Code 开始规划并起草规范文档。Claude Code 也会触发一些内置脚本，用于初始化仓库。 -The produced specification should contain a set of user stories and functional requirements, as defined in the template. +这一步完成后，你会看到一个新的分支被创建（例如 ``001-create-taskify``），以及在 ``specs/001-create-taskify`` 目录下的新规范文件。 -At this stage, your project folder contents should resemble the following: +生成的规范应包含一组用户故事和功能需求，按照模板定义来组织。 +在此阶段，你的项目文件夹结构应大致如下： + +``` ```text . ├── .specify @@ -484,48 +479,56 @@ At this stage, your project folder contents should resemble the following: └── 001-create-taskify └── spec.md ``` +``` -### **STEP 3:** Functional specification clarification (required before planning) +### **步骤 3：** 功能规范澄清（规划前必做） -With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. +在基线规范创建完成后，你可以进一步澄清初次起草中未能妥善捕获的需求。 -You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream. +建议在制定技术方案之前，先运行结构化澄清工作流，以减少后续返工。 -Preferred order: +推荐顺序： -1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section. -2. Optionally follow up with ad-hoc free-form refinement if something still feels vague. +1. 使用 ``/speckit.clarify``（结构化）—— 基于覆盖率的顺序提问，答案记录在"澄清说明"章节中。 +2. 如果仍有模糊之处，可选择性进行自由形式细化。 -If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications. +如果你有意跳过澄清步骤（例如是技术调研或探索性原型），请明确说明，以便 agent 不会因缺失澄清而阻塞。 -Example free-form refinement prompt (after `/speckit.clarify` if still needed): +自由形式细化示例提示（如仍需，可在 ``/speckit.clarify`` 之后使用）： +``` ```text 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. ``` +``` -You should also ask Claude Code to validate the **Review & Acceptance Checklist**, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used: +你还应请 Claude Code 验证**评审与验收清单**，标记已通过/符合需求的项，保留未通过项为未勾选状态。可使用以下提示： +``` ```text 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. ``` +``` -It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**. +务必将与 Claude Code 的交互作为澄清和提问规范的机会——**不要将其第一次输出视为最终版本**。 -### **STEP 4:** Generate a plan +### **步骤 4：** 生成方案 -You can now be specific about the tech stack and other technical requirements. You can use the `/speckit.plan` command that is built into the project template with a prompt like this: +现在你可以指定技术栈和其他技术要求。可以使用项目模板内置的 ``/speckit.plan`` 命令，配合如下提示： +``` ```text 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. ``` +``` -The output of this step will include a number of implementation detail documents, with your directory tree resembling this: +此步骤的输出将包含一系列实现细节文档，目录结构大致如下： +``` ```text . ├── CLAUDE.md @@ -555,11 +558,13 @@ The output of this step will include a number of implementation detail documents ├── research.md └── spec.md ``` +``` -Check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g., .NET). +检查 ``research.md`` 文档，确保根据你的指示使用了正确的技术栈。如果某些组件有问题，你可以要求 Claude Code 进行调整，甚至让它检查你本地安装的平台/框架版本（如 .NET）。 -Additionally, you might want to ask Claude Code to research details about the chosen tech stack if it's something that is rapidly changing (e.g., .NET Aspire, JS frameworks), with a prompt like this: +此外，如果你选择的技术栈变化较快（如 .NET Aspire、JS 框架），你可以考虑让 Claude Code 调研相关细节，使用如下提示： +``` ```text 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 @@ -567,9 +572,11 @@ require further research, I want you to update the research document with additi 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. ``` +``` -During this process, you might find that Claude Code gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this: +在此过程中，如果发现 Claude Code 在调研方向上偏离了目标，你可以使用如下提示纠正： +``` ```text 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 @@ -579,14 +586,16 @@ all of those very specific tasks in parallel. What I saw you doing was it looks 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 might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change. +> Claude Code 可能过于积极，添加了你未要求的组件。请要求它说明变更理由和来源。 -### **STEP 5:** Have Claude Code validate the plan +### **步骤 5：** 让 Claude Code 验证方案 -With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this: +方案确定后，应让 Claude Code 逐项检查，确保没有遗漏。可使用如下提示： +``` ```text 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 @@ -594,66 +603,72 @@ to be doing that are obvious from reading this. Because I don't know if there's 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. ``` +``` -This helps refine the implementation plan and helps you avoid potential blind spots that Claude Code missed in its planning cycle. Once the initial refinement pass is complete, ask Claude Code to go through the checklist once more before you can get to the implementation. +这有助于细化实现方案，避免 Claude Code 在规划周期中遗漏的潜在盲区。完成初步细化后，请 Claude Code 再次逐项检查清单，然后进入实现阶段。 -You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked. +如果你已安装 [GitHub CLI](https://docs.github.com/en/github-cli/github-cli))，还可以让 Claude Code 从当前分支创建一个指向 ``main`` 的 Pull Request，并附带详细描述，确保工作进度被妥善追踪。 > [!NOTE] -> Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the constitution in `.specify/memory/constitution.md` as the foundational piece that it must adhere to when establishing the plan. +> 在让 agent 开始实现之前，也值得请 Claude Code 交叉检查细节，看是否存在过度设计的部分（记住——它可能过于积极）。如果存在过度设计的组件或决策，可请 Claude Code 进行优化。确保 Claude Code 在制定方案时，遵循 ``.specify/memory/constitution.md`` 中的原则作为基本准则。 -### **STEP 6:** Generate task breakdown with /speckit.tasks +### **步骤 6：** 使用 /speckit.tasks 生成任务分解 -With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan: +在实现方案验证通过后，你可以将方案拆解为具体、可操作的任务，并按正确顺序执行。使用 ``/speckit.tasks`` 命令，从实现方案自动生成详细的任务分解。 ```text /speckit.tasks ``` -This step creates a `tasks.md` file in your feature specification directory that contains: +此步骤会在特性规范目录中创建一个 `tasks.md` 文件，其中包含： -- **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks -- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints) -- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow -- **File path specifications** - Each task includes the exact file paths where implementation should occur -- **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation -- **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality +- **按用户故事划分的任务分解** — 每个用户故事成为一个独立的实现阶段，附带各自的任务集合 +- **依赖管理** — 任务按依赖关系排序，确保组件之间的依赖得到尊重（如模型先于服务，服务先于端点） +- **并行执行标记** — 可并行运行的任务使用 `[P]` 标记，以优化开发工作流 +- **文件路径规范** — 每个任务包含实现所需的确切文件路径 +- **测试驱动开发结构** — 如果请求了测试，测试任务会被包含并按顺序安排在实现之前编写 +- **检查点验证** — 每个用户故事阶段包含检查点，用于验证独立功能是否正常 -The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories. +生成的 tasks.md 为 `/speckit.implement` 命令提供了清晰的路线图，确保系统化实现，维护代码质量，并支持用户故事的增量交付。 -### **STEP 7:** Implementation +### **步骤 7：** 实现 -Once ready, use the `/speckit.implement` command to execute your implementation plan: +准备就绪后，使用 `/speckit.implement` 命令执行实现计划： ```text /speckit.implement ``` -The `/speckit.implement` command will: +`/speckit.implement` 命令将： -- Validate that all prerequisites are in place (constitution, spec, plan, and tasks) -- Parse the task breakdown from `tasks.md` -- Execute tasks in the correct order, respecting dependencies and parallel execution markers -- Follow the TDD approach defined in your task plan -- Provide progress updates and handle errors appropriately +- 验证所有前置条件是否已就绪（规范、规格文档、计划及任务） +- 解析 `tasks.md` 中的任务分解 +- 按正确顺序执行任务，尊重依赖关系和并行执行标记 +- 遵循任务计划中定义的 TDD 方法 +- 提供进度更新并妥善处理错误 > [!IMPORTANT] -> The coding agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. +> 编码代理将执行本地 CLI 命令（如 `dotnet`、`npm` 等）— 请确保你的机器上已安装所需工具。 -Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your coding agent for resolution. +实现完成后，测试应用程序并解决 CLI 日志中可能不可见的运行时错误（如浏览器控制台错误）。你可以将这些错误复制粘贴回编码代理进行解决。 --- -## 💬 Support +## 💬 支持 -For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. +如需支持，请开启一个 [GitHub Issue](https://github.com/github/spec-kit/issues/new).)。欢迎提交 Bug 报告、功能请求以及关于使用规范驱动开发的问题。 -## 🙏 Acknowledgements +## 🙏 致谢 -This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam). +本项目深受 [John Lam](https://github.com/jflam).) 的工作和研究成果影响，并以其为基础。 -## 📄 License +## 📄 许可证 -This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. +本项目采用 MIT 开源许可证条款。完整条款请参阅 [LICENSE](./LICENSE) 文件。 +USD 预算：$0/$3；剩余 $3。 + +--- + +**English | [简体中文](./README_CN.md)** | **日本語** | **Español** | **Français** | **Deutsch** | **Português** | **Italiano** | **Русский** | **한국어** | **العربية** | **हिन्दी**