open-spec

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

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