---
name: spec-driven-development
description: 在编码前先创建规格说明。适用于启动新项目、新功能或重大变更且尚无规格说明的场景。适用于需求不明确、含糊不清或仅为一个模糊构思的情况。
---

# 规格驱动开发

## 概述

在编写任何代码之前，先撰写一份结构化的规格说明。规格说明是你与人类工程师之间共享的事实源头——它定义了我们正在构建什么、为什么构建以及如何判断完成。没有规格说明的代码就是瞎猜。

## 何时使用

- 启动新项目或新功能
- 需求含糊不清或不完整
- 变更涉及多个文件或模块
- 你即将做出架构决策
- 任务实施时间超过 30 分钟

**何时不使用：** 单行修复、拼写更正，或需求明确且自包含的变更。

## 门控工作流

规格驱动开发分为四个阶段。在当前阶段未经验证之前，不得进入下一阶段。

```
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 人工审核    人工审核   人工审核   人工审核
```

### 阶段 1：规格定义

从高层愿景开始。向人类提出澄清性问题，直到需求变得具体。

**立即暴露假设。** 在撰写任何规格内容之前，列出你所做的假设：

```
我正在做的假设：
1. 这是一个 Web 应用（不是原生移动端）
2. 认证使用基于会话的 Cookie（不是 JWT）
3. 数据库是 PostgreSQL（基于现有的 Prisma 模式）
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. **边界**——三层体系：
   - **始终执行：** 提交前运行测试、遵循命名约定、验证输入
   - **先询问：** 数据库模式变更、添加依赖项、更改 CI 配置
   - **绝不执行：** 提交密钥、编辑供应商目录、未经批准删除失败的测试

**规格模板：**

```markdown
# 规格：[项目/功能名称]

## 目标
[我们要构建什么以及为什么。用户故事或验收标准。]

## 技术栈
[框架、语言、关键依赖项及版本]

## 命令
[构建、测试、代码检查、开发——完整命令]

## 项目结构
[目录布局及描述]

## 代码风格
[示例代码片段 + 关键约定]

## 测试策略
[框架、测试位置、覆盖率要求、测试层级]

## 边界
- 始终执行：[...]
- 先询问：[...]
- 绝不执行：[...]

## 成功标准
[如何判断完成——具体、可测试的条件]

## 未决问题
[任何需要人工输入的未解决事项]
```

**将指令重新表述为成功标准。** 当收到模糊需求时，将其转化为具体条件：

```
需求："让仪表盘更快"

重新表述的成功标准：
- 在 4G 网络下，仪表盘 LCP < 2.5 秒
- 初始数据加载在 500 毫秒内完成
- 加载过程中无布局偏移（CLS < 0.1）
→ 这些是合适的目标吗？
```

这样你就可以朝着明确的目标进行循环、重试和问题解决，而不是猜测"更快"是什么意思。

### 阶段 2：计划

有了经过验证的规格说明，生成技术实施方案：

1. 识别主要组件及其依赖关系
2. 确定实施顺序（必须先构建什么）
3. 记录风险及应对策略
4. 识别哪些可以并行构建，哪些必须顺序进行
5. 在阶段之间定义验证检查点

计划应可供审核：人类应能阅读后说"是的，这是正确的方法"或"不，请修改 X"。

### 阶段 3：任务

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

- 每个任务应能在一次专注的会话中完成
- 每个任务有明确的验收标准
- 每个任务包含一个验证步骤（测试、构建、手动检查）
- 任务按依赖关系排序，而非按感知重要性排序
- 每个任务涉及的更改文件不应超过约 5 个

**任务模板：**
```markdown
- [ ] 任务：[描述]
  - 验收标准：[完成时必须满足的条件]
  - 验证方式：[如何确认——测试命令、构建、手动检查]
  - 涉及文件：[将被更改的文件]
```

### 阶段 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 小时的调试。 |
| "需求反正会变" | 正因为如此，规格说明才是一份持续更新的文档。过时的规格说明仍然比没有规格说明要好。 |
| "用户知道他们想要什么" | 即使明确的需求也包含隐含假设。规格说明正是为了暴露这些假设。 |

## 警示信号

- 在没有书面需求的情况下开始编写代码
- 在明确"完成"是什么意思之前就问"我是不是可以直接开始构建？"
- 实现任何规格说明或任务列表中都未提及的功能
- 做出架构决策但不记录
- 因为"要构建什么很明显"而跳过规格说明

## 验证

在进入实施之前，请确认：

- [ ] 规格说明涵盖了全部六个核心领域
- [ ] 人类已审核并批准了规格说明
- [ ] 成功标准是具体且可测试的
- [ ] 边界（始终执行/先询问/绝不执行）已定义
- [ ] 规格说明已保存到仓库中的文件中