Back to Details

spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-Driven Development

规范驱动开发

Overview

概述

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
在编写任何代码之前，先撰写结构化的规范文档。该规范是你与工程师之间共享的事实依据——它定义了我们要构建的内容、构建原因以及验收标准。没有规范的代码开发无异于盲目猜测。

When to Use

适用场景

  • Starting a new project or feature
  • Requirements are ambiguous or incomplete
  • The change touches multiple files or modules
  • You're about to make an architectural decision
  • The task would take more than 30 minutes to implement
When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
  • 启动新项目或新功能
  • 需求模糊或不完整
  • 变更涉及多个文件或模块
  • 即将做出架构决策
  • 任务实施耗时超过30分钟
不适用场景： 单行代码修复、拼写错误修正，或需求明确且独立的变更。

The Gated Workflow

分阶段审批工作流

Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews
规范驱动开发分为四个阶段，当前阶段通过审核后才能进入下一阶段。
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
  人工审核    人工审核  人工审核    人工审核

Phase 1: Specify

阶段1：制定规范

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
Surface assumptions immediately. Before writing any spec content, list what you're assuming:
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.
Never silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.
Write a spec document covering these six core areas:
  1. Objective — What are we building and why? Who is the user? What does success look like?
  2. Commands — Full executable commands with flags, not just tool names.
    Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
  3. Project Structure — Where source code lives, where tests go, where docs belong.
    src/           → Application source code
src/components → React components
src/lib        → Shared utilities
tests/         → Unit and integration tests
e2e/           → End-to-end tests
docs/          → Documentation
  4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
  5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.
  6. Boundaries — Three-tier system:
    • Always do: Run tests before commits, follow naming conventions, validate inputs
    • Ask first: Database schema changes, adding dependencies, changing CI config
    • Never do: Commit secrets, edit vendor directories, remove failing tests without approval
Spec template:
markdown
undefined
从高层次的愿景开始。向相关人员提出澄清问题，直到需求具体化。
立即明确假设前提。 在撰写任何规范内容之前，列出你的假设：
我的假设前提：
1. 这是一个Web应用（而非原生移动应用）
2. 认证采用基于会话的Cookie（而非JWT）
3. 数据库为PostgreSQL（基于现有Prisma schema）
4. 我们仅针对现代浏览器（不支持IE11）
→ 若有错误请立即指出，否则我将基于这些假设推进。
绝不要默默填补模糊的需求。规范的核心目的就是在代码编写之前暴露误解——假设是最危险的误解形式。
撰写规范文档需涵盖以下六个核心领域：
  1. 目标 —— 我们要构建什么？为什么构建？用户是谁？成功的标准是什么？
  2. 命令 —— 完整的可执行命令及参数，而非仅工具名称。
    构建: npm run build
测试: npm test -- --coverage
代码检查: npm run lint --fix
开发: npm run dev
  3. 项目结构 —— 源代码、测试、文档的存放位置。
    src/           → 应用源代码
src/components → React组件
src/lib        → 共享工具库
tests/         → 单元测试与集成测试
e2e/           → 端到端测试
docs/          → 文档
  4. 代码风格 —— 一段真实的代码示例胜过三段描述性文字。包含命名规范、格式化规则及优秀输出示例。
  5. 测试策略 —— 使用的框架、测试存放位置、覆盖率要求、不同关注点对应的测试层级。
  6. 边界规则 —— 三级体系：
    • 必须执行： 提交前运行测试、遵循命名规范、验证输入
    • 需先确认： 数据库schema变更、添加依赖、修改CI配置
    • 禁止操作： 提交敏感信息、编辑 vendor 目录、未经批准移除失败测试
规范模板：
markdown
undefined

Spec: [Project/Feature Name]

规范：[项目/功能名称]

Objective

目标

[What we're building and why. User stories or acceptance criteria.]
[我们要构建的内容及原因。用户故事或验收标准。]

Tech Stack

技术栈

[Framework, language, key dependencies with versions]
[框架、语言、关键依赖及版本]

Commands

命令

[Build, test, lint, dev — full commands]
[构建、测试、代码检查、开发——完整命令]

Project Structure

项目结构

[Directory layout with descriptions]
[目录布局及说明]

Code Style

代码风格

[Example snippet + key conventions]
[示例代码片段 + 核心规范]

Testing Strategy

测试策略

[Framework, test locations, coverage requirements, test levels]
[框架、测试位置、覆盖率要求、测试层级]

Boundaries

边界规则

  • Always: [...]
  • Ask first: [...]
  • Never: [...]
  • 必须：[...]
  • 需先确认：[...]
  • 禁止：[...]

Success Criteria

成功标准

[How we'll know this is done — specific, testable conditions]
[如何判断任务完成——具体、可测试的条件]

Open Questions

待解决问题

[Anything unresolved that needs human input]

**Reframe instructions as success criteria.** When receiving vague requirements, translate them into concrete conditions:
REQUIREMENT: "Make the dashboard faster"
REFRAMED SUCCESS CRITERIA:
  • Dashboard LCP < 2.5s on 4G connection
  • Initial data load completes in < 500ms
  • No layout shift during load (CLS < 0.1) → Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
[所有需要人工输入的未决事项]

**将模糊需求转化为成功标准。** 收到模糊需求时，将其转换为具体条件：
需求："让仪表盘更快"
转化后的成功标准：
  • 4G网络下仪表盘LCP < 2.5s
  • 初始数据加载时间 < 500ms
  • 加载过程无布局偏移（CLS < 0.1） → 这些目标是否合适？

这样你就能朝着明确的目标迭代、重试和解决问题，而非猜测“更快”的具体含义。

Phase 2: Plan

阶段2：制定计划

With the validated spec, generate a technical implementation plan:
  1. Identify the major components and their dependencies
  2. Determine the implementation order (what must be built first)
  3. Note risks and mitigation strategies
  4. Identify what can be built in parallel vs. what must be sequential
  5. Define verification checkpoints between phases
The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."
基于已通过审核的规范，生成技术实施计划：
  1. 识别主要组件及其依赖关系
  2. 确定实施顺序（哪些必须优先构建）
  3. 记录风险及缓解策略
  4. 识别可并行构建与需串行构建的任务
  5. 定义各阶段之间的验证检查点
计划需具备可审核性：相关人员阅读后应能判断“这是正确的方案”或“不，需要修改X部分”。

Phase 3: Tasks

阶段3：拆分任务

Break the plan into discrete, implementable tasks:
  • Each task should be completable in a single focused session
  • Each task has explicit acceptance criteria
  • Each task includes a verification step (test, build, manual check)
  • Tasks are ordered by dependency, not by perceived importance
  • No task should require changing more than ~5 files
Task template:
markdown
- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]
将计划拆分为独立的、可执行的任务：
  • 每个任务应能在一个专注的工作时段内完成
  • 每个任务有明确的验收标准
  • 每个任务包含验证步骤（测试、构建、人工检查）
  • 任务按依赖关系排序，而非按主观重要性
  • 单个任务修改的文件不应超过约5个
任务模板：
markdown
- [ ] 任务：[描述]
  - 验收标准：[完成时需满足的条件]
  - 验证方式：[确认方法——测试命令、构建、人工检查]
  - 涉及文件：[将修改的文件]

Phase 4: Implement

阶段4：实施

Execute tasks one at a time following 
incremental-implementation
and 
test-driven-development
skills.
遵循
incremental-implementation
（增量实施）和
test-driven-development
（测试驱动开发）原则，逐个执行任务。

Keeping the Spec Alive

规范的持续维护

The spec is a living document, not a one-time artifact:
  • Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
  • Update when scope changes — Features added or cut should be reflected in the spec.
  • Commit the spec — The spec belongs in version control alongside the code.
  • Reference the spec in PRs — Link back to the spec section that each PR implements.
规范是一份活文档，而非一次性产物：
  • 决策变更时更新 —— 若发现数据模型需要变更，先更新规范再实施。
  • 范围变更时更新 —— 新增或移除的功能应在规范中体现。
  • 提交规范至版本控制 —— 规范应与代码一同存入版本控制系统。
  • PR中引用规范 —— 每个PR需链接到其实现的规范章节。

Common Rationalizations

常见误区及真相

RationalizationReality
"This is simple, I don't need a spec"Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it"That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down"A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway"That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want"Even clear requests have implicit assumptions. The spec surfaces those assumptions.
误区真相
"这个任务很简单，不需要规范"简单任务不需要长篇规范，但仍需验收标准。两行规范即可。
"我先写代码再补规范"那是文档记录，而非规范制定。规范的价值在于在代码编写之前强制明确需求。
"写规范会拖慢进度"15分钟的规范能避免数小时的返工。15分钟的前置规划胜过15小时的调试。
"反正需求总会变"这正是规范作为活文档的原因。过时的规范仍胜于无规范。
"用户知道自己想要什么"即使是明确的需求也存在隐含假设。规范的作用就是暴露这些假设。

Red Flags

警示信号

  • Starting to write code without any written requirements
  • Asking "should I just start building?" before clarifying what "done" means
  • Implementing features not mentioned in any spec or task list
  • Making architectural decisions without documenting them
  • Skipping the spec because "it's obvious what to build"
  • 未写下任何需求就开始编写代码
  • 未明确“完成”的定义就问“我可以开始构建了吗？”
  • 实施规范或任务列表中未提及的功能
  • 未记录就做出架构决策
  • 以“显然知道要构建什么”为由跳过规范制定

Verification

验证检查

Before proceeding to implementation, confirm:
  • The spec covers all six core areas
  • The human has reviewed and approved the spec
  • Success criteria are specific and testable
  • Boundaries (Always/Ask First/Never) are defined
  • The spec is saved to a file in the repository
进入实施阶段前，确认：
  • 规范涵盖所有六个核心领域
  • 相关人员已审核并批准规范
  • 成功标准具体且可测试
  • 已定义边界规则（必须/需先确认/禁止）
  • 规范已保存至仓库中的文件