spec-driven-development

规范驱动开发

概述

在编写任何代码之前，先写一份结构化规范。这份规范是你与人工工程师之间共享的事实来源，它定义了我们要构建什么、为什么构建，以及如何判断任务已完成。没有规范的代码就是在猜测。

适用场景

• 启动新项目或开发新功能
• 需求含糊或不完整
• 变更涉及多个文件或模块
• 即将做出架构决策
• 实现任务需要超过 30 分钟

不适用场景： 单行修复、拼写更正，或需求明确且独立的变更。

分阶段门控工作流

规范驱动开发分为四个阶段，前面还有一个范围检查（阶段 0）；仅当一项请求包含多个可独立测试的功能时，才启用该阶段。当前阶段通过验证之前，不要进入下一阶段。

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

阶段 0：范围检查

大多数请求只描述一项功能。如果当前请求也是如此，请跳过此阶段，直接进入规范阶段——阶段 0 只用于例外情况，并不对单项功能划分层级。

识别。 如果一项需求包含多个可独立测试的功能，请先拆解再编写规范：

• 需求列出了各自具有使用者或数据的不同功能（例如身份、账单、通知、报告）
• 验收标准分成几组，每组都可以单独交付和验证
• 移除或替换一项功能，不会导致其他功能的需求需要重写

编写任何规范之前，先提出功能映射。 映射应简洁且便于审查，由模块表和构建顺序组成，而不是项目计划：

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting

• 稳定的模块 ID。 使用 kebab-case，一经选定便不再更改；在整个计划期间都保持不变。规范、计划和后续命令都通过这些 ID 选择工作，而不是猜测当前生效的是哪份规范。
• 依赖方向，不设循环。 箭头只能指向一个方向。如果两个模块相互依赖，它们就属于同一个模块。
• 接口位于边界处。 映射会记录 billing 依赖于 identity；它们之间的契约应写在提供方模块的规范中（接口设计方法请参见 api-and-interface-design）。

映射与每个阶段一样需要通过审查。 在编写任何模块规范之前，人工审查者应先审核模块边界、依赖方向和构建顺序。映射出错代价高昂，审查十行内容却不然。

然后按模块递归执行。 按依赖顺序，为每个模块运行 Specify → Plan → Tasks → Implement。每个模块都有自己的规范，范围限定为该模块的目标、边界和成功标准。将获批的映射保存在项目根目录下，并将每个模块的规范与映射一同保存，文件名使用模块 ID（SPEC-identity.md、SPEC-billing.md）——已有内容的索引是映射，而不是通过猜测文件名来查找。

阶段 1：明确需求

从高层愿景着手。通过提问向人类确认需求，直到需求具体明确。

立即说明假设。 在撰写任何规格说明内容之前，列出你的假设：

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.

不要默默补全含糊的需求。规格说明的全部目的，就是在编写代码之前暴露误解——假设是最危险的误解形式。

编写一份涵盖以下六个核心领域的规格说明文档：

1. 目标 — 我们要构建什么，为什么要构建？用户是谁？成功是什么样的？

2. 命令 — 提供完整的可执行命令及其标志，而不只是工具名称。

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev
   

3. 项目结构 — 源代码放在哪里，测试放在哪里，文档放在哪里。

   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. 代码风格 — 一个真实的代码片段胜过三段对代码风格的描述。请包含命名约定、格式规则和优秀输出示例。

5. 测试策略 — 使用什么框架，测试放在哪里，覆盖率要求是什么，哪些测试级别适用于哪些关注点。

6. 边界 — 三层体系：

   • 始终执行： 提交前运行测试、遵循命名约定、验证输入
   • 先询问： 更改数据库架构、添加依赖项、更改 CI 配置
   • 绝不执行： 提交机密信息、编辑供应商目录、未经批准删除失败的测试

规格说明模板：

# 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]

外部规格说明工具： 此工作流与格式无关。如果项目已使用 OpenSpec 或其他规格说明系统，请保留该系统的产物格式和存储约定，而不是另行创建重复的 SPEC.md。此技能负责澄清需求、编写内容和设置审批关卡；外部工具负责确定已批准规格说明的呈现方式。

将指示改写为成功标准。 收到含糊的需求时，将其转化为具体条件：

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?

这样，你就能围绕明确目标反复尝试、重试并解决问题，而不是猜测“更快”是什么意思。

写完规格说明后立即停止（重要）。 保存规格说明后：

1. 概述规格说明并列出所有待解决问题。
2. 请人类批准，或提出修改要求。
3. 立即停止本轮操作。 不要开始阶段 2、调用 planning-and-task-breakdown，也不要在本轮编写代码。只有在人类在后续轮次批准规格说明后，才能开始规划。

阶段 2：规划

根据已验证的规格说明，生成技术实现计划：

1. 确定主要组件及其依赖关系
2. 确定实现顺序（必须先构建哪些内容）
3. 记录风险和缓解策略
4. 确定哪些工作可以并行开展，哪些必须按顺序进行
5. 定义各阶段之间的验证检查点

请遵循 planning-and-task-breakdown 中关于依赖关系图映射和垂直切片机制的说明；该说明是权威来源。以上要点只是简要概述；若有任何不一致，以 planning-and-task-breakdown 为准。

输出约定： 将计划保存到 tasks/plan.md，并将任务列表记录在 planning-and-task-breakdown 定义的任务列表目标位置（默认为 tasks/todo.md；项目也可以指定外部跟踪工具）。如果 tasks/ 不存在，则创建它。后续命令（/build 等）会使用这些默认位置。

计划应便于审阅：人类应能阅读并回答“是的，这种方法合适”，或“不，请修改 X”。

阶段 3：任务

将计划拆分为离散、可实施的任务：

• 每项任务都应能在一次专注的工作时段内完成
• 每项任务都有明确的验收标准
• 每项任务都包含验证步骤（测试、构建或手动检查）
• 任务按依赖关系排序，而非按主观重要性排序
• 每项任务涉及的文件不应超过约 5 个

完整的任务规模划分和依赖排序方法请参阅 planning-and-task-breakdown；它是权威来源。下面的模板是轻量级的内联形式；如果两者有任何差异，以 planning-and-task-breakdown 为准。

任务模板：

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

阶段 4：实施

按照 skills/incremental-implementation/SKILL.md（incremental-implementation）和 skills/test-driven-development/SKILL.md（test-driven-development）逐项执行任务。使用 skills/context-engineering/SKILL.md（context-engineering）在每个步骤加载正确的规范章节和源文件，而不是将整份规范全部提供给 Agent。

让规范保持鲜活

规范是一份持续更新的文档，而非一次性产物：

• 决策变更时更新 — 如果发现数据模型需要变更，先更新规范，再实施。
• 范围变更时更新 — 新增或删减的功能都应体现在规范中。
• 提交规范 — 规范应与代码一同纳入版本控制。
• 在 PR 中引用规范 — 链接到每个 PR 所实现的规范章节。

常见的自我开脱

自我开脱	实际情况
“这很简单，不需要规范”	简单任务不需要冗长的规范，但仍需要验收标准。两行规范也可以。
“我写完代码再补规范”	那是文档，不是规范。规范的价值在于促使你在编写代码之前明确需求。
“规范会拖慢进度”	15 分钟写规范，可以避免数小时返工。花 15 分钟走瀑布流程，胜过花 15 小时调试。
“需求反正还会变”	因此规范才需要持续更新。过时的规范仍胜过没有规范。
“用户知道自己想要什么”	即使请求很明确，也包含隐含假设。规范能揭示这些假设。
“这是一个大功能，拆分它只会增加额外工作”	如果验收标准可归为可独立测试的组，那么单体规范会迫使所有后续任务都考虑整份约定。十行的能力映射就是成本低廉的替代方案。
“我会在规划时拆解”	规划是在规范内切分任务。到那时，过大的产物已经存在——模块边界和依赖方向必须在编写规范之前确定，而不是之后。

危险信号

• 没有任何书面需求就开始编写代码
• 在明确“完成”的定义之前就问“我是不是该直接开始构建？”
• 实施任何规范或任务清单中都未提及的功能
• 做出架构决策却不记录
• 因为“要构建什么显而易见”而跳过规范
• 在同一轮中编写规范并开始规划或编写代码
• 一份规范的需求横跨多个可独立测试的能力
• 因为事先没有批准能力映射，而在实施过程中隐式决定模块边界或构建顺序

验证

开始实施之前，请确认：

• 规范涵盖全部六个核心领域
• 人类已审阅并批准规范
• 保存规范后本轮已结束；批准是在后续轮次中获得的
• 成功标准具体且可测试
• 已定义边界（始终允许／需先询问／绝不允许）
• 规范已保存到仓库中的文件
• 如果请求包含多个可独立测试的能力，则必须在编写任何模块规范之前批准能力映射（模块 ID、依赖方向、构建顺序）
• 每份模块规范都能追溯到已批准映射中的模块 ID