在编码前创建规范。适用于启动新项目、新功能或重大变更且尚无规范时。适用于需求不清晰、模糊或仅存在于模糊想法时。
规范驱动开发
概述
在编写任何代码之前，先编写一份结构化的规范。规范是你与人类工程师之间的共享真相源——它定义了我们要构建什么、为什么构建以及如何知道完成。没有规范的代码就是猜测。
何时使用
- 启动新项目或新功能
- 需求模糊或不完整
- 变更涉及多个文件或模块
- 即将做出架构决策
- 任务实施时间超过30分钟
何时不使用： 单行修复、拼写纠正或需求明确且自包含的变更。
门控工作流
规范驱动开发包含四个阶段。在当前阶段验证通过之前，不要进入下一阶段。
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
│ │ │ │
▼ ▼ ▼ ▼
人类 人类 人类 人类
审查 审查 审查 审查
阶段1：规范
从高层愿景开始。向人类提出澄清性问题，直到需求具体化。
立即表面化假设。 在编写任何规范内容之前，列出你的假设：
我做出的假设：
1. 这是一个Web应用（不是原生移动端）
2. 认证使用基于会话的Cookie（不是JWT）
3. 数据库是PostgreSQL（基于现有Prisma模式）
4. 我们只针对现代浏览器（不支持IE11）
→ 现在纠正我，否则我将按此继续。
不要默默填补模糊的需求。规范的整个目的是在代码编写之前表面化误解——假设是最危险的误解形式。
编写涵盖以下六个核心领域的规范文档：
-
目标 — 我们要构建什么以及为什么？用户是谁？成功是什么样的？
-
命令 — 完整的可执行命令及其标志，而不仅仅是工具名称。
构建：npm run build 测试：npm test -- --coverage 检查：npm run lint --fix 开发：npm run dev -
项目结构 — 源代码位置、测试位置、文档位置。
src/ → 应用程序源代码 src/components → React组件 src/lib → 共享工具 tests/ → 单元测试和集成测试 e2e/ → 端到端测试 docs/ → 文档 -
代码风格 — 一个真实的代码片段胜过三段描述。包括命名约定、格式化规则和良好输出的示例。
-
测试策略 — 使用什么框架、测试位置、覆盖率期望、不同关注点使用哪些测试级别。
-
边界 — 三级系统：
- 始终做： 提交前运行测试、遵循命名约定、验证输入
- 先询问： 数据库模式变更、添加依赖、更改CI配置
- 绝不做： 提交密钥、编辑供应商目录、未经批准删除失败的测试
规范模板：
# 规范：[项目/功能名称]
## 目标
[我们要构建什么以及为什么。用户故事或验收标准。]
## 技术栈
[框架、语言、关键依赖及其版本]
## 命令
[构建、测试、检查、开发——完整命令]
## 项目结构
[目录布局及描述]
## 代码风格
[示例片段 + 关键约定]
## 测试策略
[框架、测试位置、覆盖率要求、测试级别]
## 边界
- 始终：[...]
- 先询问：[...]
- 绝不做：[...]
## 成功标准
[如何知道完成——具体、可测试的条件]
## 未决问题
[任何需要人类输入的未解决问题]
将指令重构为成功标准。 当收到模糊需求时，将其转化为具体条件：
需求：“让仪表盘更快”
重构后的成功标准：
- 仪表盘LCP在4G连接下小于2.5秒
- 初始数据加载在500毫秒内完成
- 加载期间无布局偏移（CLS < 0.1）
→ 这些是正确目标吗？
这让你能够循环、重试并朝着明确目标解决问题，而不是猜测“更快”的含义。
阶段2：计划
根据验证通过的规范，生成技术实施计划：
- 识别主要组件及其依赖关系
- 确定实施顺序（必须先构建什么）
- 记录风险及缓解策略
- 识别哪些可以并行构建，哪些必须串行
- 在阶段之间定义验证检查点
遵循
planning-and-task-breakdown了解这些步骤背后的依赖图映射和垂直切片机制；它是权威来源。上面的要点是轻量级摘要；如果两者不一致，以planning-and-task-breakdown为准。输出约定： 将计划保存到
tasks/plan.md，任务列表保存到tasks/todo.md，遵循/plan命令约定。如果tasks/不存在则创建。下游命令（/build等）期望这些路径。
计划应可审查：人类应能阅读并说“是的，这是正确的方法”或“不，改变X”。
阶段3：任务
将计划分解为离散的、可实施的任务：
- 每个任务应能在一次专注的会话中完成
- 每个任务有明确的验收标准
- 每个任务包含验证步骤（测试、构建、手动检查）
- 任务按依赖关系排序，而非按感知重要性
- 每个任务不应涉及超过约5个文件的更改
遵循
planning-and-task-breakdown了解完整的任务大小确定和依赖排序机制；它是权威来源。下面的模板是轻量级内联形式；如果两者不一致，以planning-and-task-breakdown为准。
任务模板：
- [ ] 任务：[描述]
- 验收：[完成时必须满足的条件]
- 验证：[如何确认——测试命令、构建、手动检查]
- 文件：[将涉及哪些文件]
阶段4：实施
一次执行一个任务，遵循 skills/incremental-implementation/SKILL.md（incremental-implementation）和 skills/test-driven-development/SKILL.md（test-driven-development）。使用 skills/context-engineering/SKILL.md（context-engineering）在每一步加载正确的规范章节和源文件，而不是用整个规范淹没代理。
保持规范活跃
规范是活文档，而非一次性产物：
- 当决策变更时更新 — 如果发现数据模型需要更改，先更新规范，再实施。
- 当范围变更时更新 — 添加或削减的功能应在规范中反映。
- 提交规范 — 规范应与代码一起纳入版本控制。
- 在PR中引用规范 — 链接回每个PR实现的规范章节。
常见合理化理由
| 合理化理由 | 现实 |
|---|---|
| “这很简单，我不需要规范” | 简单任务不需要长规范，但仍需要验收标准。两行规范就足够了。 |
| “我会在编码后写规范” | 那是文档，不是规范。规范的价值在于在编码前强制清晰。 |
| “规范会拖慢我们” | 15分钟的规范可以防止数小时的重做。15分钟的瀑布式胜过15小时的调试。 |
| “需求无论如何都会变” | 这就是为什么规范是活文档。过时的规范仍然比没有规范好。 |
| “用户知道他们想要什么” | 即使明确的需求也有隐含假设。规范表面化这些假设。 |
红旗
- 在没有任何书面需求的情况下开始编写代码
- 在澄清“完成”的含义之前问“我应该直接开始构建吗？”
- 实施任何规范或任务列表中未提及的功能
- 做出架构决策而不记录
- 因为“构建什么很明显”而跳过规范
验证
在进入实施之前，确认：
- [ ] 规范涵盖所有六个核心领域
- [ ] 人类已审查并批准规范
- [ ] 成功标准具体且可测试
- [ ] 边界（始终/先询问/绝不做）已定义
- [ ] 规范已保存到仓库中的文件
