Back to Details

spec-kit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-Driven Development

规范驱动开发

Turn a feature idea into a structured, reviewable spec before a single line of code is written. The workflow has three phases, each producing a file in 
specs/<spec-name>/
. You move forward only when the user approves the current phase — this keeps the plan grounded in what they actually want.
specs/<spec-name>/
├── spec.md         ← Phase 0: Spec metadata (type, workflow)
├── requirements.md ← Phase 1: What to build
├── design.md       ← Phase 2: How to build it
└── tasks.md        ← Phase 3: Ordered implementation steps
在编写任何一行代码之前，将功能想法转化为结构化、可评审的规范。工作流分为三个阶段，每个阶段都会在
specs/<spec-name>/
目录下生成一个文件。只有当用户批准当前阶段的产出后才能进入下一阶段——这可以确保规划始终贴合用户的实际需求。
specs/<spec-name>/
├── spec.md         ← 阶段 0: 规范元数据（类型、工作流）
├── requirements.md ← 阶段 1: 要构建的内容
├── design.md       ← 阶段 2: 如何构建
└── tasks.md        ← 阶段 3: 有序的实现步骤

Phase 0: Spec

阶段 0: 规范

Before writing anything, nail down the spec name and create the folder.
  1. If the user hasn't named the spec, propose a short slug (e.g., 
    user-auth
    , 
    export-csv
    ).
  2. Confirm with the user the spec name (and also the slug).
  3. Add a number to the slug, it must be an increment of the last spec created inside 
    specs/
    (e.g., 
    001
    , 
    002
    ).
  4. Create 
    specs/<spec-name>/
    in the repo root. 
    <spec-name> = <number>-<spec-slug>
    (e.g., 
    001-user-auth
    , 
    002-export-csv
    ).
Read 
./references/templates/spec.md
before writing this file.
Write 
specs/<spec-name>/spec.md
. No details are required at this stage, just metadata.
Note: Use the YAML frontmatter to track spec type and workflow, currently 
type: feature
and 
workflow: requirements-first
.
在编写任何内容之前，先确定规范名称并创建文件夹。
  1. 如果用户尚未命名规范，建议一个简短的标识（例如 
    user-auth
    、
    export-csv
    ）。
  2. 与用户确认规范名称（以及对应的标识）。
  3. 在标识前添加编号，编号必须为
    specs/
    目录下已创建的最后一个规范编号的递增数字（例如 
    001
    、
    002
    ）。
  4. 在仓库根目录下创建
    specs/<spec-name>/
    文件夹，
    <spec-name> = <编号>-<规范标识>
    （例如 
    001-user-auth
    、
    002-export-csv
    ）。
在编写该文件前请先阅读
./references/templates/spec.md
。
编写
specs/<spec-name>/spec.md
文件。此阶段不需要详细内容，仅需元数据即可。
注意： 使用YAML frontmatter来记录规范类型和工作流，当前使用 
type: feature
和 
workflow: requirements-first
。

Phase 1: Requirements

阶段 1: 需求

Goal: Capture what the system must do, in unambiguous terms the user can validate.
Read 
./references/templates/requirements.md
before writing this file.
Write 
specs/<spec-name>/requirements.md
using EARS notation for user stories:
WHEN [condition/event] THE SYSTEM SHALL [expected behavior]
Group stories by user-facing goal. For each story, list concrete acceptance criteria — the conditions a reviewer could check to say "done".
Iterate: Share the draft. Ask: "Does this capture everything? Anything missing or off?" Revise until approved, when approved update the YAML frontmatter, then move to Phase 2.
Note: Use the YAML frontmatter to track document status.
目标： 用用户可以验证的无歧义表述，明确系统必须实现的功能。
在编写该文件前请先阅读
./references/templates/requirements.md
。
使用EARS notation编写用户故事，生成
specs/<spec-name>/requirements.md
文件：
WHEN [条件/事件] THE SYSTEM SHALL [预期行为]
按照面向用户的目标对用户故事进行分组。为每个故事列出具体的验收标准——即评审人员可以用来判定“已完成”的条件。
迭代： 分享草稿，询问：“是否涵盖了所有内容？有没有遗漏或错误的地方？” 持续修订直到获得批准，批准后更新YAML frontmatter，然后进入阶段2。
注意： 使用YAML frontmatter来记录文档状态。

Phase 2: Design

阶段 2: 设计

Goal: Decide how the system will fulfill the requirements — before writing code.
Read 
./references/templates/design.md
before writing this file.
Write 
specs/<spec-name>/design.md
. Every significant decision should trace back to a requirement. Use Mermaid for sequence/flow diagrams where it adds clarity; plain prose otherwise.
Cover:
  • High-level architecture and component responsibilities
  • Data models and storage
  • Key interfaces / API contracts
  • Critical flows as sequence diagrams
  • Error handling and edge cases
  • Testing strategy (what to unit-test vs. integrate-test)
Iterate: Share the draft. Ask: "Does this approach make sense? Any concerns?" Revise until approved, when approved update the YAML frontmatter, then move to Phase 3.
Note: Use the YAML frontmatter to track document status.
目标： 在编写代码之前，确定系统如何满足需求。
在编写该文件前请先阅读
./references/templates/design.md
。
编写
specs/<spec-name>/design.md
文件。每个重要决策都要对应到具体的需求。如果可以提升清晰度，可以使用Mermaid绘制时序/流程图，否则使用普通文本即可。
内容需覆盖：
  • 高层架构和组件职责
  • 数据模型和存储
  • 核心接口 / API契约
  • 关键流程的时序图
  • 错误处理和边界场景
  • 测试策略（单元测试和集成测试的范围划分）
迭代： 分享草稿，询问：“这个方案是否合理？有没有什么问题？” 持续修订直到获得批准，批准后更新YAML frontmatter，然后进入阶段3。
注意： 使用YAML frontmatter来记录文档状态。

Phase 3: Tasks

阶段 3: 任务

Goal: Break the design into discrete, ordered implementation steps a developer can pick up one at a time.
Read 
./references/templates/tasks.md
before writing this file.
Write 
specs/<spec-name>/tasks.md
as a checkbox list. Each task should:
  • Be small enough to complete in one sitting
  • Reference the requirement(s) it satisfies (e.g., 
    [REQ-2]
    )
  • Be ordered so earlier tasks unblock later ones (foundations first)
Avoid vague tasks like "implement auth". Prefer "Add 
POST /auth/login
endpoint that validates credentials and returns a JWT 
[REQ-1.2]
".
Iterate: Share the list. Ask: "Does the order feel right? Anything too big or missing?" Revise until approved, when approved update the YAML frontmatter.
Note: Use the YAML frontmatter to track document status.
目标： 将设计拆分为离散、有序的实现步骤，开发人员可以按顺序逐个完成。
在编写该文件前请先阅读
./references/templates/tasks.md
。
编写
specs/<spec-name>/tasks.md
文件，内容为复选框列表。每个任务应当：
  • 体量足够小，可以在单次工作时段内完成
  • 关联其满足的需求（例如 
    [REQ-2]
    ）
  • 按顺序排列，前面的任务不会阻塞后续任务（基础任务优先）
避免使用模糊的任务描述，比如“实现认证”，优先使用类似“添加 
POST /auth/login
接口，用于验证凭证并返回JWT 
[REQ-1.2]
”这样的描述。
迭代： 分享任务列表，询问：“顺序是否合理？有没有任务体量过大或者遗漏的内容？” 持续修订直到获得批准，批准后更新YAML frontmatter。
注意： 使用YAML frontmatter来记录文档状态。

Re-entering the loop

重入工作流

The user may want to revisit an earlier phase — that's fine. If requirements change after the design is written, update 
requirements.md
first, then revise 
design.md
and 
tasks.md
for consistency. The three files should always agree.
If the user drops in mid-workflow (e.g., they already have a 
requirements.md
), read what exists, orient yourself, and pick up from the right phase.
用户可能想要回到之前的阶段——这是允许的。如果设计完成后需求发生了变更，先更新
requirements.md
，然后修订
design.md
和
tasks.md
以保持一致性。三个文件的内容必须始终保持一致。
如果用户在工作流中途加入（例如他们已经有了
requirements.md
文件），先阅读已有内容，明确当前进度，然后从对应的阶段继续推进。

References

参考资料

  • ./references/templates/requirements.md
    — requirements file template (read at Phase 1)
  • ./references/templates/design.md
    — design file template (read at Phase 2)
  • ./references/templates/tasks.md
    — tasks file template (read at Phase 3)
  • ./references/templates/requirements.md
    — 需求文件模板（阶段1时阅读）
  • ./references/templates/design.md
    — 设计文件模板（阶段2时阅读）
  • ./references/templates/tasks.md
    — 任务文件模板（阶段3时阅读）