chore: import zh skill spec-driven-development
This commit is contained in:
wehub-skill-sync
@@ -0,0 +1,9 @@
|
||||
# WeHub 来源说明
|
||||
|
||||
- Skill 名称：`spec-driven-development`
|
||||
- 中文类目：产品需求与规约文档
|
||||
- 上游仓库：`addyosmani__agent-skills`
|
||||
- 上游路径：`skills/spec-driven-development/SKILL.md`
|
||||
- 上游链接：https://github.com/addyosmani/agent-skills/blob/HEAD/skills/spec-driven-development/SKILL.md
|
||||
- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
|
||||
- 原作者、版权和许可证信息以上游仓库为准
|
||||
@@ -0,0 +1,199 @@
|
||||
---
|
||||
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 小时的调试。 |
|
||||
| "需求反正会变" | 正因为如此，规格说明才是一份持续更新的文档。过时的规格说明仍然比没有规格说明要好。 |
|
||||
| "用户知道他们想要什么" | 即使明确的需求也包含隐含假设。规格说明正是为了暴露这些假设。 |
|
||||
|
||||
## 警示信号
|
||||
|
||||
- 在没有书面需求的情况下开始编写代码
|
||||
- 在明确"完成"是什么意思之前就问"我是不是可以直接开始构建？"
|
||||
- 实现任何规格说明或任务列表中都未提及的功能
|
||||
- 做出架构决策但不记录
|
||||
- 因为"要构建什么很明显"而跳过规格说明
|
||||
|
||||
## 验证
|
||||
|
||||
在进入实施之前，请确认：
|
||||
|
||||
- [ ] 规格说明涵盖了全部六个核心领域
|
||||
- [ ] 人类已审核并批准了规格说明
|
||||
- [ ] 成功标准是具体且可测试的
|
||||
- [ ] 边界（始终执行/先询问/绝不执行）已定义
|
||||
- [ ] 规格说明已保存到仓库中的文件中
|
||||
Reference in New Issue
Block a user