Search

什么是 SDD？规格驱动开发完全指南

SDD（Specification-Driven Development，规格驱动开发）是一种先写规格定义、再按规格驱动实现、最后用规格验证的软件开发方法论。

Pluszzz6 min read
SDDAIDevelopmentEngineering

什么是 SDD？

SDD（Specification-Driven Development，规格驱动开发） 是一种软件开发方法论：先写规格（Spec）定义“要做什么”，再按规格驱动实现（Build），最后用规格验证（Close）交付物是否正确。

传统开发 SDD
拿到需求 → 直接写代码 → 改来改去 拿到需求 → 先写规格（proposal + spec）→ AI 验证规格完整性 → 规格驱动实现 → 规格验证归档
需求与代码脱节，靠人脑记住“当初为什么这么写” 每个变更都有完整的 proposal.md → design.md → specs/ → plan-ready.md 链，可追溯
代码评审难，不知道是否漏了验收条件 specs/ 中的 Scenario（Given-When-Then）就是验收条件，close 阶段逐一比对

本手册中的 openflow 就是 SDD 的工作流实现，OpenSpec CLI 是规格管理工具，Superpowers 是 AI 辅助实现引擎。三者配合，实现完整的 SDD 开发闭环。

本手册教你如何在 Claude Code 中高效使用 5 个 Skill 完成 xahp 生态项目的 SDD 开发流程。

1. 快速开始

1.1 前置条件

项目 要求 验证方式
Claude Code 已安装并可用 终端输入 claude 能进入交互
openflow Skill 已安装 输入 /openflow 有响应
OpenSpec CLI 已安装 终端输入 openspec --version 有输出
Superpowers 已安装 Claude Code 可用 Skill 列表中有 writing-plans

1.2 OpenSpec CLI

是什么： OpenSpec 是一套“规格即代码”的工具链，把需求、设计、任务以结构化文档的形式管理在 openspec/changes/ 目录下。每个变更都有独立的目录，包含 proposal.md、design.md、specs/（规格变更）、tasks.md，由 openflow 的 spec 阶段自动生成。

核心概念

概念 说明 示例
变更（Change） 一个独立的功能或改动，对应 openspec/changes/<change-id>/ 目录 add-article-management
规格（Spec） 用 ADDED / MODIFIED / REMOVED 标记的增量需求，每个需求包含 Scenario（Given-When-Then） specs/article-crud/spec.md
Delta 需求变更的最小单元。每个 Requirement 必须包含 SHALL/MUST，每个 Scenario 描述一个具体交互 “The system SHALL support article CRUD”
归档（Archive） 变更完成后，规格增量合并到 openspec/specs/ 主规格库，变更目录移到 archive/ openspec archive add-article-management --yes

安装

Terminal window
npm install -g openspec

验证：openspec --version 有输出。

常用命令

Terminal window
# 查看所有活跃变更
openspec list


# 校验变更规格格式
openspec validate <change-id> --strict


# 查看变更解析出的 Delta 列表
openspec change show <change-id> --json --deltas-only


# 归档已完成的变更
openspec archive <change-id> --yes

1.3 Superpowers

是什么： Superpowers 是 Claude Code 的官方插件套件，提供一套强化 AI 实现能力的 Skill。核心包括 writing-plans 和 subagent-driven-development，由 openflow 的 build 阶段调用。

核心 Skill

Skill 作用 被 openflow 调用的阶段
writing-plans 读取 plan-ready.md，拆解为细粒度实现步骤（每个 2-5 分钟），生成带 checkbox 的详细计划文件到 docs/superpowers/plans/ build 入口
subagent-driven-development 识别可并行的 Task，派发多个子代理同时执行，各自完成后汇总结果 build 执行

安装

Terminal window
# 在 Claude Code 终端中输入
/plugin install superpowers@claude-plugins-official

验证：Claude Code 的可用 Skill 列表中出现 writing-plans。

实际效果

# 没有 Superpowers（手动模式）
AI 直接按 plan-ready.md 的步骤逐条执行


# 有 Superpowers
AI 调用 writing-plans → 生成详细计划（每个步骤含代码路径 + 验证命令）
AI 调用 subagent → 独立 Task 并行执行 → 汇总结果 → 标记 checkbox

1.4 OpenSpec、Superpowers 与 openflow 的关系

graph TB
  subgraph openflow["openflow"]
      direction LR
      A[proposal] --> B[brainstorming] --> C[spec] --> D[build] --> E[close]
  end
  C -.-> F[OpenSpec CLI]
  C -.-> G[Superpowers]
  E -.-> H[OpenSpec CLI]
Terminal window
# 符号链接到全局（推荐）
ln -s "$(pwd)/.claude/skills/openflow" ~/.claude/skills/openflow

验证安装

在 Claude Code 中输入 /openflow 应该能看到子命令提示

1.6 如何加载 Skill

Claude Code 中有两种加载方式：

方式一：显式调用

直接在对话中输入 Skill 名称或相关关键词。Claude Code 会识别并加载对应 Skill。

创建后端服务时

帮我用 xahp-gen 创建一个文章管理服务

需要权限认证帮助时

参考 xahp-backend，如何给 Controller 加数据权限？

前端页面开发时

按照 web-template-v3 的约定，写一个文章列表页

方式二：自动匹配

Claude Code 会根据你的问题自动匹配相关 Skill。例如你问“怎么配置 OAuth2 客户端”，AI 会自动加载 xahp-backend Skill。

2. 5 个 Skill 速查

2.1 openflow — 工作流协调器

定位： 管理 AI 辅助开发的 6 阶段流程，确保需求→设计→实现→归档可追溯。

适用场景：

  • 新功能开发（从需求到上线）
  • 多轮需求对话的需求收敛
  • 复杂变更的规格生成和翻译
  • 实现完成后的验证归档

核心能力： 6 个子命令（proposal/brainstorming/spec/amend/build/close）、状态检测、中断恢复、阶段写入边界

3. OpenFlow 工作流完整教程

3.1 6 阶段概览

proposal → brainstorming → spec → amend ⇄ build → close
阶段 命令 输入 输出 写入权限
proposal /openflow proposal 用户需求描述 proposal.md 仅 OpenSpec 需求文档
brainstorming /openflow brainstorming 需求 + 深度讨论 proposal.md（增强） 仅 OpenSpec 需求文档
spec /openflow spec proposal.md design.md + specs/ + tasks.md + plan-ready.md OpenSpec 文档 + plan-ready.md
amend /openflow amend 需求变更 更新的规格 + 计划 规格文档 + plan-ready.md
build /openflow build plan-ready.md 代码 / 实现文件 代码 + 测试
close /openflow close 已完成实现 归档记录 归档 + close-issues.md

3.2 proposal — 轻量需求捕获

目标： 用 3-5 个问题快速收敛需求，产出一页 proposal.md。

典型对话：

🧑 你： /openflow proposal 我想做一个数据导出功能，支持 Excel 和 PDF

🤖 AI： 好的，让我确认几个关键点：

  1. 做什么 — 数据导出功能，支持 Excel 和 PDF 两种格式
  2. 为什么 — 给运营人员导出报表？给用户导出自己的数据？
  3. 成功标准 — 哪些数据需要导出？需要筛选条件吗？
  4. 边界 — 是否需要定时导出？是否需要导出历史记录？
  5. 现有约束 — 用的是 xahp-common-easyexcel 吗？数据量大吗？

🧑 你： 给运营导出订单数据，支持时间范围和状态筛选，不要定时，用 easyexcel，数据量一般几千条。PDF 先不做。

🤖 AI： 我理解的需求是：为运营人员提供订单数据 Excel 导出功能。具体来说：

  • 支持按时间范围 + 订单状态筛选
  • 使用 xahp-common-easyexcel 实现
  • 暂不包含 PDF 和定时导出

这样理解对吗？

🧑 你： 对的

🤖 AI： 需求已记录到 openspec/changes/add-order-export/proposal.md。接下来用 /openflow spec 生成完整规格。

禁止： proposal 阶段不写代码，不修改任何实现文件。用户如果说“就这样做”、“继续”，AI 仍然是补 proposal 文档，不会进入实现。

3.3 brainstorming — 深度设计

与 proposal 类似但进行多轮深度设计探索。适用于技术方案不明确、架构决策影响大的场景。AI 会针对技术选择、架构方案、性能考量等展开多轮讨论。产物仍是 proposal.md，不写代码。

3.4 spec — 生成规格

目标： 根据 proposal.md 自动生成 design.md + specs/ + tasks.md，用户确认后翻译为 plan-ready.md。

前置条件： openspec/changes/<变更名>/proposal.md 已存在。

🧑 你： /openflow spec

🤖 AI： 检测到活跃变更 add-order-export。正在生成规格…

  • ✅ design.md — 技术方案（使用 xahp-common-easyexcel，Controller 模式）
  • ✅ specs/order-export/spec.md — 规格变更（ADDED: Excel 导出接口）
  • ✅ tasks.md — 4 个实现任务

以下是规格摘要：… 有需要调整的吗？

🧑 你： 继续

🤖 AI： 规格已确认，plan-ready.md 已生成（28 个步骤）。接下来用 /openflow build 开始实现。

3.5 amend — 受控修订

在 build 或 close 之前，如果需求发生变化，用 amend 而不是直接改代码。

⚠️ 不要在 build 阶段直接改需求！如果 build 中发现“用户其实还需要 XX”，先切到 /openflow amend 更新规格，再回到 build。

3.6 build — 执行实现

目标： 按 plan-ready.md 逐步骤执行实现。这是唯一允许写代码的阶段。

前置条件： plan-ready.md 存在。

执行流程：

  1. 检测 plan-ready.md 和任务状态
  2. 生成详细实现计划（如有 Superpowers）或手动执行
  3. 逐 Task 实现：先写失败测试 → 再写代码
  4. 每个 Task 完成后标记 checkbox

💡 build 阶段可以并行执行独立 Task。例如“写后端 Entity”和“写前端 API 模块”互不依赖，可用多个子代理同时进行。

3.7 close — 验证归档

目标： 验证实现与设计一致，将变更归档。

前置条件： 实现计划中所有 checkbox 已勾选。

执行流程：

  1. 确认实现状态（所有任务完成）
  2. 验证设计一致性（design.md 决策 vs 实际代码）
  3. 验证规格完整性（specs/ 变更 vs 实际实现）
  4. 不一致项记录到 close-issues.md（不在 close 阶段改代码！）
  5. 运行 openspec validate --strict 校验
  6. 执行 openspec archive --yes 归档

3.8 中断恢复机制

openflow 支持在任意阶段中断后无缝恢复：

场景 行为
proposal 中被打断，回来补充需求 AI 停留在 proposal，更新 proposal.md，不写代码
spec 中被打断，回来后说“继续” AI 继续 spec 阶段，产出文档
build 中被打断，回来后补充需求 AI 切到 amend（修改规格），不直接改代码
build 中被打断，回来后说“继续” AI 恢复 build，从断点 Task 继续

⚠️ 关键原则：在 proposal/spec 阶段用户说“就这样做”、“继续”不代表进入 build。必须先走完 spec → 生成 plan-ready.md → 才能 build。

5. 常见问题排查

Q: Skill 没被加载，输入 /xahp-gen 无响应

原因：Skill 文件不在 Claude Code 搜索路径中。

解决：确认 Skill 目录在项目的 .claude/skills/ 下。如果是全局 Skill，需要将文件复制到 Claude Code 的全局 skills 目录。检查方法：在对话中看可用 Skill 列表是否包含 xahp-backend/xahp-gen/web-template-v3/xahp-fullstack。

Q: 前端 401 错误，提示 Token 无效

原因：OAuth2 客户端凭据不匹配。前端 .env 文件中的 VITE_OAUTH2_PASSWORD_CLIENT 与后端 sys_oauth_client_details 表中的 client_id/client_secret 不一致。

解决：检查 .env 中的 VITE_OAUTH2_PASSWORD_CLIENT=client_id:secret 是否与数据库 sys_oauth_client_details 表中对应记录一致。确认 client 的 authorized_grant_types 包含 password。

Q: 前端 404，新服务的 API 访问不到

原因：Gateway 未注册新服务的路由规则。

解决：在 Nacos 动态路由配置中为新服务添加路由规则（参考 xahp-fullstack Step 6）。或检查已有路由的 predicates 路径模式是否匹配新服务的 API 前缀。

Q: 左侧菜单不显示新加的功能

原因：sys_menu 表中未插入菜单记录，或者菜单未通过 sys_role_menu 分配给当前用户角色。

解决：

  1. 确认 sys_menu 表中有对应菜单记录（type=0 菜单 + type=1 按钮）
  2. 在 sys_role_menu 中将菜单关联到角色
  3. 在 sys_user_role 中将角色分配给用户
  4. 重新登录，前端路由守卫会重新拉取菜单

Q: 不知道当前场景该用哪个 Skill

原因：Skill 选择场景不熟悉。

解决：参考本手册 Skill 关系图和最佳实践-场景映射。一般来说：创建项目用 xahp-gen，后端能力用 xahp-backend，前端用 web-template-v3，架构和流程用 xahp-fullstack，管理开发流程用 openflow。

Related posts

PLUSZZZ*ZHANGJIA*