@zw-team/sdd

Spec-Driven Development — 基于 Claude Code 的状态机驱动开发工作流。

将 Superpowers（设计/规划/执行引擎）与 OpenSpec（需求持久化层）通过 shell 脚本状态机桥接为五阶段流水线，用可执行的门控取代纯 prompt 约束，确保 LLM 不跳阶段、不丢进度。

安装

npx @zw-team/sdd init

交互式选择安装模式：

• 全局安装 (~/.claude/) — 所有项目共享
• 本地安装 (当前目录 .claude/) — 仅当前项目

安装时自动检测并安装依赖：

• OpenSpec — 需求持久化 CLI
• Superpowers — Claude Code 插件

升级

npx @zw-team/sdd update

自动检测全局/本地安装位置，覆盖 skills、commands、scripts。

卸载

npx @zw-team/sdd uninstall

移除全局配置的 SDD skills/commands/scripts 和相关权限。项目级安装请手动删除 .claude/ 下的 SDD 文件。

使用

# 统一入口，自动检测阶段并连续执行，不含归档步骤
/sdd 我想给用户列表页增加批量操作功能

# 逐阶段手动推进
/sdd:think 我想给用户列表页增加批量操作功能
/sdd:design
/sdd:build
/sdd:verify
/sdd:archive

# 快捷路径
/sdd --hotfix 修复按钮点击无响应的问题
/sdd --tweak 把提交按钮文案改为"确认提交"

五阶段流水线

/sdd
  ↓ 自动检测
sdd-think ──→ sdd-design ──→ sdd-build ──→ sdd-verify ──→ sdd-archive
(OpenSpec)    (Superpowers)   (Superpowers)  (Both)        (OpenSpec)

| 阶段 | 命令 | 职责 | 产物 | |------|------|------|------| | Think | /sdd:think | 探索想法 + 创建 change 结构 | proposal.md, design.md, tasks.md | | Design | /sdd:design | 深度技术设计（brainstorming） | Design Doc + delta spec | | Build | /sdd:build | 制定计划 + 执行实现 | plan + 业务代码 | | Verify | /sdd:verify | 验证一致性 + 处理分支 | 验证报告 | | Archive | /sdd:archive | spec 同步 + 归档 + 清理 | 归档目录 |

辅助命令

| 命令 | 用途 | |------|------| | /sdd:update | 中途变更同步（Patch/Extend/Rethink 三级评估） | | /sdd:help | 显示使用帮助 | | /sdd --hotfix | Bug 修复快捷路径（跳过 design） | | /sdd --tweak | 小改动快捷路径（轻量流程） |

Preset 快捷路径

| Preset | 流程 | 适用场景 | |--------|------|---------| | --hotfix | think(简化) → build(direct) → verify → archive | Bug 修复，≤2 文件 | | --tweak | think(简化) → build(简化) → verify(轻量) → archive | 文案/配置微调，≤3 任务 |

超出范围时自动升级到完整流程。

核心机制

状态机 + 脚本门控

每个 change 有独立状态文件 openspec/changes/<name>/.sdd.yaml，由 shell 脚本强制执行：

# 初始化状态机
sdd-state.sh init <name> full

# 入口检查（脚本级强制，LLM 无法绕过）
sdd-state.sh check <name> build

# 出口门控 + 自动转换
sdd-guard.sh <name> build --apply

# 规模评估（自动选择验证模式）
sdd-state.sh scale <name>

为什么用脚本而不是纯 prompt：

• exit 1 是硬约束 — LLM 无法忽略工具失败
• .sdd.yaml 持久化在磁盘 — context compaction 和 /clear 不影响进度
• 枚举校验 + 路径遍历防护 — 防止状态文件损坏

脚本清单

| 脚本 | 职责 | |------|------| | sdd-state.sh | 状态 CRUD + 转换验证 + 入口检查 + 规模评估 | | sdd-guard.sh | 出口条件验证 + --apply 自动转换 + 构建/测试执行 | | sdd-archive.sh | 原子归档（spec sync + 标注 + 移动 + 状态更新） | | sdd-validate.sh | YAML schema 校验（字段存在性 + 枚举值 + 路径有效性） | | sdd-handoff.sh | 设计阶段上下文打包（SHA256 完整性验证） |

执行顺序总览

think 开始
└─ sdd-state.sh init         ← 创建状态机
└─ sdd-state.sh check think  ← 入口检查
└─ ... 创建 proposal/design/tasks ...
└─ sdd-guard.sh think --apply ← 出口门控 + 状态转换

design 开始
└─ sdd-state.sh check design
└─ sdd-handoff.sh design --write  ← 打包上下文
└─ ... brainstorming → Design Doc ...
└─ sdd-guard.sh design --apply

build 开始
└─ sdd-state.sh check build
└─ sdd-state.sh set isolation/build_mode
└─ ... 实现代码 ...
└─ sdd-guard.sh build --apply

verify 开始
└─ sdd-state.sh check verify
└─ sdd-state.sh scale         ← 决定 light/full
└─ ... 验证 + 写报告 ...
└─ sdd-guard.sh verify --apply

archive 开始
└─ sdd-state.sh check archive
└─ sdd-archive.sh             ← 一键归档

安装后的文件结构

全局安装 (~/.claude/)

~/.claude/
├── skills/
│   ├── sdd-think/SKILL.md
│   ├── sdd-design/SKILL.md
│   ├── sdd-build/SKILL.md
│   ├── sdd-verify/SKILL.md
│   ├── sdd-archive/SKILL.md
│   ├── sdd-unified/SKILL.md
│   ├── sdd-update/SKILL.md
│   ├── sdd-hotfix/SKILL.md
│   ├── sdd-tweak/SKILL.md
│   ├── sdd-help/SKILL.md
│   └── sdd/scripts/
│       ├── sdd-state.sh
│       ├── sdd-guard.sh
│       ├── sdd-archive.sh
│       ├── sdd-validate.sh
│       ├── sdd-handoff.sh
│       └── reference/dirty-worktree.md
├── commands/
│   ├── sdd.md
│   └── sdd/
│       ├── think.md
│       ├── design.md
│       ├── build.md
│       ├── verify.md
│       ├── archive.md
│       ├── update.md
│       ├── hotfix.md
│       ├── tweak.md
│       └── help.md
└── settings.json              ← 自动合并脚本执行权限

运行时产物（在项目目录中）

your-project/
├── openspec/
│   ├── config.yaml            # 需要用户创建（项目技术栈描述）
│   └── changes/<name>/        # 每次 /sdd:think 自动创建
│       ├── .sdd.yaml          # 状态文件
│       ├── proposal.md
│       ├── design.md
│       └── tasks.md
└── docs/superpowers/          # Superpowers 临时产物
    ├── specs/                 # Design Doc
    ├── plans/                 # 实现计划
    └── reports/               # 验证报告

配置

必要配置

1. openspec/config.yaml — 在项目中创建，描述产品和技术栈（供 SDD 理解上下文）
2. 权限 — sdd init 已自动配置脚本执行权限

推荐配置

• CodeGraph MCP Server — 为 think/design 阶段提供精准代码上下文
• Superpowers 插件 — sdd init 已自动安装

FAQ

Q: 必须走完五阶段吗？ 不必。每个阶段独立可用。/sdd:think 可以单独做设计探索。

Q: /sdd 和 /sdd:think 有什么区别？ /sdd 是统一入口，自动检测当前阶段并连续执行。/sdd:think 只执行 think 阶段。

Q: 为什么不让 skill 自动 git commit？ 设计决策。git 操作有不可逆风险，由用户自行控制更安全。

Q: hotfix/tweak 和完整流程的界限？ hotfix: ≤2 文件、无架构变更、无新接口。tweak: ≤3 任务、≤4 文件、无新功能。超出则升级。

Q: context compaction 后怎么恢复？ .sdd.yaml 在磁盘上永久存在。重新执行 /sdd 即可从断点继续。

Q: 全局安装和本地安装怎么选？

• 全局安装：所有项目共享一套 SDD，适合个人开发者
• 本地安装：跟随项目仓库，适合团队协作（确保版本一致）

开发与发版

# 本地调试
npm link
sdd --version

# 预览发版
npm run release:dry

# 正式发版（bump + changelog + tag + push + npm publish）
npm run release

Commit message 遵循 Conventional Commits：

• feat: xxx → minor 版本升级
• fix: xxx → patch 版本升级
• feat!: xxx 或 BREAKING CHANGE: → major 版本升级