传统流程 vs SDD 流程

核心价值

2.1 安装工具链

# 1. 安装 Claude Code（如未安装）
npm install -g @anthropic-ai/claude-code

# 2. 初始化 OpenSpec（在项目根目录执行）
npx openspec init

2.2 初始化后的目录结构

your-project/
├── openspec/                    # OpenSpec 工作目录
│   ├── config.yaml              # 项目配置（schema、context、rules）
│   ├── changes/                 # 活跃变更目录
│   │   └── archive/             # 已归档变更
│   └── specs/                   # 基线规格（归档时同步）
├── CLAUDE.md                    # Claude Code 项目级指令（关键！）
└── .claude/
    ├── CLAUDE.md                # 可选的额外指令
    └── rules/                   # 规则文件目录
        └── *.md                 # 各种规则

2.3 配置 config.yaml

根据你的项目技术栈和架构定制：

schema: spec-driven

context: |
  语言要求：所有 artifact 必须使用中文撰写。
  项目：<你的项目名>
  技术栈：<你的技术栈，如 React + TypeScript + Node.js>
  架构：<你的架构模式，如 组件 → Hooks → API → 后端>

rules:
  proposal:
    - 使用中文撰写
    - "Why" 部分必须说明业务背景和动机
  design:
    - 使用中文撰写
    - 必须说明分层归属
  specs:
    - 使用中文撰写
    - 接口规格必须包含：URL、Method、请求体、响应体
  tasks:
    - 使用中文撰写
    - 每个任务必须有明确的验收标准
    - 任务粒度控制在 30 分钟以内

2.4 配置 CLAUDE.md（项目级指令）

Claude Code 读取指令的优先级顺序（源码分析得出）：

1. /etc/claude-code/CLAUDE.md      — 全局托管指令（所有用户）
2. ~/.claude/CLAUDE.md              — 用户级私有指令（所有项目）
3. 项目根/CLAUDE.md                 — 项目级指令（提交到仓库）
   项目根/.claude/CLAUDE.md         — 项目级指令（提交到仓库）
   项目根/.claude/rules/*.md        — 项目规则文件
4. 项目根/CLAUDE.local.md           — 本地私有指令（不提交）

越靠后的文件优先级越高。建议在 CLAUDE.md 中写入：

# 项目说明
- 这是 XXX 项目，使用 XXX 技术栈
- 架构模式：XXX

# 开发规范
- 代码风格：遵循 ESLint / Prettier 配置
- 提交规范：conventional commits

# SDD 工作流
- 本项目使用 OpenSpec 进行规格驱动开发
- 所有功能变更必须通过 /opsx:propose 发起
- 使用 /opsx:apply 实现，/opsx:archive 归档

proposal (ready)              ← 第一个创建，无依赖
    ↓ unlocks
design (blocked → ready)      specs (blocked → ready)    ← 依赖 proposal，可并行
    ↓                            ↓
    └──────── tasks (blocked → ready) ────────┘           ← 依赖 design + specs

各 Artifact 详解

Artifact	内容	关键要素
Proposal	变更提案	Why（动机）、What Changes（范围）、Capabilities（能力点）、Impact（影响）
Design	技术设计	分层归属、架构决策、备选方案对比
Specs	详细规格	Requirements（SHALL/MUST）、Scenarios（WHEN/THEN）、可直接转测试用例
Tasks	实施任务	30 分钟粒度、checkbox 格式、按依赖顺序排列

explore（可选）→ propose → apply → archive
                    ↑                  ↓
                    └──────────────────┘   （下一轮迭代）

每个阶段对应的命令

阶段	Claude Code 命令	做什么
探索（可选）	/opsx:explore	调研代码现状，适合对代码库不熟悉时使用
提案	/opsx:propose	描述需求 → Claude 自动生成全套 artifact
实现	/opsx:apply	Claude 逐个执行 task，自动写代码
归档	/opsx:archive	归档变更，specs 同步为基线

OpenSpec CLI 命令速查

操作	命令
初始化项目	npx openspec init
新建变更	npx openspec new change "<名称>"
查看依赖状态	npx openspec status "<名称>"
查看 artifact 详情	npx openspec show "<名称>" --json
归档变更	npx openspec archive "<名称>"

操作步骤

你：/opsx:propose
Claude：What change do you want to work on?
你：梳理当前项目 XXX 模块的基线能力，包括已有的 API、组件、数据模型

Claude 会自动：

1. 创建变更目录 openspec/changes/baseline-xxx/
2. 启动后台 Agent 并行探索代码（前端、后端、数据层）
3. 按依赖顺序生成 proposal → design → specs → tasks
4. 输出完成摘要

完成后执行 /opsx:archive 归档为基线，后续迭代可引用。

示例：新增删除按钮

第一步：提案

你：/opsx:propose 在 XXX 页面的操作列中新增删除按钮，使用逻辑删除

Claude 会自动调研代码，发现后端 API 已存在、前端封装已就绪、只缺按钮，然后生成全套 artifact。

第二步：实现

你：/opsx:apply

# Claude 逐个执行 task：
Working on task 1/4: 添加组件导入       ✓
Working on task 2/4: 添加 API 导入      ✓
Working on task 3/4: 在操作列添加按钮    ✓
Working on task 4/4: 代码验证           ✓

Implementation Complete
Change: xxx-delete-button  Progress: 4/4 tasks complete

第三步：归档

你：/opsx:archive
→ 选择「同步并归档」
→ Specs 同步到 openspec/specs/ 作为基线

Archive Complete
Archived to: openspec/changes/archive/2026-04-08-xxx-delete-button/
Specs: Synced to openspec/specs/xxx-delete/spec.md

示例：新增创建功能（复用已有组件）

你：/opsx:propose 在 XXX 模块添加新增功能，需要复用已有的编辑弹窗组件

Claude 调研后会做出设计决策（记录在 design.md）：

• 复用已有组件 vs 新建组件 → 选择复用，避免代码冗余
• 新增 mode prop 区分创建/编辑模式

apply 阶段：按模块分组执行

# apply 阶段生成更多 task（如 12 个），按模块分组：
组件改造 (6 tasks):
  1.1 新增 mode / defaultTargetType props
  1.2 import createAPI
  1.3 useEffect 支持创建模式
  1.4 Modal title 区分「新增」/「编辑」
  1.5 表单字段条件渲染
  1.6 handleOk 区分 create/update 调用

页面集成 (4 tasks):
  2.1 import PlusOutlined
  2.2 添加 createVisible state
  2.3 筛选区域添加「新增」按钮
  2.4 渲染创建模式弹窗

验证 (2 tasks):
  3.1 创建模式代码验证通过
  3.2 编辑模式后向兼容验证通过

对不熟悉的模块，先用 explore 调研

你：/opsx:explore 调研 XXX 模块的实现细节，重点关注数据流和状态管理

# Claude 探索后输出调研报告
# 然后再进入标准流程：
你：/opsx:propose ...
你：/opsx:apply
你：/opsx:archive

# 就这一句，剩下的全自动
/sdd 在用户列表页添加批量删除功能

创建 Skill 文件

将以下文件放到项目的 .claude/skills/sdd.md：

---
name: sdd
description: "SDD 规格驱动开发：输入需求，自动完成全流程"
user-invocable: true
argument-hint: "<用自然语言描述需求>"
arguments:
  - requirement
when_to_use: "Use when user says 'sdd', '规格驱动', or wants structured feature development"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - Agent
---

Skill 正文定义了 9 个自动化步骤（详见项目 .claude/skills/sdd.md）：

1. 读取配置 — 加载 config.yaml + 已有基线 specs
2. 调研代码 — Agent 并行探索相关模块
3. 生成 Proposal — Why / What Changes / Capabilities / Impact
4. 生成 Design — 分层归属、架构决策、备选方案
5. 生成 Specs — Requirements (SHALL/MUST) + Scenarios (WHEN/THEN)
6. 生成 Tasks — 30 分钟粒度、按依赖排序
7. 逐个实现 — 按 task 顺序写代码，实时汇报进度
8. 归档 — specs 同步基线、变更归档
9. 总结报告 — 输出完整的 artifact 链路和修改文件清单

对比：手动 vs 一键 Skill

手动三步	一键 Skill
/opsx:propose ... (等待 → review) /opsx:apply (等待 → 验证) /opsx:archive (选择同步)	/sdd 在用户列表页添加批量删除功能 (全自动，最后输出总结报告)
适合需要中途 review 的场景	适合信任 AI 或需求明确的场景

Step 1: 项目初始化（一次性）

• 在项目根目录执行 npx openspec init
• 根据项目技术栈和架构编辑 openspec/config.yaml
• 在 CLAUDE.md 中写入项目说明和 SDD 工作流约定
• 将 openspec/ 和 CLAUDE.md 提交到 Git

Step 2: 基线建立（首次）

• 用 /opsx:propose 对核心模块做基线梳理
• Review 生成的 specs，确认准确性
• 用 /opsx:archive 归档基线
• 提交归档后的 openspec/specs/ 到 Git

Step 3: 日常迭代（每次功能开发）

• /opsx:propose 描述需求
• Review 生成的 proposal、design、specs、tasks
• /opsx:apply 让 Claude 实现
• 手动验证功能（启动项目、测试）
• /opsx:archive 归档并同步基线
• Git commit & push

Step 4: 持续优化

• 根据实际体验调整 config.yaml 中的 rules
• 在 CLAUDE.md 中补充 Claude 经常犯错的规则
• 定期 review openspec/specs/ 确保基线准确

场景判断

场景	是否使用 SDD	原因
新功能开发	推荐	需求→代码全链路可追溯
Bug 修复（明确原因）	不需要	直接修，太轻量不值得
大规模重构	强烈推荐	降低 AI 出错概率，分步可控
探索性原型	不需要	快速试错优先
多人协作功能	推荐	Specs 成为沟通契约

Proposal 写作要点

• Why：1-2 句说清业务动机，不要写技术细节
• What Changes：用 bullet list，具体到模块/文件级别
• Capabilities：每个独立功能点一个 capability，用 kebab-case 命名
• Impact：列出受影响的文件、API、依赖

Specs 写作要点

• 每个 Requirement 使用 ### Requirement: <name> 格式
• 使用 SHALL / MUST 表达强制要求
• 每个 Requirement 至少一个 Scenario（WHEN / THEN 格式）
• 每个 Scenario 可直接转化为测试用例

Tasks 拆分原则

• 每个 task 30 分钟以内可完成
• 使用 checkbox 格式：- [ ] X.Y 任务描述
• 按依赖顺序排列（先改 model，再改 service，最后改 controller/UI）
• 验证任务单独成组，放在最后

第一轮：基线梳理（propose → archive）
  ↓
第二轮：小功能（propose → apply → archive）  ~30min
  ↓
第三轮：中等功能（propose → apply → archive） ~1h
  ↓
第四轮：复杂功能（explore → propose → apply → archive）

归档后的基线管理

归档后 specs 自动同步到 openspec/specs/：

openspec/specs/
├── user-delete/spec.md       # 删除能力基线
├── user-create/spec.md       # 创建能力基线
└── ...

后续迭代中如需修改已有能力：

1. 在 proposal 的 Modified Capabilities 中引用已有 spec 名称
2. 在 delta spec 中使用 ## MODIFIED Requirements 标记变更部分

Skills（自定义斜杠命令）

OpenSpec 的 /opsx:propose、/opsx:apply、/opsx:archive 就是通过 Skills 机制实现的。Skills 是 .md 文件，放在 .claude/skills/ 目录，支持 frontmatter 定义参数。你也可以自定义 skill 封装常用操作。

Agent 子代理机制

类型	用途
general-purpose	通用多步任务
Explore	快速代码库探索（quick / medium / very thorough）
Plan	架构设计和实现规划

SDD 的 propose 阶段大量使用 Agent 并行探索代码库。

Memory 持久记忆

Claude Code 的自动记忆系统（~/.claude/projects/<project>/memory/）跨会话保留用户偏好、项目上下文、外部引用。

前端项目（React / Vue）

schema: spec-driven
context: |
  项目：XXX 管理后台
  技术栈：React 18 + TypeScript + Ant Design + Zustand
  架构：Pages → Components → Hooks → API → Types
rules:
  proposal:
    - 使用中文撰写
    - 说明影响的页面和组件
  specs:
    - 组件规格包含：Props 接口、事件、状态
    - API 规格包含：URL、请求体、响应体
  tasks:
    - 先改 Types，再改 API，再改 Components，最后改 Pages
    - 每个 task 30 分钟以内

后端项目（Go / Java / Python）

schema: spec-driven
context: |
  项目：XXX 微服务
  技术栈：Go 1.23 + Gin + GORM + Wire + PostgreSQL
  架构：Controller → Service → DAO → Model 四层架构
rules:
  proposal:
    - 使用中文撰写
    - 必须说明 API 变更和数据库变更
  design:
    - 必须说明分层归属（Controller/Service/DAO/Model）
  specs:
    - 接口规格：URL、Method、请求体、响应体、错误码
    - 数据模型：表结构、字段类型、约束
  tasks:
    - 先改 Model，再改 DAO，再改 Service，最后改 Controller
    - 数据库迁移单独一个 task

全栈项目

schema: spec-driven
context: |
  项目：XXX 平台
  前端：Next.js 14 + TypeScript + Tailwind
  后端：Node.js + Prisma + PostgreSQL
  架构：前端 Pages → API Routes → Services → Prisma Models
rules:
  proposal:
    - 使用中文撰写
    - 分别说明前端和后端的改动范围
  specs:
    - 前后端接口必须定义 TypeScript 类型
  tasks:
    - 后端先行：Model → Service → API Route
    - 前端跟进：Types → Hooks → Components → Pages
    - 集成验证放最后

# 1. 提案：描述你想做什么
/opsx:propose <用自然语言描述需求>

# 2. 实现：Claude 自动写代码
/opsx:apply

# 3. 归档：保存为基线
/opsx:archive

遇到问题时

情况	怎么做
Claude 生成的 spec 不准确	手动编辑 spec 文件后重新 apply
Task 执行失败	检查错误，手动修复后继续
需要修改已归档的能力	新 propose 中引用已有 spec
对代码不熟悉	先用 /opsx:explore 调研
第一次在项目用 SDD	先做基线梳理（Phase 1）

这套方法的威力