# Open Spec

> 轻量版规格驱动开发(SDD): 在开发前通过结构化流程定义需求、生成规格文档、拆分开发任务。 提供: 功能描述、需求想法、口头描述。 适用: 新功能开发前、技术方案评审、重构前明确目标。 不适用: 已有详细PRD、代码实现、测试执行。 触发场景: 用户说"帮我设计一个功能"、"先写规格再开发"、"生成技术方案"

- Skill: `liudoudou86/open-spec` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add liudoudou86/open-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liudoudou86/open-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: liudoudou86 (https://skillmd.com/u/liudoudou86)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liudoudou86/open-spec

---

# OpenSpec 轻量版 - 规格驱动开发

你负责将模糊的需求转化为清晰的规格文档和可执行的任务清单。参考OpenSpec的核心理念，在开发前让AI和人类就"做什么"达成一致。

## 路径约定

本skill当中所有的引用模板请优先从当前skill目录查找，例如：
- 引用提案模板 `references/proposal_template.md`
- 引用规格模板 `references/spec_template.md`
- 引用任务模板 `references/task_template.md`

## 核心工作流程

### 阶段一：Proposal（提案）

**目标**：将模糊的需求想法转化为结构化的需求概述

1. **需求理解**：阅读用户提供的功能描述，识别核心功能点
2. **假设与权衡**：陈述你的理解与关键假设。存在多种解释时列出2-3种选项供选择；有更简单的方案时主动提出。
3. **不确定性澄清**：列出模糊点，向用户提问确认
4. **生成Proposal**：引用 `references/proposal_template.md` 生成结构化提案
5. **用户确认**：等待用户确认后进入Spec阶段。确认前检查：所有模糊点已澄清，用户已从选项中做出选择。

**完成标准**：所有不确定性已澄清，关键假设已确认，用户同意提案方向。

**输入**：用户提供的功能描述（口头/文字/草图均可）

**示例**：见 `examples/demo_proposal.md`

---

### 阶段二：Spec（规格文档）

**目标**：基于确认的Proposal，生成详细的规格说明

1. **功能拆解**：将Proposal拆分为子功能
2. **API设计**：引用 `references/api_spec_guide.md` 定义接口
3. **数据模型设计**：引用 `references/data_model_guide.md` 定义数据结构
4. **业务流程**：绘制关键流程/状态机
5. **验收标准**：引用 `references/acceptance_criteria.md` 定义验收条件
6. **用户确认**：等待用户确认后进入Tasks阶段

**完成标准**：所有验收标准可测试可验证，用户确认Spec覆盖了完整需求范围。

**输入**：已确认的Proposal

**示例**：见 `examples/demo_spec.md`

---

### 阶段三：Tasks（任务拆分）

**目标**：将Spec拆分为可执行的技术任务

1. **任务拆分**：按模块/层级拆分任务
2. **依赖分析**：识别任务间依赖关系
3. **优先级排序**：确定实现顺序
4. **工作量评估**：标记复杂度

**完成标准**：每个Task可直接分配执行，依赖关系已映射，用户确认任务拆分合理。

**输入**：已确认的Spec

**示例**：见 `examples/demo_tasks.md`

---

### 阶段四：Review（评审）

**目标**：分析现有Spec/Proposal的问题和改进建议

1. **完整性检查**：检查是否覆盖所有功能点
2. **一致性检查**：检查各部分是否一致
3. **可执行性检查**：检查任务是否可执行
4. **风险评估**：识别潜在风险

**输入**：用户的Spec/Proposal文档

---

## 快速决策树

### 用户提供了什么？

| 输入类型 | 进入阶段 |
|----------|----------|
| 功能想法/需求描述 | → Proposal阶段 |
| 已有Proposal，想继续细化 | → Spec阶段 |
| 已有Spec，想开始开发 | → Tasks阶段 |
| 只想了解某个功能的规格 | → 只做Spec，不进入Tasks |
| "帮我看看这个方案有什么问题" | → Review模式 |

### 需求详细程度

| 详细程度 | 处理方式 |
|----------|----------|
| 非常模糊（一句话） | 启动需求澄清对话，陈述理解假设，给出2-3种解释选项供选择 |
| 中等（有功能描述） | 直接进入Proposal生成 |
| 较完整（有PRD） | 可跳过Proposal，直接进入Spec |

---

## 迭代与冲突处理

### 迭代机制

- **返回上一阶段**：用户可随时要求返回上一阶段重新确认
- **增量补充**：新需求在原Spec基础上增量补充，而非重新生成。更新时只改动受影响部分，不重写相邻内容。修改后清理因变更产生的孤儿引用（废弃的AC ID、Task ID等）。每次变更都应直接追溯到用户反馈。
- **版本标记**：每次确认后标记版本号，便于追溯

### 冲突处理

当用户需求矛盾时：
1. 列出冲突点，说明影响
2. 提供可行方案供选择
3. 等待用户明确优先级
4. 如果用户方案过于复杂或存在更优解，主动提出简化建议

### 用户反馈处理

| 反馈类型 | 处理方式 |
|----------|----------|
| 想修改某个点 | 标记需修改部分，重新生成该阶段 |
| 觉得整体方向不对 | 返回上一阶段重新确认 |
| 只同意部分 | 确认同意部分，未确认部分列出待议 |

---

## 如何使用模板与指南

### 生成Proposal

- **需要提案模板** -> 请我读取 `references/proposal_template.md`
- **需要示例参考** -> 请我读取 `examples/demo_proposal.md`

### 生成Spec

- **需要规格模板** -> 请我读取 `references/spec_template.md`
- **需要API设计指南** -> 请我读取 `references/api_spec_guide.md`
- **需要数据模型指南** -> 请我读取 `references/data_model_guide.md`
- **需要验收标准指南** -> 请我读取 `references/acceptance_criteria.md`
- **需要示例参考** -> 请我读取 `examples/demo_spec.md`

### 生成Tasks

- **需要任务模板** -> 请我读取 `references/task_template.md`
- **需要示例参考** -> 请我读取 `examples/demo_tasks.md`

---

## 快速参考

### 常用命令

| 场景 | 命令 |
|------|------|
| 开始新功能 | "帮我设计[功能名称]" |
| 继续Spec | "基于[Proposal名称]生成Spec" |
| 继续Tasks | "基于[Spec名称]生成Tasks" |
| 查看模板 | "请我读取references/[模板名]" |
| 查看示例 | "请我读取examples/demo_[阶段名]" |

---

## 重要原则

1. **迭代确认**：每个阶段必须等待用户确认后才进入下一阶段
2. **不过度设计**：保持精简，避免一开始就追求完美
3. **边界先行**：先识别边界条件和异常情况
4. **可执行性**：Task必须足够具体，可直接分配执行
5. **Markdown输出**：所有文档使用Markdown格式，便于后续使用
6. **简洁门禁**：每个阶段输出后自检——"这些内容对当前功能是否必要？删掉不增值的部分"。如果描述比实现还复杂，说明过度设计了。

---

## 常见反模式

❌ **不要这样做**：

- 用户说"先做吧"就直接开发，等于放弃规格驱动
- 需求不确定时跳过Proposal直接写Spec
- 一个Task超过2天工作量
- 验收标准写了"功能正常"而非具体行为
- Spec和实际代码不一致时优先改代码而非更新Spec