# 规格生成器结构化规范文档生成器通过 6 个连续阶段以及多 CLI 分析和交互式细化生成完整的规范包（产品简介、PRD、架构、史诗）。 **仅生成文档** \- 执行切换到现有工作流程（精简计划、计划、请求计划）。 ## 架构概述第 0 阶段：规范研究（阅读规范/+模板/-强制性先决条件） | 第 1 阶段：发现 -> spec-config.json + discovery-context.json | （包括spec_type选择）阶段 1.5：Req Expansion -> Fine-requirements.json（交互式讨论 + CLI 差距分析） | （-y auto模式：自动展开，跳过交互）第 2 阶段：产品简介 ->product-brief.md +lossary.json（多 CLI 并行分析） | 第 3 阶段：需求 (PRD) -> 需求/ (_index.md + REQ-*.md + NFR-*.md) | （RFC 2119 关键字、数据模型定义）第 4 阶段：架构 -> 架构/（_index.md + ADR-*.md，多 CLI 审查） | （状态机、配置模型、错误处理、可观察性）阶段 5：史诗与故事 -> Epiks/ (_index.md + EPIC-*.md) | 第 6 阶段：准备情况检查 -> readiness-report.md + spec-summary.md | （术语+范围一致性验证） ├── Pass (>=80%)：切换至执行工作流程 ├── 回顾（60-79%）：带有警告的交接 └── 失败（<60%）：阶段 6.5 自动修复（最多 2 次迭代） | 阶段 6.5：自动修复 -> 更新阶段 2-5 文档 | └── 重新运行第6阶段验证 ## 关键设计原则 1. **文档链**：每个阶段都建立在以前的输出之上，创建从想法到可执行故事的可追踪规范链 2. **多视角分析**：CLI工具（Gemini/Codex/Claude）并行提供产品、技术和用户视角 3. **默认交互**：每个阶段都提供用户确认点； `-y` 标志启用全自动模式 4. **可恢复会话**：`spec-config.json` 跟踪已完成的阶段； `-c` 标志从上一个检查点恢复 5. **模板驱动** ：从带有 YAML frontmatter 的标准化模板生成的所有文档 6. **纯文档**：无代码生成或执行 - 干净地切换到现有执行工作流程 7. **规范类型专业化**：模板通过特定领域深度的配置文件适应规范类型（服务/api/库/平台） 8. **迭代质量**：第 6.5 阶段自动修复循环修复了就绪检查中发现的问题（最多 2 次迭代） 9. **术语一致性**：第2阶段生成的glossary.json，注入到所有后续阶段 ** ** ## 强制性先决条件 > **请勿跳过**：在执行任何操作之前，您**必须**完整阅读以下文档。不阅读规范就继续操作将导致输出不符合质量标准。 ### 规范文件（必读）文件|目的|优先级 ---|---|--- [specs/document-standards.md]() |文档格式、frontmatter、命名约定 | **P0 - 执行前必须读取** [specs/quality-gates.md]() |每阶段质量门标准和评分 | **P0 - 执行前必须读取** ### 模板文件（生成前必须读取）文件|目的 ---|--- [templates/product-brief.md]() |产品简介文档模板 [templates/requirements-prd.md]() | PRD文件模板 [templates/architecture-doc.md]() |架构文档模板 [templates/epics-template.md]() |史诗/故事文档模板 ** ** ## 执行流程输入解析： |- 解析 $ARGUMENTS：提取想法/主题、标志（-y、-c、-m） |- 检测模式：新 |继续 |- 如果继续：读取spec-config.json，从第一个不完整的阶段恢复 |- 如果是新的：进入第 1 阶段第一阶段：发现和种子分析 |- 参考：phases/01-discovery.md |- 生成会话 ID：SPEC-{slug}-{YYYY-MM-DD} |- 解析输入（文本或文件引用） |- Gemini CLI 种子分析（问题、用户、领域、维度） |- 代码库探索（有条件，如果检测到项目） |- Spec 类型选择：service|api|library|platform（交互式，-y 默认为服务） |- 用户确认（交互式，-y 跳过） |- 输出：spec-config.json、discovery-context.json（可选）第 1.5 阶段：需求扩展和澄清 |- 参考：phases/01-5-requirement-clarification.md |- CLI 差距分析：完整性评分、缺失维度检测 |- 多轮互动讨论（最多5轮） | |- 第一轮：现状差距分析+扩展建议 | |- N轮：根据用户反馈进行后续细化 |- 用户最终确认要求 |- 自动模式 (-y)：CLI 自动扩展，无需交互 |- 输出：refine-requirements.json 第二阶段：产品简介 |- 参考：phases/02-product-brief.md |- 3 个并行 CLI 分析：产品 (Gemini) + 技术 (Codex) + 用户 (Claude) |- 综合观点：趋同主题+冲突 |- 生成lossary.json（来自产品简介+CLI分析的术语） |- 交互式细化（-y 跳过） |- 输出：product-brief.md（来自模板）、glossary.json 第 3 阶段：要求/PRD |- 参考：phases/03-requirements.md |- Gemini CLI：将目标扩展到功能性+非功能性需求 |- 根据要求生成验收标准 |- RFC 2119 行为约束（必须/应该/可以） |- 核心实体数据模型定义 |- 术语注入以实现术语一致性 |- 用户优先级排序：MoSCoW（交互式，-y 自动分配） |- 输出：requirements/ 目录（_index.md + REQ-*.md + NFR-*.md，来自模板）第四阶段：架构 |- 参考：phases/04-architecture.md |- Gemini CLI：核心组件、技术堆栈、ADR |- 代码库集成映射（有条件） |- 状态机生成（生命周期实体的 ASCII 图） |- 配置模型定义（字段、类型、默认值、约束） |- 错误处理策略（每个组件分类+恢复） |- 可观察性规范（指标、日志、健康检查） |- 规范类型配置文件注入 (templates/profiles/{type}-profile.md) |- 术语注入以实现术语一致性 |- Codex CLI：架构挑战 + 审查 |- 交互式 ADR 决策（-y 自动接受） |- 输出：architecture/ 目录（_index.md + ADR-*.md，来自模板）第五阶段：史诗和故事 |- 参考：phases/05-epics-stories.md |- Gemini CLI：需求分组为 Epics、MVP 子集标记 |- 故事生成：作为...我想要...所以... |- 依赖关系映射（美人鱼） |- 交互式验证（-y 跳过） |- 输出：epics/ 目录（_index.md + EPIC-*.md，来自模板）第 6 阶段：准备情况检查 |- 参考：phases/06-readiness-check.md |- 跨文档验证（完整性、一致性、可追溯性） |- 每个维度的质量评分 |- 术语一致性验证（术语表合规性） |- 范围包含验证（PRD <= 简要范围） |- 输出：readiness-report.md、spec-summary.md |- 移交选项：精简计划、请求计划、计划、问题：新、仅导出、迭代阶段 6.5：自动修复（有条件，当阶段 6 得分 < 60% 时触发） |- 参考：phases/06-5-auto-fix.md |- 解析 readiness-report.md 中的错误/警告项 |- 按发起阶段对问题进行分组 (2-5) |- 通过带有错误上下文的 CLI 重新生成受影响的部分 |- 重新运行第 6 阶段验证 |- 最多 2 次迭代，然后强制切换 |- 输出：更新的第 2-5 阶段文档完整：完整的规格包可供执行阶段 6 → 切换桥（有条件，基于用户选择）： ├─ lite-plan：提取第一个MVP Epic描述→直接文本输入 ├─ plan / req-plan：创建 WFS 会话 + .brainstorming/ 桥接文件 │ ├─guiding-specation.md（从规范输出合成） │ ├─ feature-specs/feature-index.json (Epic → 特征映射) │ └─ feature-specs/F-{num}-{slug}.md（每个 Epic 一个） ├─ 问题：新：为每个 Epic 创建问题 └─ context-search-agent 自动发现 .brainstorming/ → 已填充 context-package.json.brainstorm_artifacts → 行动规划代理消耗：guiding_spec (P1) → feature_index (P2) ## 目录设置 // 会话ID生成 const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-').slice(0, 40); const date = new Date().toISOString().slice(0, 10); const sessionId = `SPEC-${slug}-${date}`; const workDir = `.workflow/.spec/${sessionId}`; Bash(`mkdir -p "${workDir}"`); ## 输出结构 .workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/ ├── spec-config.json # 会话配置+阶段状态 ├── discovery-context.json # 代码库探索结果（可选） ├── Fine-requirements.json # 阶段1.5：讨论后确认需求 ├──lossary.json # 第 2 阶段：跨文档一致性的术语词汇表 ├──product-brief.md # 第二阶段：产品简介 ├── 需求/ # 第三阶段：详细PRD（目录） │ ├── _index.md # 总结、MoSCoW 表、溯源、链接 │ ├── REQ-NNN-{slug}.md # 个别功能需求 │ └── NFR-{type}-NNN-{slug}.md # 个别非功能需求 ├── Architecture/ # 第 4 阶段：架构决策（目录） │ ├── _index.md # 概述、组件、技术堆栈、链接 │ └── ADR-NNN-{slug}.md # 个体架构决策记录 ├── Epiks/ # 第5阶段：史诗/故事分解（目录） │ ├── _index.md # Epic 表、依赖图、MVP 范围 │ └── EPIC-NNN-{slug}.md # 带有故事的个人史诗 ├── readiness-report.md # 第 6 阶段：质量报告 └── spec-summary.md # 第 6 阶段：一页执行摘要 ## 状态管理 **spec-config.json** 作为核心状态文件： { “session_id”：“SPEC-xxx-2026-02-11”， "seed_input": "用户输入文本", “input_type”：“文本”， “时间戳”：“ISO8601”， “模式”：“交互”， “复杂性”：“中等”， “深度”：“标准”， “焦点区域”：[]， "spec_type": "服务", “迭代计数”：0， “迭代历史”：[]， “种子分析”：{ "problem_statement": "...", “目标用户”：[]， “域”：“...”， “约束”：[]， “尺寸”：[] }, “has_codebase”：假， "refined_requirements_file": "refined-requirements.json", “阶段已完成”：[ { "phase": 1, "name": "discovery", "output_file": "spec-config.json", "completed_at": "ISO8601" }, { "phase": 1.5, "name": "requirement-clarification", "output_file": "refined-requirements.json", "discussion_rounds": 2, "completed_at": "ISO8601" }, { "phase": 3, "name": "requirements", "output_dir": "requirements/", "output_index": "requirements/_index.md", "file_count": 8, "completed_at": "ISO8601" } ] } **恢复机制**：“-c|--continue”标志读取“spec-config.json.phasesCompleted”，从第一个不完整的阶段恢复。 ## 核心规则 1. **立即开始** ：第一个操作是 TaskCreate 初始化，然后是阶段 0（规范研究），然后是阶段 1 2. **渐进阶段加载**：仅在该阶段即将执行时读取阶段文档 3. **自动继续** ：所有阶段自主运行；检查任务列表以执行下一个待处理阶段 4. **解析每个输出**：从每个阶段提取所需数据以用于下一阶段上下文 5. **不要停止**：连续 6 阶段管道，直到所有阶段完成或用户退出 6. **尊重 -y 标志** ：自动模式时，跳过所有 AskUserQuestion 调用，使用推荐的默认值 7. **尊重 -c Flag** ：当继续模式时，加载spec-config.json并从检查点恢复 8. **注入词汇表**：从第3阶段开始，将glossary.json术语注入每个CLI提示符中 9. **加载配置文件** ：读取 templates/profiles/{spec_type}-profile.md 并将需求注入到阶段 2-5 提示中 10. **迭代失败**：当阶段 6 得分 < 60% 时，自动触发阶段 6.5（最多 2 次迭代） ## 各阶段参考文件 ### 第一阶段：发现文件|目的|何时使用 ---|---|--- [phases/01-discovery.md]() |种子分析和会话设置 |阶段开始 [templates/profiles/]() |规格类型型材 |规格型号选择 [specs/document-standards.md]() | spec-config.json 的 Frontmatter 格式 |配置生成 ### 阶段 1.5：需求扩展和澄清文件|目的|何时使用 ---|---|--- [phases/01-5-requirement-clarification.md]() |交互式需求讨论工作流程 |阶段开始 [specs/quality-gates.md]() |细化要求的质量标准 |验证 ### 第 2 阶段：产品简介文件|目的|何时使用 ---|---|--- [phases/02-product-brief.md]() |多 CLI 分析编排 |阶段开始 [templates/product-brief.md]() |文档模板|文档生成 [specs/glossary-template.json]() |词汇表架构 |词汇表生成 ### 第 3 阶段：要求文件|目的|何时使用 ---|---|--- [phases/03-requirements.md]() | PRD 生成工作流程 |阶段开始 [templates/requirements-prd.md]() |文档模板|文档生成 ### 第 4 阶段：架构文件|目的|何时使用 ---|---|--- [phases/04-architecture.md]() |架构决策工作流程 |阶段开始 [templates/architecture-doc.md]() |文档模板|文档生成 ### 第 5 阶段：史诗和故事文件|目的|何时使用 ---|---|--- [phases/05-epics-stories.md]() |史诗/故事分解|阶段开始 [templates/epics-template.md]() |文档模板|文档生成 ### 第 6 阶段：准备情况检查文件|目的|何时使用 ---|---|--- [phases/06-readiness-check.md]() |跨文档验证 |阶段开始 [specs/quality-gates.md]() |质量评分标准|验证 ### 阶段 6.5：自动修复文件|目的|何时使用 ---|---|--- [phases/06-5-auto-fix.md]() |自动修复准备问题的工作流程 |当第 6 阶段得分 < 60% 时 [specs/quality-gates.md]() |迭代退出标准 |验证 ### 调试和故障排除问题 |解决方案文档 ---|--- 阶段执行失败 |请参阅相关阶段文档产量未达到预期| [specs/quality-gates.md]() 文档格式问题 | [specs/document-standards.md]() ## 错误处理相|错误 |封锁？ |行动 ---|---|---|--- 第一阶段|空输入|是的 |错误并退出第一阶段| CLI 种子分析失败 |没有 |使用基本解析后备 1.5 阶段 |差距分析 CLI 失败 |没有 |通过基本提示跳至用户问题 1.5 阶段 |用户跳过讨论 |没有 |按原样继续进行 seed_analysis 1.5 阶段 |达到最大回合数 (5) |没有 |强制确认当前状态第二阶段 |单一 CLI 视角失败 |没有 |继续使用可用的观点第二阶段 |所有 CLI 调用均失败 |没有 |从种子分析中生成基本简介第三阶段 | Gemini CLI 失败 |没有 |使用 Codex 后备第四阶段 |架构审核失败 |没有 |跳过审查，继续进行初步分析第五阶段 |故事生成失败 |没有 |生成没有详细故事的史诗第六阶段 |验证 CLI 失败 |没有 |使用可用数据生成部分报告 6.5 阶段 |自动修复 CLI 失败 |没有 |记录失败，继续切换并查看状态 6.5 阶段 |达到最大迭代次数 |没有 |强制切换，报告剩余问题 ### CLI 后备链 Gemini -> Codex -> Claude -> 降级模式（仅限本地分析）

规格生成器

包含技能