TL;DR

  • SDD（规格驱动开发）用“先规格、再实现”的方式，把需求意图、约束与落地任务统一在同一条交付链上。
  • OpenSpec 把这条链落在 仓库里：用“变更提案（change）→ 规格（spec）→ 任务（tasks）→ 校验（validate）→ PR/Release”的闭环来推进团队协作。
  • 本文提供 10 分钟上手清单、落地建议与常见坑位排查，仓库内的 openspec/AGENTS.md 是进一步细则的权威入口。

为什么是 SDD（规格驱动开发）

很多团队的痛点并不在“代码写不出来”，而在“写对的东西、一次到位很难”：

  • 需求意图在讨论中逐步走样，规格与实现脱节；
  • 任务切分零散，PR 难以复盘“为什么要改”；
  • 文档与实现两套话术，维护成本高，知识沉淀断裂。

SDD 的核心是把“意图与约束（规格）”变成交付主线：先把“要什么、为什么”固化成可验证的规范，再据此拆解任务与实现，最后用自动化校验来保证收敛质量。这样可带来的直接收益是：

  • 用同一份“规格语言”串起需求、任务、代码与验证；
  • 设计权衡、非功能性需求（性能、兼容、安全）被显式纳入；
  • 交付中每一步都有“被验证”的依据，更容易 review 与复盘。

什么是 OpenSpec

OpenSpec 是把 SDD 落在 GitHub 的一套实践模板与约定，通常包括：

  • 变更提案（Change）：以“动词开头的唯一 ID”代表一次跨多文件/多模块的能力变更；
  • 规格（Specs）：围绕用户能力/系统约束的清单化描述，含场景与验收；
  • 任务（Tasks）：把规格落到可执行的小步快跑；
  • 设计（Design，可选）：跨系统或需要取舍时的方案权衡记录；
  • 校验（Validate）：以工具对规范与实现进行一致性检查；
  • PR/Release：从变更到上线的可追溯链路（含标签、模板与检查项）。

在本仓库内，你可以参考 openspec/AGENTS.md 与 openspec/project.md 获取约定与命令举例；在日常协作中使用 openspec 命令辅助管理与校验。

工作流总览

尚未安装 OpenSpec？请先完成安装与初始化：/tutorials/openspec-install/

快速上手（30 秒）

# 查看当前仓库的变更与规格
openspec list
openspec list --specs

# 校验某个变更（提交前必跑）
openspec validate <change-id> --strict

OpenSpec 初始化向导与 AI 助手选择

  1. 提出变更提案：定义 change-id（动词开头，如 add-authz-policy），声明目标与范围。
  2. 编写规格：在 openspec/changes/<id>/specs/<capability>/spec.md 中写清“要求/场景/验收”。
  3. 拆分任务：在 openspec/changes/<id>/tasks.md 列出小步、可验证的工作项。
  4. 如有必要，补充设计：在 design.md 记录关键取舍与风险对策。
  5. 校验：openspec validate <id> --strict，修复所有问题直至通过。
  6. 实现与 PR：按任务推进开发，PR 关联 change-id 并通过检查项。
  7. 发布与归档：Release 后归档变更，保证历史可追溯与知识沉淀。

核心构件与示例

变更提案（Change）

  • 命名：动词开头、短小有力（如 add-user-onboarding、refactor-media-pipeline）。
  • 入口：openspec/changes/<id>/proposal.md，包含目标、范围、非目标、依赖与风险。

规格（Specs）

  • 结构：按能力分文件；每个 spec.md 使用 ## ADDED|MODIFIED|REMOVED Requirements 编写；每条要求至少一个 #### Scenario:。
  • 关注：用户视角的可观测结果与边界条件、验收口径与反例。

任务（Tasks）

  • 原则：小步快跑、可验证、能持续合并；避免“一口气做完所有事情”。
  • 示例：
    • 「接入鉴权中间件并保留灰度开关」
    • 「为 /v2/* 路由写互斥率限规则与回归测试」

按优先级顺序的阶段推进与 TDD 红黄绿状态提示，包含下一步执行建议 图：OpenSpec 建议采用按优先级顺序（Sequential by Priority）与 TDD 驱动任务推进

设计（Design）

  • 适用：跨系统影响、资源消耗权衡、安全/合规要求显著的场景。
  • 内容：方案对比、取舍理由、数据流/时序图、失败场景与降级策略。

校验（Validate）

  • 目标：确保“规格—任务—实现—验证”间的一致性与完整性。
  • 常用命令：
# 列出当前仓库下的变更与状态
openspec list

# 查看所有能力规格（按仓库已有）
openspec list --specs

# 严格校验某个变更（提交前必跑）
openspec validate <change-id> --strict

# 查看某个规格或变更详情
openspec show <spec> --type spec
openspec show <change-id> --deltas-only

OpenSpec 规格质量门禁（Quality Gate PASS）示例

失败排查建议：使用 openspec show <id> --json 获取细节；对照 openspec/AGENTS.md 的校验项逐条修复。

10 分钟上手清单

  1. 建立首个变更（change）：
    • 选择一个对用户“可感知”的小能力；
    • 以动词命名 change-id，在 openspec/changes/<id>/ 建立 proposal.md；
    • 在 specs/ 下以能力为单位编写 spec.md，包含至少 1 条要求与 1 个场景。
  2. 拆分任务与并行推进：
    • 在 tasks.md 罗列 3–7 个小任务；
    • 先做“加可观测性/加保护”的任务，后做破坏性改动；
    • 每合并一次，更新任务勾选与备注，保持轨迹清晰。
  3. 本地校验并提交 PR：
    • openspec validate <id> --strict 直至通过；
    • PR 标题与描述中包含 change-id 与“完成度/风险/回滚方式”。

在你项目里如何落地

  • 渐进式引入：从单一仓库/单一模块开始试点，优先选择“体验影响大、技术风险小”的能力；
  • 单仓 vs 多仓：单仓更容易统一流程；多仓建议用同一模板/检查项，变更跨仓时以“父 change 管辖子 change”方式管理；
  • 与 Issue/Jira 协同：保持“规格与变更”在 GitHub，任务可映射到现有工单系统，但 PR 必须回链 change-id；
  • 非功能性需求（NFR）：为性能、安全、兼容性建立独立规格与场景清单，避免被实现挤占；
  • 文档不过期：把“验收口径/场景”写入自动化校验或回归测试，确保变更后的文档能跑、能验、能复现。

最佳实践与命名规范

  • change-id：动词-对象-限定（add-authz-policy-mobile、migrate-image-cdn）；
  • 目录：openspec/changes/<id>/{proposal.md,tasks.md,design.md,specs/...}；
  • 提交规范：遵循 Conventional Commits（feat/fix/docs/…）；PR 模板包含：范围、风险、验证方式、回滚计划；
  • 校验策略：开发中频繁 openspec validate，CI 在 PR 必跑 --strict；
  • 版本与发布：变更与 Release 对齐，保留“有哪些规格/场景被满足”的清单化记录。

常见问题（FAQ）

Q：会不会拖慢交付？ 不会。SDD 强调“小步+校验”。在节奏感上更接近“持续集成”，而不是“大文档批核”。

Q：文档会不会过期？ 规格是“可被校验”的文档，配合 openspec validate 与回归测试，可以持续发现偏移并快速修正。

Q：和 ADR/设计文档的关系？ ADR 偏“决策记录”，SDD 的 design.md 更关注“为了满足哪些规格在做哪些取舍”，两者可以互补。

Q：跨团队如何协作？ 以 change-id 为协作单位；父变更下挂子变更，保持规格和接口契约的一致性与版本化。

仓库内参考与下一步

  • 规范与流程：openspec/AGENTS.md、openspec/project.md
  • 命令速查：在根目录运行 openspec list、openspec list --specs、openspec validate <id> --strict
  • 建议先以“新增一项小能力”为起点，把本文的 10 分钟清单走通，再推广到团队日常。

——

如果你希望本文与参考文章在结构或措辞上更接近，请提供可复制的正文文本或要点摘要。我可以据此做一次“逐段映射”的改写，并补充对照表与仓库内落地示例。