# SDD-template

**Repository Path**: wangyuhan123/sdd-template

## Basic Information

- **Project Name**: SDD-template
- **Description**: superpowers+openspec 打造的通用SDD工作流Skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SDD-Template

**Spec-Driven Development** -- 一套基于 Claude Code 的薄编排开发工作流模板。

将 **Superpowers** 插件（设计/规划/执行引擎）与 **OpenSpec**（需求持久化层）桥接为五步流水线，用最少的编排代码驱动从创意到交付的完整生命周期。

---

## 目录

1. [设计理念](#1-设计理念)
2. [系统架构](#2-系统架构)
3. [目录结构](#3-目录结构)
4. [五步工作流详解](#4-五步工作流详解)
5. [纯 OpenSpec 旁路](#5-纯-openspec-旁路)
6. [快速开始](#6-快速开始)
7. [配置说明](#7-配置说明)
8. [中途变更策略](#8-中途变更策略)
9. [常见问题](#9-常见问题)

---

## 1. 设计理念

### 1.1 核心原则

| 原则 | 说明 |
|------|------|
| **薄桥接** | SDD skill 本身不做决策，只做"注入上下文 + 委托 + 拦截终态转换" |
| **双引擎分工** | Superpowers 负责思考和执行；OpenSpec 负责持久化和追溯 |
| **显式阶段门控** | 每步 skill 通过 HARD-GATE / OVERRIDE 阻断自动级联，用户用命令显式推进 |
| **git 用户自治** | 所有 git 操作（commit / push / PR / merge）不由 skill 执行，全权交给用户 |
| **中文优先** | 文档正文中文；文件名、代码、路径保持英文 kebab-case |

### 1.2 为什么这样设计

传统 AI 辅助编码的问题：

1. **黑盒跳跃** -- AI 收到需求后直接写代码，跳过设计和验收标准定义，产出不可控。
2. **上下文丢失** -- 多轮对话后设计决策散落在聊天记录中，无法回溯。
3. **自动级联失控** -- 各 skill 自动串联，用户失去对节奏的控制。

SDD 的应对：

- **Think → Spec → Plan → Code → Ship** 强制分离关注点，每步有明确入/出条件。
- OpenSpec 将所有设计产物落盘为结构化文件，不依赖对话记忆。
- HARD-GATE 机制确保每次阶段转换都需要用户显式触发。

### 1.3 设计哲学

```
"SDD skills are thin bridges -- they delegate decision-making
 to Superpowers and persistence to OpenSpec."
```

每个 SDD skill 做三件事且仅三件事：
1. **定位输入** -- 找到上游产物（design spec / OpenSpec change / plan 文件）
2. **注入上下文 + 委托** -- 将输入传给 Superpowers skill 处理
3. **拦截终态** -- 阻止 Superpowers 自动级联到下一阶段，给出"下一步"提示

---

## 2. 系统架构

### 2.1 整体拓扑

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户命令层                                 │
│  /sdd:think  /sdd:spec  /sdd:plan  /sdd:code  /sdd:ship        │
│  /sdd:update (中途变更同步)                                       │
└──────┬───────────┬──────────┬──────────┬──────────┬─────────────┘
       │           │          │          │          │
┌──────▼───────────▼──────────▼──────────▼──────────▼─────────────┐
│                     SDD Skill 薄桥接层                            │
│  sdd-think │ sdd-spec │ sdd-plan │ sdd-code │ sdd-ship          │
│  (委托+拦截)  (桥接转换)  (注入+委托) (纯委托)   (验证+归档)       │
│  sdd-update (影响评估 + 产物同步，自包含逻辑)                      │
└──────┬───────────┬──────────┬──────────┬──────────┬─────────────┘
       │           │          │          │          │
┌──────▼───────────┼──────────▼──────────▼──────────▼─────────────┐
│           Superpowers 执行引擎                                    │
│  brainstorming │ writing-plans │ subagent-driven-dev │ verify    │
│  (设计探索)      (计划拆分)       (TDD 实现)           (最终验证)  │
└──────────────────┼──────────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────────┐
│               OpenSpec 持久化层                                   │
│  openspec/changes/<name>/                                        │
│    ├── proposal.md    (背景动机、影响范围、Capabilities)           │
│    ├── design.md      (技术选型、数据流、组件拆分)                 │
│    ├── specs/         (验收标准 SHALL/MUST + WHEN/THEN 场景)      │
│    └── plan.md        (归档时从 Superpowers 搬入)                 │
│  openspec/changes/archive/   (已完成的变更)                       │
│  openspec/CHANGELOG.md       (变更日志)                           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│             CodeGraph 代码智能层（MCP Server）                     │
│  基于 tree-sitter 的 AST 解析 + SQLite 知识图谱                   │
│  提供：符号搜索、调用链分析、变更影响分析、上下文构建              │
│  消费方：sdd-think (Step 0 作用域预加载)、brainstorming 内部探索  │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 数据流

```
brainstorming 产出           OpenSpec 归档            Superpowers 产出
docs/superpowers/specs/     openspec/changes/        docs/superpowers/plans/
  YYYY-MM-DD-*-design.md      <name>/                  YYYY-MM-DD-*.md
         │                      ├── proposal.md             │
         │   /sdd:spec          ├── design.md               │
         └──────────────────────├── specs/**/*               │
                                │                           │
                                │   /sdd:plan               │
                                └───────────────────────────┘
                                                            │
                                            /sdd:code       │
                                    (Superpowers 读 plan    │
                                     驱动 TDD 实现)         │
                                                            │
                                            /sdd:ship       │
                                    (搬 plan → OpenSpec     ▼
                                     归档 → 清理临时文件)
```

### 2.3 依赖关系

| 组件 | 来源 | 安装方式 |
|------|------|---------|
| Claude Code | Anthropic CLI | `npm i -g @anthropic-ai/claude-code` |
| Superpowers 插件 (v5.1.0+) | claude-plugins-official | Claude Code 内启用 |
| CodeGraph MCP Server | codegraph | Claude Code MCP 配置（推荐；提供代码智能索引） |
| OpenSpec CLI | 项目约定 | 通过 `openspec` 命令（可选；SDD 流程不依赖 CLI） |

---

## 3. 目录结构

```
SDD-Template/
├── .claude/
│   ├── commands/
│   │   ├── sdd/                    # SDD 斜杠命令
│   │   │   ├── think.md
│   │   │   ├── spec.md
│   │   │   ├── plan.md
│   │   │   ├── code.md
│   │   │   ├── ship.md
│   │   │   └── update.md
│   │   └── opsx/                   # 纯 OpenSpec 斜杠命令
│   │       ├── explore.md
│   │       ├── propose.md
│   │       ├── apply.md
│   │       └── archive.md
│   ├── skills/
│   │   ├── sdd-think/SKILL.md
│   │   ├── sdd-spec/SKILL.md
│   │   ├── sdd-plan/SKILL.md
│   │   ├── sdd-code/SKILL.md
│   │   ├── sdd-ship/SKILL.md
│   │   ├── sdd-update/SKILL.md
│   │   ├── openspec-explore/SKILL.md
│   │   ├── openspec-apply-change/SKILL.md
│   │   ├── openspec-archive-change/SKILL.md
│   │   └── openspec-propose/SKILL.md
│   └── settings.local.json         # 项目级权限配置
├── .codegraph/
│   ├── config.json                 # CodeGraph 索引配置（语言、排除规则）
│   └── .gitignore                  # 排除索引数据库（仅保留配置）
├── openspec/
│   ├── config.yaml                 # OpenSpec 配置（技术栈、规则）
│   ├── CHANGELOG.md                # 变更日志
│   ├── changes/                    # 活跃变更
│   │   └── archive/                # 已归档变更
│   └── specs/                      # 全局 spec（可选）
├── docs/
│   └── superpowers/                # Superpowers 运行时产物（临时）
│       ├── specs/                  # design spec 文件
│       └── plans/                  # 实现计划文件
└── README.md
```

---

## 4. 五步工作流详解

### 4.1 Think -- 设计探索

```
命令：/sdd:think <你的想法或需求>
委托：superpowers:brainstorming
产出：docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
```

**做什么**：
- **作用域预加载（CodeGraph 优先）**：利用 `codegraph_context` 精准定位相关文件和符号依赖；CodeGraph 不可用时降级为 Glob/Grep
- 探索项目上下文（代码、文档、git 历史）
- 一问一答澄清需求（不超过 3 轮）
- 提出 2-3 个方案及权衡
- 分段呈现设计，逐段获得用户确认
- 产出完整 design spec 文件

**不做什么**：
- 不写业务代码
- 不创建 OpenSpec 文件
- 不自动进入 plan 阶段（HARD-GATE 拦截）

**完成后输出**：
```
设计已完成，文件已保存。
下一步：
-> /sdd:spec --- 基于设计建立 OpenSpec 档案
-> 或直接告诉我新需求继续讨论
```

---

### 4.2 Spec -- 需求建档

```
命令：/sdd:spec [可选的 change 名]
产出：openspec/changes/<name>/ 完整目录
```

**做什么**：
- 读取 brainstorming 产出的 design spec
- 推荐 2-3 个 kebab-case 名称供用户选择
- 创建 OpenSpec change 目录
- 生成 `proposal.md`（背景、影响范围、Capabilities）
- 生成 `design.md`（技术选型、数据流、组件拆分、风险）
- 生成 `specs/<capability>/spec.md`（验收标准 + 场景）

**不做什么**：
- 不做设计探索（由 /sdd:think 完成）
- 不生成实现计划
- 不写业务代码

**完成后输出**：
```
OpenSpec 档案已创建：openspec/changes/<name>/
下一步：
-> /sdd:plan --- 创建实现计划
```

---

### 4.3 Plan -- 实现规划

```
命令：/sdd:plan [可选的 change 名]
委托：superpowers:writing-plans
产出：docs/superpowers/plans/YYYY-MM-DD-<name>.md
```

**做什么**：
- 从 design spec 中提取作用域提示（相关目录、核心文件、技术关键词），为 writing-plans 提供探索起点
- 委托 writing-plans 拆分任务（每个 2-5 分钟粒度）
- 每个任务包含：具体文件路径、完整代码、TDD 步骤
- 产出可执行的实现计划文件

**不做什么**：
- 不自行拆任务（由 writing-plans 负责）
- 不硬限制 writing-plans 的代码探索范围（只引导起点）
- 不写业务代码
- 不自动进入执行阶段（OVERRIDE 拦截）

**完成后输出**：
```
实现计划已创建。下一步：
-> /sdd:code --- 开始实现
```

---

### 4.4 Code -- TDD 实现

```
命令：/sdd:code [可选的 plan 路径]
委托：superpowers:subagent-driven-development 或 superpowers:executing-plans
产出：业务代码实现
```

**做什么**：
- 读取 plan 文件，检测任务进度（支持中断后恢复）
- 自动选择执行方式：任务独立 → 并行执行（subagent-driven）；有依赖 → 串行执行（executing-plans）
- 按任务逐个实现（TDD: RED → GREEN → REFACTOR）
- 每个任务完成后做 spec review + code quality review
- 实时更新 plan 文件中的完成标记（`- [x]`）以支持断点续传

**不做什么**：
- 不执行 git 操作
- 不自动调用 finishing-a-development-branch（OVERRIDE 拦截）

**完成后输出**：
```
实现完成。下一步：
-> /sdd:ship --- 验证并归档
```

---

### 4.5 Ship -- 验证归档

```
命令：/sdd:ship [可选的 change 名]
委托：superpowers:verification-before-completion
产出：归档完成 + 临时文件清理
```

**执行 7 道 Gate**：

| Gate | 动作 |
|------|------|
| 1. 最终验证 | 运行 lint/build/test，验证失败则停止 |
| 2. 定位产物 | 找到关联的 change + plan + spec 文件 |
| 3. 搬运产物 | 将 plan 复制到 OpenSpec change 目录 |
| 4. 归档 | 移动 change 到 `archive/YYYY-MM-DD-<name>/` |
| 5. CHANGELOG | 追加条目到 `openspec/CHANGELOG.md` |
| 6. 清理 | 删除 `docs/superpowers/` 下的临时产物 |
| 7. 汇报 | 输出归档路径和清理列表 |

**完成后输出**：
```
### SHIP COMPLETE
归档路径：openspec/changes/archive/YYYY-MM-DD-<name>/
CHANGELOG：- YYYY-MM-DD <name>: <一句话描述>
已清理：[文件列表]
-> 请自行处理 git commit / PR / merge
```

---

## 5. 纯 OpenSpec 旁路

除 SDD 五步流外，项目保留了不经 Superpowers 的纯 OpenSpec 路径：

| 命令 | 用途 |
|------|------|
| `/opsx:explore` | 思考探索（不写代码，只讨论和创建 OpenSpec 产物） |
| `/opsx:propose` | 快速建档（一步创建 proposal + design + specs + tasks） |
| `/opsx:apply` | 按 tasks.md 逐任务实现 |
| `/opsx:archive` | 归档已完成变更 |

**何时用 SDD vs 纯 OpenSpec**：

- **SDD**：需要深度设计探索、详细计划拆分、TDD 驱动实现的中大型功能
- **纯 OpenSpec**：快速小变更、已有明确方案只需记录和执行

---

## 6. 快速开始

### 6.1 环境准备

1. 安装 Claude Code CLI
2. 启用 Superpowers 插件：
   ```json
   // ~/.claude/settings.json
   {
     "enabledPlugins": {
       "superpowers@claude-plugins-official": true
     }
   }
   ```
3. 配置 CodeGraph MCP Server（推荐）：
   ```json
   // .claude/settings.local.json 或 ~/.claude/settings.json
   {
     "mcpServers": {
       "codegraph": {
         "command": "codegraph",
         "args": ["mcp"]
       }
     }
   }
   ```
4. 初始化 CodeGraph 索引（项目根目录已包含 `.codegraph/config.json`）：
   ```bash
   codegraph init -i
   ```
5. 将本模板复制到你的项目根目录

### 6.2 配置 `openspec/config.yaml`

替换 `context` 段中的技术栈信息为你项目的实际情况：

```yaml
schema: spec-driven

context: |
  ## 产品与技术栈
  - 产品：**你的产品名**；仓库：your-repo。
  - 前端：React 18 / Vue 3 / ...
  - 包管理：npm / pnpm / yarn
  - UI：Ant Design / Element Plus / ...
  ...
```

### 6.3 典型开发流程

```bash
# 1. 有一个想法，想探索设计
> /sdd:think 我想给用户列表页增加批量操作功能

# 2. brainstorming 完成后，将设计落盘
> /sdd:spec

# 3. 基于 spec 生成实现计划
> /sdd:plan

# 4. 开始 TDD 实现
> /sdd:code

# 5. 实现完成，验证并归档
> /sdd:ship

# 6. 用户自行处理 git
> git add -A && git commit -m "feat: batch operations for user list"
> git push
```

### 6.4 可跳步使用

流程不是强制线性的，你可以：

- 只用 `/sdd:think` 做设计探索，不建档
- 从 `/sdd:plan` 开始（如果你手动创建了 OpenSpec change）
- 从 `/sdd:code` 开始（如果你手动写了 plan 文件）
- 用 `/opsx:propose` 一步建档，然后接 `/sdd:plan`

---

## 7. 配置说明

### 7.1 `openspec/config.yaml` 关键字段

| 字段 | 说明 |
|------|------|
| `schema` | 固定为 `spec-driven` |
| `context` | 项目技术栈和约定，会注入到所有 skill 的上下文中 |
| `rules.change_directory` | change 目录命名规则 |
| `rules.proposal` | proposal.md 必须包含的内容 |
| `rules.design` | design.md 必须包含的内容 |
| `rules.specs` | spec 文件格式要求（SHALL/MUST + WHEN/THEN） |
| `rules.tasks` | 纯 OpenSpec 流的 tasks.md 规则 |
| `rules.archive` | 归档规则和 CHANGELOG 格式 |

### 7.2 `.claude/settings.local.json`

项目级权限配置。建议允许常用的只读操作以减少权限弹窗：

```json
{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)"
    ]
  }
}
```

### 7.3 `.codegraph/config.json`

CodeGraph 索引配置，定义哪些文件纳入知识图谱：

| 字段 | 说明 |
|------|------|
| `include` | 索引的文件 glob 模式（默认覆盖 30+ 种语言） |
| `exclude` | 排除的目录/文件模式（node_modules、dist、build 等） |
| `maxFileSize` | 单文件大小上限（默认 1MB） |
| `extractDocstrings` | 是否提取文档注释 |
| `trackCallSites` | 是否追踪调用点（启用调用链分析） |

配置已包含合理的默认值。通常只需将 `include` 中不需要的语言移除或添加项目特有的排除规则。

### 7.4 Superpowers 插件配置

Superpowers 通过 Claude Code 的插件系统自动加载，无需额外配置。需确保版本 >= 5.1.0。

---

## 8. 中途变更策略

开发过程中需求变更是常态。SDD 通过 `/sdd:update` 命令提供三级变更同步机制：

### 8.1 三级影响评估

| 级别 | 触发条件 | 动作 |
|------|---------|------|
| **Patch (小改)** | 现有 capability 内的微调（措辞、参数、样式），不影响已完成任务 | 更新 design spec + 同步 OpenSpec design.md |
| **Extend (扩展)** | 新增 capability 或显著扩展，不需返工已完成任务 | 更新 design spec + 新增 OpenSpec spec + 追加 plan 任务 |
| **Rethink (推翻)** | 架构级变更，已完成任务需返工 | 引导回 `/sdd:think` 重新设计 |

### 8.2 使用方式

```bash
# 描述你的变更，skill 自动评估影响级别
> /sdd:update 需要给批量操作增加一个"全选当前页"的快捷按钮

# skill 输出：
# 影响评估：Patch（在现有 batch-operations capability 内新增 UI 元素）
# → 确认后自动同步 design spec + OpenSpec + 检查 plan
```

### 8.3 各场景处理方式

| 场景 | 推荐方式 |
|------|---------|
| **小调整**（文案、样式） | 直接在 `/sdd:code` 中适配，或 `/sdd:update` 正式记录 |
| **新增能力** | `/sdd:update` (Extend) — 同步更新所有产物 |
| **Plan 遗漏/顺序调整** | `/sdd:update` (Patch) — 检查并修补 plan |
| **推翻设计**（架构级变更） | `/sdd:update` (Rethink) → 引导回 `/sdd:think` |
| **新增独立功能** | 完成当前 change → 新开 `/sdd:think` |

### 8.4 产物同步方向

```
SP Design Spec (权威源)
       │
       ├──→ OpenSpec design.md (单向同步)
       ├──→ OpenSpec specs/ (Extend 时新增)
       └──→ Plan (追加/修改任务)
```

**判断标准**：如果变更导致已完成任务需要返工 → "推翻设计"，走完整重规划。

---

## 9. 常见问题

### Q: SDD 和直接用 Superpowers 有什么区别？

Superpowers 本身会自动级联（brainstorming → writing-plans → executing → finishing）。SDD 在每个环节设置了 HARD-GATE，让用户掌控节奏，同时用 OpenSpec 做持久化追溯。

### Q: 我必须走完五步吗？

不必。可以在任何阶段停下，也可以跳步。每步的入/出条件有明确定义，只要满足入条件即可执行。

### Q: design spec 和 OpenSpec design.md 有什么区别？

- `docs/superpowers/specs/*-design.md` 是 brainstorming 的运行时产出（临时文件）
- `openspec/changes/<name>/design.md` 是持久化的技术方案（归入 OpenSpec 体系）
- `/sdd:spec` 负责将前者转换为后者

### Q: 为什么不让 skill 自动 git commit？

设计决策。git 操作有不可逆风险（force push、错误的 commit message），由用户自行控制更安全，也让用户可以在 commit 前做最终审查。

### Q: 纯 OpenSpec 路径(/opsx:*) 什么时候用？

当你不需要 Superpowers 的重度设计/TDD 流程时。比如：小 bug fix、已有明确方案的快速变更、只想记录需求但不需要 AI 设计。

### Q: 如何定制为其他技术栈？

1. 修改 `openspec/config.yaml` 的 `context` 段
2. 修改 `.codegraph/config.json` 的 `include` 字段，仅保留项目使用的语言
3. 如有项目特有的开发规范 skill，放入 `.claude/skills/` 目录
4. 其余 SDD/Superpowers 逻辑无需修改

### Q: CodeGraph 是必须的吗？

不是。CodeGraph 是推荐组件，提供更快速精准的代码上下文构建。如果未配置或索引不可用，SDD 流程会自动降级为 Glob/Grep 模式继续工作。主要区别：

- **有 CodeGraph**：`/sdd:think` 通过 `codegraph_context` 一次调用获得相关文件、符号和调用链
- **无 CodeGraph**：降级为关键词 Glob/Grep 搜索，结果可能不够精准

### Q: CodeGraph 索引需要手动更新吗？

不需要。CodeGraph MCP Server 内置 file watcher，文件保存后 ~500ms 自动增量同步。如果索引出现 pending changes，sdd-think 会自动触发 `codegraph sync`。

---