wehub-skill-sync
7.4 KiB
name, description
| name | description |
|---|---|
| spec-driven-development | 在编码前先创建规格说明。适用于启动新项目、新功能或重大变更且尚无规格说明的场景。适用于需求不明确、含糊不清或仅为一个模糊构思的情况。 |
规格驱动开发
概述
在编写任何代码之前，先撰写一份结构化的规格说明。规格说明是你与人类工程师之间共享的事实源头——它定义了我们正在构建什么、为什么构建以及如何判断完成。没有规格说明的代码就是瞎猜。
何时使用
- 启动新项目或新功能
- 需求含糊不清或不完整
- 变更涉及多个文件或模块
- 你即将做出架构决策
- 任务实施时间超过 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 配置
- 绝不执行： 提交密钥、编辑供应商目录、未经批准删除失败的测试
规格模板：
# 规格：[项目/功能名称]
## 目标
[我们要构建什么以及为什么。用户故事或验收标准。]
## 技术栈
[框架、语言、关键依赖项及版本]
## 命令
[构建、测试、代码检查、开发——完整命令]
## 项目结构
[目录布局及描述]
## 代码风格
[示例代码片段 + 关键约定]
## 测试策略
[框架、测试位置、覆盖率要求、测试层级]
## 边界
- 始终执行：[...]
- 先询问：[...]
- 绝不执行：[...]
## 成功标准
[如何判断完成——具体、可测试的条件]
## 未决问题
[任何需要人工输入的未解决事项]
将指令重新表述为成功标准。 当收到模糊需求时，将其转化为具体条件：
需求："让仪表盘更快"
重新表述的成功标准：
- 在 4G 网络下，仪表盘 LCP < 2.5 秒
- 初始数据加载在 500 毫秒内完成
- 加载过程中无布局偏移（CLS < 0.1）
→ 这些是合适的目标吗？
这样你就可以朝着明确的目标进行循环、重试和问题解决，而不是猜测"更快"是什么意思。
阶段 2：计划
有了经过验证的规格说明，生成技术实施方案：
- 识别主要组件及其依赖关系
- 确定实施顺序（必须先构建什么）
- 记录风险及应对策略
- 识别哪些可以并行构建，哪些必须顺序进行
- 在阶段之间定义验证检查点
计划应可供审核：人类应能阅读后说"是的，这是正确的方法"或"不，请修改 X"。
阶段 3：任务
将计划拆分为离散的、可实施的任务：
- 每个任务应能在一次专注的会话中完成
- 每个任务有明确的验收标准
- 每个任务包含一个验证步骤（测试、构建、手动检查）
- 任务按依赖关系排序，而非按感知重要性排序
- 每个任务涉及的更改文件不应超过约 5 个
任务模板：
- [ ] 任务：[描述]
- 验收标准：[完成时必须满足的条件]
- 验证方式：[如何确认——测试命令、构建、手动检查]
- 涉及文件：[将被更改的文件]
阶段 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 小时的调试。 |
| "需求反正会变" | 正因为如此，规格说明才是一份持续更新的文档。过时的规格说明仍然比没有规格说明要好。 |
| "用户知道他们想要什么" | 即使明确的需求也包含隐含假设。规格说明正是为了暴露这些假设。 |
警示信号
- 在没有书面需求的情况下开始编写代码
- 在明确"完成"是什么意思之前就问"我是不是可以直接开始构建？"
- 实现任何规格说明或任务列表中都未提及的功能
- 做出架构决策但不记录
- 因为"要构建什么很明显"而跳过规格说明
验证
在进入实施之前，请确认：
- 规格说明涵盖了全部六个核心领域
- 人类已审核并批准了规格说明
- 成功标准是具体且可测试的
- 边界（始终执行/先询问/绝不执行）已定义
- 规格说明已保存到仓库中的文件中