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