spec-driven-development

规格驱动开发

概览

在写任何代码之前，先写一份结构化的规格说明。Spec 是你和人类工程师之间共享的事实来源，它定义了我们要构建什么、为什么构建，以及如何判断它已经完成。没有 spec 的代码，本质上是在猜。

何时使用

• 开始一个新项目或新功能
• 需求有歧义或不完整
• 改动会涉及多个文件或模块
• 你将要做架构决策
• 任务实现预计会超过 30 分钟

不适用的场景： 单行修复、拼写修正，或需求已经非常明确且范围自洽的小改动。

分阶段工作流

Spec-driven development 分为四个阶段。当前阶段没有通过验证前，不要进入下一个阶段。

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

阶段 1：明确规格（Specify）

从高层愿景开始。持续向人类提出澄清问题，直到需求足够具体。

立刻暴露假设。 在写任何 spec 内容之前，先列出你当前的假设：

我当前的假设：
1. 这是一个 Web 应用，不是原生移动端
2. 认证使用基于 session 的 cookie，而不是 JWT
3. 数据库是 PostgreSQL（基于现有 Prisma schema 推断）
4. 目标仅为现代浏览器，不考虑 IE11
→ 如果不对请现在纠正，否则我会按这些继续。

不要悄悄补齐有歧义的需求。Spec 的全部价值，就是在代码写下去之前先暴露误解，而假设正是最危险的误解形式。

写一份覆盖以下六个核心区域的 spec 文档：

1. Objective：我们要做什么，为什么做？用户是谁？成功的标准是什么？

2. Commands：给出完整可执行命令和参数，而不是只写工具名。

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

3. Project Structure：源码在哪里、测试在哪里、文档放哪里。

   src/           → 应用源码
   src/components → React 组件
   src/lib        → 共享工具
   tests/         → 单元与集成测试
   e2e/           → 端到端测试
   docs/          → 文档
   

4. Code Style：一个真实代码片段，比三段文字描述更有用。包括命名约定、格式规则，以及好的输出示例。

5. Testing Strategy：使用什么框架，测试放在哪里，覆盖率预期如何，不同关注点分别用哪一层测试。

6. Boundaries：三层边界系统：

   • Always do： 提交前跑测试、遵循命名规范、做输入校验
   • Ask first： 改数据库 schema、加依赖、改 CI 配置
   • Never do： 提交 secrets、编辑 vendor 目录、未经批准删除失败测试

Spec 模板：

# Spec: [项目/功能名称]

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

## Tech Stack
[框架、语言、带版本的关键依赖]

## Commands
[Build、test、lint、dev 的完整命令]

## Project Structure
[目录结构及说明]

## Code Style
[示例片段 + 关键约定]

## Testing Strategy
[框架、测试位置、覆盖要求、测试层级]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[如何判断完成，必须是具体且可测试的条件]

## Open Questions
[任何仍需人类确认的未决问题]

把模糊指令改写成成功标准。 当接收到模糊需求时，把它翻译成明确条件：

原始需求："让 dashboard 更快"

改写后的成功标准：
- Dashboard 的 LCP 在 4G 网络下 < 2.5s
- 初始数据加载在 < 500ms 内完成
- 加载期间没有布局偏移（CLS < 0.1）
→ 这些目标对吗？