---
description: |
  引导规格驱动开发 (SDD) 工作流程，在实现前规划变更。
  使用时机：建立规格、提案、规划功能、使用 OpenSpec 或类似工具。
  关键字：spec, specification, SDD, proposal, openspec, spec-kit, design doc, 规格, 提案, 设计文件。
source: ../../../../skills/spec-driven-dev/guide.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-03-23
status: current
---

# 规格驱动开发指南

> **语言**: [English](../../../../skills/spec-driven-dev/guide.md) | 简体中文

**版本**: 1.2.0
**最后更新**: 2026-03-23
**适用范围**: Claude Code Skills

---

## 目的

本技能引导您完成规格驱动开发 (SDD)，确保变更在实现前经过规划、文档化和核准。

## 会话启动协议

每次会话开始时：

1. **检查进行中的规格**：搜索 `docs/specs/`、`specs/`、`openspec/changes/` 或 `.specify/` 中的进行中工作
2. **若发现进行中的规格** → 通知用户并提供继续的选项
3. 在开始新工作前**检阅上下文**

## 快速参考

### SDD 工作流程

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Discuss    │───▶│   Proposal   │───▶│    Review    │───▶│Implementation│
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
                                                                   │
                                                                   ▼
                                        ┌──────────────┐    ┌──────────────┐
                                        │   Archive    │◀───│ Verification │
                                        └──────────────┘    └──────────────┘
```

### 工作流程阶段

| 阶段 | 说明 | 产出 |
|------|------|------|
| **Discuss** | 捕捉模糊地带、锁定范围、建立必读清单 | 范围定义、规范参考 |
| **Proposal** | 定义要变更什么以及为什么 | `proposal.md` |
| **Review** | 利害关系人核准 | 核准记录 |
| **Implementation** | 执行已核准的规格 | 代码、测试、文档 |
| **Verification** | 确认实现符合规格（最多 3 次迭代） | 测试结果、追溯矩阵 |
| **Archive** | 关闭并归档 | 带链接的已归档规格 |

### 工作流程强制闸门

**重要**：执行任何工作流程阶段前，必须检查先决条件。

| 阶段 | 先决条件 | 失败时 |
|------|---------|--------|
| Proposal | Discuss 完成、范围锁定 | → 先完成 Discuss 阶段 |
| Implementation | 规格状态 = Approved | → 先取得核准 |
| Verification | 所有 AC 都有代码 + 测试 | → 完成实现 |
| Commit (feat/fix) | 检查进行中的规格 | → 建议规格参考 (Refs: SPEC-XXX) |
| Archive | 所有任务完成、已验证 | → 完成剩余任务 |

### 核心原则

| 原则 | 说明 |
|------|------|
| **先评估** | 建立规格前评估范围和同步需求 |
| **规格优先** | 没有已核准的规格不进行功能性变更 |
| **工具优先** | 有 SDD 工具时优先使用其命令 |
| **方法论 > 工具** | SDD 可搭配任何工具或手动流程 |
| **双向同步** | 变更传播到所有相关产物 |
| **简单优先** | 选择最简单的可行方案 |

### 规格前评估

建立规格前，回答以下问题：

| 问题 | 选项 | 结果 |
|------|------|------|
| **范围？** | 项目特定 / 通用 | 决定是否需要核心规范 |
| **交互式？** | 是 / 否 | 决定是否需要技能 |
| **用户触发？** | 是 / 否 | 决定是否需要命令 |

### 建立规格前

- 总是先检查项目中是否已存在类似的规格
- 建立新规格前先搜索现有规格目录
- 优先修改现有规格而非建立重复的
- 若需求不明确，先提出 1-2 个厘清问题

### 「规格优先」的例外

- 紧急修复（立即恢复服务，之后补文档）
- 琐碎变更（错字、注释、格式）
- 依赖套件更新（不破坏兼容性）
- 配置变更

## 详细阶段指引

### Discuss 阶段

Discuss 阶段确保在编写规格前解决所有歧义。

#### 1. 建立治理原则

预先定义项目惯例、约束和不可妥协的事项：

- 项目的核心架构决策是什么？
- 不可妥协的约束是什么（性能、安全、兼容性）？
- 记录在 `project.md`、`CONTRIBUTING.md` 或等效文件中

#### 2. 结构化厘清

列出所有模糊点作为明确问题，逐一解决后再继续：

```markdown
## 厘清记录

| # | 问题 | 选项 | 决定 | 理由 |
|---|------|------|------|------|
| 1 | 认证方式？ | OAuth2 / JWT / Session | OAuth2 | 业界标准，支持 SSO |
| 2 | Token 存储？ | Cookie / LocalStorage | HttpOnly Cookie | XSS 防护 |
```

#### 3. 锁定范围

- 定义什么在范围内、什么在范围外
- 识别可能受影响的相关规格
- 建立必读的文件/规格清单

### Implementation 阶段

实现时遵循结构化方法：

1. **仔细阅读提案/规格** — 理解所有需求和 AC
2. **建立任务清单** — 分解为循序任务（在 `tasks.md` 或规格内）
3. **依序实现任务** — 按顺序完成每个任务
4. **完成后更新清单** — 标记任务为已完成
5. **不要跳到下一阶段** — 直到所有任务完成

### 需求用语

在规格中使用精确语言：

| 关键字 | 含义 | 用法 |
|--------|------|------|
| **SHALL/MUST** | 强制需求 | 「系统 SHALL 验证输入」 |
| **SHOULD** | 建议做法 | 「API SHOULD 在 200ms 内响应」 |
| **MAY** | 可选功能 | 「UI MAY 显示加载动画」 |

避免模糊用语：「should try」、「might need」、「could possibly」

## 简单优先

### 默认原则

- 每次变更默认少于 100 行新代码
- 单一文件实现直到证明不足
- 没有明确理由不引入框架
- 选择无聊但经过验证的模式

### 复杂度触发条件

只有在具体证据下才增加复杂度：

| 触发条件 | 需要的证据 |
|---------|-----------|
| 性能优化 | 分析数据显示瓶颈 |
| 抽象层 | 3+ 个具体使用案例需要 |
| 外部依赖 | 相较内建方案的明确理由 |
| 多服务拆分 | 规模需求（>1000 用户、>100MB 数据） |

## 命名规范

### 规格 ID

- 格式：`SPEC-NNN`（例如 `SPEC-001`、`SPEC-042`）
- 在项目内循序编号

### 变更 ID

- 格式：kebab-case，动词开头
- 前缀：`add-`、`update-`、`remove-`、`refactor-`
- 范例：`add-two-factor-auth`、`update-payment-flow`、`remove-legacy-api`

### 功能名称

- 格式：动词-名词（例如 `user-auth`、`payment-capture`）
- 每个功能单一目的
- 10 分钟可理解性规则：若需要更久才能理解，就拆分
- 描述需要「而且」时就拆分

## 提案模板

```markdown
# [SPEC-ID] 功能标题

## 摘要
简短描述提案变更。

## 动机
为什么需要这个变更？解决什么问题？

## 详细设计
技术方法、受影响的组件、数据流。

## 验收条件
- [ ] 条件 1
- [ ] 条件 2

## 依赖性
列出对其他规格或外部系统的依赖。

## 风险
潜在风险和缓解策略。
```

## 详细指南

完整标准请参阅：
- [规格驱动开发标准](../../../../core/spec-driven-development.md)

### AI 优化格式（Token 效率）

AI 助手可使用 YAML 格式文件以减少 token 用量：
- 基本标准：`ai/standards/spec-driven-development.ai.yaml`

## 与其他标准的整合

### 与 Commit 讯息

在 commit 讯息中参照规格 ID：

```
feat(auth): 实现登录功能

实现 SPEC-001 使用 OAuth2 支持的登录功能。

Refs: SPEC-001
```

### 与提交规范

为规格提交代码前：

- [ ] 规格已核准
- [ ] 实现符合规格
- [ ] 测试涵盖验收条件
- [ ] PR 中参照规格 ID

### 与代码审查

审查者应验证：

- [ ] 变更符合已核准的规格
- [ ] 没有超出规格的范围蔓延
- [ ] 规格的验收条件已满足

## 常见 SDD 工具

| 工具 | 说明 | 主要命令 |
|------|------|---------|
| **OpenSpec** | 规格管理 CLI | `openspec list`、`openspec show`、`openspec validate`、`openspec archive` |
| **Spec Kit** | 斜线命令驱动的 SDD | `specify init`、`/specify`、`/clarify`、`/plan`、`/tasks`、`/implement` |
| **手动** | 无工具，基于文件 | 手动建立 `specs/SPEC-XXX.md` |

> **注意**：当项目中检测到 SDD 工具时，优先使用其原生命令而非手动编辑文件，以确保一致性和可追溯性。

## 同步验证

完成规格后，验证同步：

### 同步清单

```markdown
## 同步状态

### 范围：[通用|项目|工具]

- [ ] 核心规范：[已建立|已更新|不适用]
- [ ] 技能：[已建立|已更新|不适用]
- [ ] 命令：[已建立|已更新|不适用]
- [ ] 翻译：[已同步|待处理|不适用]
```

### 同步矩阵

| 变更来源 | 同步至 |
|---------|--------|
| 核心规范 | → 技能、命令、翻译 |
| 技能 | → 核心规范、命令、翻译 |
| 命令 | → 技能、翻译 |

## 最佳实践

### 应该做的

- 建立规格前评估范围
- 建立新规格前检查是否已存在
- 保持规格聚焦且原子化（一个规格一个变更）
- 包含使用 Given/When/Then 的明确验收条件
- 使用 SHALL/MUST 表达强制需求
- 将规格链接到实现 PR
- 完成后归档规格
- 关闭前验证同步状态

### 不应该做的

- 规格核准前就开始写代码
- 跳过范围评估或 Discuss 阶段
- 实现期间修改范围而不更新规格
- 让规格处于悬而未决状态（一定要关闭或归档）
- 跳过验证步骤
- 忘记同步相关产物
- 没有具体证据就增加复杂度

---

## 配置检测

本技能支持项目特定的配置。

### 检测顺序

1. 检查工作区中的 SDD 工具：
   - `openspec/` 目录 → 检测到 OpenSpec
   - `.specify/` 目录 → 检测到 Spec Kit
   - `specs/` 或 `docs/specs/` → 手动基于文件的工作流程
2. 检查 `CONTRIBUTING.md` 中的规格工作流程文档
3. 若未找到，**默认使用手动基于文件的工作流程**

### 首次设置

若未找到配置：

1. 询问用户：「此项目尚未配置 SDD。是否要设置规格目录？」
2. 建议记录在 `CONTRIBUTING.md`：

```markdown
## 规格驱动开发

我们对所有非琐碎的变更使用规格驱动开发。

### 流程
1. 在 `specs/` 目录建立提案
2. 取得团队负责人核准
3. 实现并在 PR 中参照规格
4. 合并后归档规格

### 规格模板
请参阅 `specs/TEMPLATE.md`
```

---

## 相关标准

- [规格驱动开发标准](../../../../core/spec-driven-development.md)
- [Commit 讯息指南](../../../../core/commit-message-guide.md)
- [代码审查清单](../../../../core/code-review-checklist.md)

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.2.0 | 2026-03-23 | 新增：会话启动协议、工作流程强制闸门、Discuss 阶段（治理原则 + 厘清）、简单优先、命名规范、Implementation 阶段强化、需求用语、搜索指引、更新常见 SDD 工具 |
| 1.1.0 | 2026-01-26 | 新增：规格前评估、同步验证、同步矩阵、强化最佳实践 |
| 1.0.0 | 2025-12-30 | 初始版本 |

---

## 授权

本技能以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权释出。

**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
