@zw-team/sddmini

Spec-Driven Development — 基于 Claude Code 的状态机驱动开发工作流，只服务新 capability。

通过 shell 脚本状态机把 Superpowers（设计/规划/执行引擎）桥接为四阶段流水线，用可执行的门控取代纯 prompt 约束，确保 LLM 不跳阶段、不丢进度。SDD 自带轻量 capsule 档案能力，无需任何外部 spec CLI。

何时不用 SDD：bug 修复、文案微调、配置变更、prompt 微调等局部小改动 — 直接用 Claude Code plan mode。

安装

npx @zw-team/sddmini init

交互式选择安装模式：

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

依赖：

• Superpowers — Claude Code 插件，安装时自动检测并尝试安装

升级

npx @zw-team/sddmini update

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

卸载

npx @zw-team/sddmini uninstall

移除全局配置的 SDD skills/commands/scripts 和相关权限。

使用

# 统一入口，自动检测阶段并连续执行（不含归档步骤）
/sdd 我想新增视频拼接 capability

# 逐阶段手动推进
/sdd:think 我想新增视频拼接 capability
/sdd:build
/sdd:verify
/sdd:archive

四阶段流水线

/sdd
  ↓ 自动检测
sdd-think ──→ sdd-build ──→ sdd-verify ──→ sdd-archive

| 阶段 | 命令 | 职责 | 产物 | |------|------|------|------| | Think | /sdd:think | 澄清需求 + capsule + brainstorming（合并了原 think + design） | proposal.md + Design Doc + delta spec | | Build | /sdd:build | superpowers:writing-plans + 执行 | plan.md + 业务代码 | | Verify | /sdd:verify | 验证一致性 + 处理分支 | 验证报告 | | Archive | /sdd:archive | spec 同步 + SP 产物搬运入 capsule + 归档 | 完整归档目录 |

辅助命令

| 命令 | 用途 | |------|------| | /sdd:update | 中途变更同步（Patch/Extend/Rethink 三级评估） | | /sdd:help | 显示使用帮助 |

核心机制

状态机 + 脚本门控

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

# 初始化状态机（仅 full workflow）
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 不影响进度
• 枚举校验 + 路径遍历防护 — 防止状态文件损坏

内置 capsule 档案

sdd-spec.sh 提供 capsule scaffold / sync / list 能力，不依赖任何外部 spec CLI：

sdd-spec.sh new <change-name>                    # scaffold capsule（仅 proposal.md）
sdd-spec.sh new-spec <change-name> <capability>  # 按需创建 delta spec stub
sdd-spec.sh sync <change-name>                   # delta → main spec
sdd-spec.sh list [--active|--archived|--all]     # 列举 capsule

archive 阶段把 superpowers 产物（Design Doc / plan / verify report）搬入 capsule 并改规范名（design.md / plan.md / verify-report.md），原路径作为 archived-from frontmatter 字段保留。

脚本清单

| 脚本 | 职责 | |------|------| | sdd-state.sh | 状态 CRUD + 转换验证 + 入口检查 + 规模评估 | | sdd-guard.sh | 出口条件验证 + --apply 自动转换 + 构建/测试执行 | | sdd-archive.sh | 原子归档（spec sync + SP 产物搬运 + 标注 + 移动 + 状态更新） | | sdd-spec.sh | capsule scaffold / sync / list | | sdd-validate.sh | YAML schema 校验（字段存在性 + 枚举值 + 路径有效性） |

执行顺序总览

think 开始
└─ sdd-spec.sh new            ← 创建 capsule（proposal.md）
└─ sdd-state.sh init          ← 创建状态机
└─ sdd-state.sh check think
└─ ... 澄清 + brainstorming → Design Doc + delta spec ...
└─ sdd-guard.sh think --apply ← 出口门控 + 状态转换 → build

build 开始
└─ sdd-state.sh check build
└─ sdd-state.sh set isolation/build_mode/tdd_mode
└─ ... writing-plans → executing-plans / subagent-driven-development → 实现 ...
└─ 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             ← 一键归档（含 SP 产物搬运）

安装后的文件结构

全局安装 (~/.claude/)

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

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

工作期：

your-project/
├── openspec/
│   ├── changes/<name>/                # /sdd:think 自动创建
│   │   ├── .sdd.yaml                  # 状态文件
│   │   ├── proposal.md                # SDD 独占
│   │   └── specs/<capability>/spec.md # 按需 delta spec
│   └── specs/<capability>/spec.md     # main spec（archive 时由 delta 覆写）
└── docs/superpowers/                  # Superpowers 临时产物（archive 时搬走）
    ├── specs/                         # Design Doc
    ├── plans/                         # 实现计划
    └── reports/                       # 验证报告

归档后：

openspec/changes/archive/YYYY-MM-DD-<name>/
├── proposal.md
├── design.md          ← 从 SP specs/ 搬来
├── plan.md            ← 从 SP plans/ 搬来
├── verify-report.md   ← 从 SP reports/ 搬来
└── specs/<capability>/spec.md

FAQ

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

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

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

Q: 我要修一个 bug，要走 SDD 吗？ 不需要。SDD 只服务新 capability。bug 修复、文案、配置、prompt 调整等小改动直接用 Claude Code plan mode 即可。

Q: context compaction 后怎么恢复？ .sdd.yaml 在磁盘上永久存在。重新执行 /sdd 即可从断点继续。think 阶段会按 capsule 中已落盘产物自动判断进度。

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

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

Q: 历史用 hotfix/tweak workflow 创建的 change 还能继续吗？ 可以。状态机和 guard 都保留对历史 workflow 值的兼容，但新建 change 一律为 full。

开发与发版

# 本地调试
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 版本升级