dev-spec

开发需求规格化

目标

当用户开始一个新功能的开发时，收集需求描述、对接文档、API 文档、本地文件和原型图等材料，将非结构化信息转化为可开发、可测试、可追踪的 spec 文档，输出到项目 docs/specs/ 目录。

使用场景

当用户说出类似需求时触发：

• "为 xxx 功能写需求文档"
• "写一个需求文档"
• "讨论一下新功能"
• "输出 spec"
• "整理需求"
• "根据这份 API 文档整理开发需求"
• "结合这个 PDF/Word/原型图写 spec"
• "把这些对接材料整理成可开发的步骤"

前置条件

• 项目根目录存在 .dev-flow.yml（可选，不存在时使用默认配置）
• 如果存在 .dev-flow.yml，读取 spec.output-dir、spec.naming、spec.template、spec.required-sections、spec.materials
• 不读取或输出明文密钥、token、密码、证书私钥和数据库连接串；材料中出现敏感值时必须脱敏

执行流程

1. 读取项目根目录的 .dev-flow.yml（如果存在），获取 spec 配置。

2. 读取项目 README、现有 spec 目录和相关代码入口，建立项目上下文。

3. 建立材料清单（优先级：product handoff 已签字材料 > 用户临时描述 > 通用文档）：

   • 先查 engagement 工作区根是否有 .opc-sw-flow-state.json 的 handoff.* 块（由 opc-sw-flow 编排传入）；有则按「材料输入规范 → product handoff 材料」消费三类已签字冻结材料，其可信度高于口头描述。
   • 用户直接描述的需求。
   • 公网 HTTP/HTTPS 文档地址。
   • 本地 docx、pdf、md、txt、表格或压缩包内的需求文档。
   • 产品原型图、截图、流程图。
   • 第三方 API 文档、联调说明、mock 示例。

4. 对每个材料生成 evidence note：

   • source_id、类型、路径或 URL、读取时间、可信度、敏感信息处理状态。
   • 与需求相关的关键事实、原文位置或截图引用。
   • 不确定点和需要用户确认的问题。

5. 进入引导式澄清： a. "这次目标用户和业务目标是什么？"（如果材料已说明则跳过） b. "本次新增/改造的功能边界是什么？" c. "上游 API、原型或文档中哪些点必须严格遵循？" d. "有哪些技术、时间、权限、联调或数据约束？" e. "验收标准是什么？怎样算做完了？"

6. 判断需求复杂度：

   • S：单点修改，通常 1 个开发步骤。
   • M：1-3 个业务步骤，建议按业务闭环拆分。
   • L：跨业务域、跨系统或高风险对接，必须拆步骤并标注风险。
   • XL：大型改造，V1 只生成计划；worktree 或多分支实施留到 V2。

7. 根据 spec.template 选择模板生成 spec，并输出推荐实施步骤。

8. 输出到 {spec.output-dir}/{spec.naming} 路径。

   • 默认：docs/specs/YYYYMMDD-{feature}.md

9. 确定 feature slug 后，先调 dev-lifecycle 的解析脚本建立活动状态文件并指向该 feature（per-feature 模式下生成 .dev-flow/states/<feature>.json + 写指针 .dev-flow/active）：

   python3 skills/dev/dev-lifecycle/scripts/resolve-active-state.py --config .dev-flow.yml set <feature>
   

   再把 spec 文件路径、功能 slug、材料清单、复杂度和实施步骤写入解析出的活动状态文件（resolve 子命令输出的 state-path，供 dev-lifecycle/git-flow 读取）。state.storage: single 时该脚本回退到单一 .dev-flow-state.json，行为不变。

材料输入规范

公网 HTTP/HTTPS 文档

• 记录 URL、读取时间和标题。
• 如果页面会变化，在 spec 中写明 retrieved-at。
• 如果需要登录或访问失败，要求用户提供导出的本地文件或可访问副本。
• 不把含凭据的 URL 原样写入 spec；query 中疑似 token 的值必须脱敏。