spec-driven-development

Spec-Driven Development

概览

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

何时使用

• 开始一个新项目或功能
• 需求有歧义或不完整
• 变更触及多个文件或模块
• 你即将做出架构决策
• 任务实现需要超过 30 分钟

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

门控工作流

Spec-driven development 有四个阶段。当前阶段被验证之前，不要进入下一阶段。

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

阶段 1：Specify

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

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

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

不要默默补全含糊需求。spec 的全部目的，就是在代码写出来之前暴露误解；假设是最危险的一种误解。

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

1. Objective：我们在构建什么，为什么？用户是谁？成功是什么样子？

2. Commands：完整可执行命令，包含 flags，而不只是工具名。

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

3. Project Structure：源代码在哪里，测试放哪里，文档属于哪里。

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation
   

4. Code Style：一个真实代码片段展示风格，胜过三段描述。包含命名约定、格式规则和优秀输出示例。

5. Testing Strategy：使用什么框架、测试放在哪里、覆盖率期望、哪些关注点对应哪些测试层级。

6. Boundaries：三层系统：

   • Always do: 运行测试后再提交、遵循命名约定、验证输入
   • Ask first: 数据库 schema 变更、添加依赖、修改 CI 配置
   • Never do: 提交 secrets、编辑 vendor 目录、未经批准移除失败测试

Spec 模板：

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

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

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]