Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

spec-driven-development

编码前先创建 spec。用于开始新项目、功能或重大变更且还没有规格说明时。用于撰写带目标和范围的 PRD 或需求文档时,或需求不清晰、有歧义、只是一段模糊想法时。用于单个需求横跨多个可独立测试的能力、需要先拆解成模块能力地图再做规格说明时。

vinvcn · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add vinvcn/addyosmani-agent-skills-zh --skill spec-driven-development

About this skill


name: spec-driven-development description: 编码前先创建 spec。用于开始新项目、功能或重大变更且还没有规格说明时。用于撰写带目标和范围的 PRD 或需求文档时,或需求不清晰、有歧义、只是一段模糊想法时。用于单个需求横跨多个可独立测试的能力、需要先拆解成模块能力地图再做规格说明时。

Spec-Driven Development

概览

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

何时使用

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

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

门控工作流

Spec-driven development 有四个阶段,前面还有一个范围检查(阶段 0),它只在一个请求打包了多个可独立测试的能力时才会激活。当前阶段被验证之前,不要进入下一阶段。

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

阶段 0:范围检查(Scope Check)

大多数请求只描述一个能力。如果当前的请求也是如此,跳过这个阶段,直接进入 Specify。阶段 0 是为例外情况存在的,不是常规;它不会给单能力功能强加层级结构。

检测。 当一个需求打包了多个可独立测试的能力时,先分解再做规格说明:

  • 需求点名了多个各有自己的消费者或数据的独立能力(例如 identity、billing、notifications、reporting)
  • 验收标准聚成可以分别交付和验证的组
  • 砍掉或替换某一个能力,不需要重写其他能力的要求

在写任何 spec 之前,先提出一份能力地图(capability map)。 要小、可评审:一张模块表加一个构建顺序,不是项目计划:

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting
  • 稳定的模块 id。 kebab-case,一次选定,initiative 进行中绝不重命名。Specs、计划和下游命令都通过这些 id 来选择工作,而不是猜测当前哪个 spec 生效。
  • 依赖有方向,无环。 箭头只指向一个方向。如果两个模块互相依赖,它们其实是一个模块。
  • 接口位于边界上。 地图记录 billing 依赖 identity;两者之间的契约属于提供方模块的 spec(设计方法见 api-and-interface-design)。

地图和其他阶段一样有门禁。 在写任何模块 spec 之前,由人类评审模块边界、依赖方向和构建顺序。地图搞错的代价很高;评审十行则不然。

然后按模块递归。 依依赖顺序为每个模块执行 Specify → Plan → Tasks → Implement。每个模块都有自己的 spec,范围限定在该模块的目标、边界和成功标准。把批准后的地图保存在项目根目录,各模块的 spec 与之放在一起,按模块 id 命名(SPEC-identity.md、SPEC-billing.md)。存在的索引是这张地图,而不是靠猜文件名。

阶段 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]

外部 spec 工具: 这个工作流与格式无关。如果项目已经使用 OpenSpec 或其他规格系统,保留该系统的工件格式和存储约定,不要再创建一份重复的 SPEC.md。这个 skill 负责澄清、内容和批准门禁;外部工具负责已批准 spec 的表示形式。

把指令重新框定为成功标准。 收到模糊需求时,把它们翻译成具体条件:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

这样你就能围绕清晰目标进行循环、重试和解决问题,而不是猜测 “faster” 是什么意思。

阶段 2:Plan

在 spec 已验证后,生成技术实现计划:

  1. 识别主要组件及其依赖
  2. 确定实现顺序(必须先构建什么)
  3. 记录风险和缓解策略
  4. 识别哪些可以并行构建,哪些必须顺序执行
  5. 定义阶段之间的验证检查点

这些步骤背后的依赖图映射和垂直切片机制,遵循 planning-and-task-breakdown;它是权威来源。上面的要点只是轻量摘要;两者若出现分歧,以 planning-and-task-breakdown 为准。

输出约定: 把计划保存到 tasks/plan.md,并把任务列表记录到 planning-and-task-breakdown 定义的 task list target(默认 tasks/todo.md;项目也可以指定外部 tracker)。如果 tasks/ 不存在则创建。下游命令(/build 等)依赖这些默认值。

计划应该可评审:人类读完后应该能说“对,这是正确做法”或“不,修改 X”。

阶段 3:Tasks

把计划拆解为离散、可实现的任务:

  • 每个任务都应能在一次专注会话中完成
  • 每个任务都有明确验收标准
  • 每个任务都包含验证步骤(测试、构建、手动检查)
  • 任务按依赖排序,而不是按感知重要性排序
  • 任何任务都不应需要修改超过约 5 个文件

完整的任务大小划分和依赖排序机制,遵循 planning-and-task-breakdown;它是权威来源。下面的模板只是轻量内联形式;两者若出现分歧,以 planning-and-task-breakdown 为准。

任务模板:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

阶段 4:Implement

一次执行一个任务,并遵循 skills/incremental-implementation/SKILL.md(incremental-implementation)和 skills/test-driven-development/SKILL.md(test-driven-development)。使用 skills/context-engineering/SKILL.md(context-engineering)在每一步加载正确的 spec 章节和源文件,而不是把整个 spec 都塞给 agent。

让 Spec 保持鲜活

spec 是一份活文档,不是一次性工件:

  • 决策变化时更新:如果你发现数据模型需要改变,先更新 spec,再实现。
  • 范围变化时更新:新增或砍掉的功能应该反映在 spec 中。
  • 提交 spec:spec 应该和代码一起进入版本控制。
  • 在 PR 中引用 spec:链接回每个 PR 实现的 spec 章节。

常见合理化借口

合理化借口现实
“这很简单,我不需要 spec”简单任务不需要长 spec,但仍然需要验收标准。两行 spec 可以。
“我写完代码后再补 spec”那是文档,不是规格说明。spec 的价值在于在代码之前强制澄清。
“spec 会拖慢我们”15 分钟 spec 可以避免数小时返工。15 分钟的 waterfall 胜过 15 小时的调试。
“需求反正会变”这正是 spec 是活文档的原因。过时的 spe
Read the complete source ↗