--- name: spec-driven-dev description: | 文档驱动的软件开发规范工作流。当用户需要以下操作时使用： (1) 创建需求规格书并进行需求澄清 (2) 规划业务模块和详细模块设计 (3) 生成统一规范集合（架构、UI/UX、后端、数据库） (4) 确保跨模块一致性和可追溯性 触发词: "需求规格", "spec-driven", "文档驱动开发", "需求澄清", "模块设计", "规范集合", "create specs", "requirements specification" --- # 文档驱动开发工作流 一种结构化的、文档驱动的企业软件开发方法，确保所有项目产出物的一致性、可追溯性和对齐。 ## 语言规范 **重要：所有产出文档、交互内容均使用中文。** 仅在技术术语、代码示例、配置文件中可使用英文。 --- ## 工作流概览 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 文档驱动开发工作流 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 阶段 1 │ │ 阶段 2 │ │ 阶段 3 │ │ │ │ 需求澄清 │───▶│ 模块规划 │───▶│ 模块设计 │ │ │ │ (逐个交互) │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ └───────────────────┴───────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ 规范集合 │ │ │ │ (并行产出) │ │ │ └────────┬────────┘ │ │ │ │ │ ┌───────────────────┼───────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ 架构规范 │ │ UI/UX规范 │ │ 后端规范 │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ │ │ │ └───────────────────┴───────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ 数据库规范 │ │ │ └─────────────────┘ │ │ │ │ ┌─────────────────┐ │ │ │ 校验与对齐 │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 产出物位置 所有产出物生成在：`docs/specs/{项目名称}/` ``` docs/specs/{项目名称}/ ├── 00-需求规格/ │ └── 需求规格书.md ├── 01-模块规划/ │ └── 模块规划.md ├── 02-模块设计/ │ ├── 模块1-详细设计.md │ ├── 模块2-详细设计.md │ └── 模块N-详细设计.md ├── 03-规范集合/ │ ├── 架构规范.md │ ├── UI-UX规范.md │ ├── 后端开发规范.md │ └── 数据库设计规范.md └── 04-校验报告/ └── 一致性校验报告.md ``` --- ## 阶段 1：需求澄清（交互式） ### 1.1 收集初始上下文 首先从用户提供的需求文档或描述中提取： - 项目名称和描述 - 业务领域 - 目标用户 - 核心功能（高层概览） - 技术偏好（如有） ### 1.2 交互式问题澄清流程 **核心原则：逐个问题交互，而非一次性提出所有问题。** ``` 流程： 1. 根据上下文识别问题类别优先级 2. 选择最重要的第一个问题 3. 提出问题，等待用户回答 4. 记录答案，根据答案可能产生追问 5. 选择下一个问题 6. 重复直到收集足够信息（至少10个问题） 7. 确认是否需要补充 ``` ### 1.3 问题类别与优先级 根据项目类型动态调整问题优先级： | 类别 | 关注点 | 典型优先级 | |------|--------|-----------| | **技术架构** | 架构模式、技术栈、集成、扩展性 | 高 | | **业务逻辑** | 领域规则、工作流、边界情况、用户角色 | 高 | | **安全合规** | 认证、授权、数据保护、合规要求 | 高（医疗/金融必问） | | **性能** | 响应时间、吞吐量、缓存、并发 | 中 | | **用户体验** | 无障碍、响应式、用户流程、错误处理 | 中 | | **运维** | 部署、监控、日志、备份 | 中 | ### 1.4 单个问题的交互格式 每次只提出**一个问题**，格式如下： ```markdown **问题 {N}/{总数}：{问题标题}** {问题描述，说明为什么需要澄清这个问题} 请选择： - A) {选项A} - {简短说明} - B) {选项B} - {简短说明} - C) {选项C} - {简短说明} - D) {选项D} - {简短说明} - E) 其他（请说明） ``` ### 1.5 交互示例 ``` 助手：我已阅读您的需求文档，现在开始逐个澄清关键问题。 **问题 1/12：后端技术栈选择** 根据文档描述，这是一个医疗信息化系统，需要与现有HIS系统集成。 请选择后端技术栈： - A) Java + Spring Boot - 企业级首选，生态完善 - B) Node.js + NestJS - 与前端技术栈统一 - C) Python + FastAPI - 快速开发，AI扩展性好 - D) InterSystems IRIS 2019 - 医疗信息化领域成熟的技术 - E) 其他（请说明） 请选择或输入您的答案： 用户：A 助手：收到，选择 **A) Java + Spring Boot**。 **问题 2/12：数据库选型** 考虑到医疗数据的结构化特点和与HIS系统的集成需求： - A) InterSystems IRIS - 多模型数据库（关系型、对象、文档） - B) MySQL - 成熟稳定，运维成本低 - C) SQL Server - 与现有HIS保持一致 - D) Oracle - 企业级，高可用 - E) 其他（请说明） 请选择或输入您的答案： 用户：C，因为现有HIS用的是SQL Server 助手：收到，选择 **C) SQL Server**，理由是保持与现有HIS系统一致。 **问题 3/12：与HIS系统的集成方式**... ``` ### 1.6 追问机制 根据用户回答，可能触发追问： ``` 用户：选择 D) 其他：混合云部署 助手：收到，选择**混合云部署**。 追问：混合云部署需要确认： - 敏感数据（患者信息）存储在本地还是云端？ - 哪些模块需要部署在云端？ 请选择： - A) 全部本地部署，云端仅做备份 - B) 核心数据本地，非敏感服务云端 - C) 主系统云端，本地只留数据同步节点 - D) 其他（请说明） ``` ### 1.7 问题完成确认 收集完所有问题后： ```markdown ## 需求澄清完成 已收集以下关键决策： | 序号 | 问题 | 您的选择 | |------|------|----------| | 1 | 后端技术栈 | Java + Spring Boot | | 2 | 数据库 | SQL Server | | ... | ... | ... | **确认点：** 以上信息是否完整？是否需要补充或修改？ - 回复"确认"继续生成需求规格书 - 回复需要修改的问题编号进行修改 - 回复"补充"添加更多信息 ``` ### 1.8 生成需求规格书 用户确认后，使用 [references/templates/requirement-spec-template.md](references/templates/requirement-spec-template.md) 生成需求规格书。 **检查点：** 展示需求规格书，等待用户确认后进入下一阶段。 --- ## 阶段 2：模块规划 ### 2.1 分解业务模块 基于需求，识别业务模块： - 每个模块应有清晰的边界 - 定义模块依赖关系 - 识别共享组件/服务 ### 2.2 模块规划文档 使用 [references/templates/module-planning-template.md](references/templates/module-planning-template.md) 生成。 包含： - 模块列表及描述 - 依赖关系图（Mermaid图） - 优先级/复杂度矩阵 - 预估复杂度 **检查点：** 与用户确认模块分解方案。 --- ## 阶段 3：模块详细设计 ### 3.1 设计每个模块 为每个模块使用 [references/templates/module-design-template.md](references/templates/module-design-template.md) 创建详细设计。 每个模块设计包含： - 功能需求映射 - API契约（端点、请求/响应模式） - 组件架构 - 状态管理 - 错误处理策略 ### 3.2 模块设计检查清单 每个模块设计需确认： - [ ] 阶段1的所有需求都已覆盖 - [ ] API契约已明确定义 - [ ] 错误场景已覆盖 - [ ] 安全考虑已文档化 - [ ] 性能需求已回应 --- ## 阶段 4：规范集合（并行生成） 并行生成四个规范文档： ### 4.1 架构规范 模板：[references/templates/architecture-spec-template.md](references/templates/architecture-spec-template.md) 内容： - 系统架构概览 - 技术栈决策 - 部署架构 - 集成模式 - 扩展性策略 ### 4.2 UI/UX规范 模板：[references/templates/ui-ux-spec-template.md](references/templates/ui-ux-spec-template.md) 内容： - 设计系统（颜色、字体、间距） - 组件库标准 - 无障碍要求（WCAG级别） - 响应式断点 - 交互模式 - 页面布局和线框图 ### 4.3 后端开发规范 模板：[references/templates/backend-spec-template.md](references/templates/backend-spec-template.md) 内容： - API设计标准（REST/GraphQL/gRPC） - 错误响应格式 - 认证/授权流程 - 限流策略 - 日志和监控 - 代码结构和命名规范 ### 4.4 数据库规范 模板：[references/templates/database-spec-template.md](references/templates/database-spec-template.md) 内容： - 实体关系图 - 表定义及字段规格 - 索引策略 - 数据迁移方案 - 备份与恢复 - 查询优化指南 --- ## 阶段 5：校验与对齐 ### 5.1 跨文档校验 使用 [references/validation/consistency-checklist.md](references/validation/consistency-checklist.md) 进行半自动校验。 **自动检查：** - 模块设计中的API端点与后端规范匹配 - 数据库实体与模块设计中的数据模型匹配 - UI组件引用有效的设计令牌 - 所有需求都有对应的模块覆盖 **人工审查点：** - 跨模块业务逻辑一致性 - 安全模式对齐 - 性能需求可行性 ### 5.2 生成一致性报告 产出：`docs/specs/{项目}/04-校验报告/一致性校验报告.md` ```markdown # 一致性校验报告 ## 概要 - 总检查项：X - 通过：Y - 警告：Z - 失败：N ## 自动检查结果 | 检查项 | 状态 | 详情 | |--------|------|------| | API覆盖 | 通过 | 所有15个端点已定义 | | 实体映射 | 警告 | 2个实体缺少索引 | | ... | ... | ... | ## 需人工审查 - [ ] 审查跨模块认证流程 - [ ] 验证错误处理一致性 - [ ] 检查性能目标可行性 ``` --- ## 项目规模配置 根据项目规模调整文档粒度： | 规模 | 需求规格 | 模块数 | 规范详细度 | |------|----------|--------|-----------| | **小型**（<10个功能） | 1个文档，简化章节 | 1-3个模块 | 仅核心内容 | | **中型**（10-30个功能） | 完整模板 | 4-8个模块 | 标准详细度 | | **大型**（>30个功能） | 扩展子章节 | 8+个模块 | 完整详细 | 通过初始上下文配置或根据功能数量自动检测。 --- ## 模板参考 所有模板位于 [references/templates/](references/templates/)： | 模板 | 用途 | |------|------| | `requirement-spec-template.md` | 需求规格书 | | `module-planning-template.md` | 业务模块规划 | | `module-design-template.md` | 模块详细设计 | | `architecture-spec-template.md` | 系统架构 | | `ui-ux-spec-template.md` | UI/UX规范 | | `backend-spec-template.md` | 后端开发规范 | | `database-spec-template.md` | 数据库设计 | 用户可通过编辑 `references/templates/` 中的文件自定义模板。 --- ## 执行流程 ``` 1. 收集初始项目上下文（读取需求文档） 2. 识别问题类别，确定优先级 3. 【交互式】逐个提出澄清问题： a. 提出当前问题 b. 等待用户回答 c. 记录答案，处理追问 d. 选择下一个问题 e. 重复直到收集足够信息 4. 汇总确认所有答案 5. 【检查点】用户确认需求澄清结果 6. 生成 需求规格书.md 7. 【检查点】用户确认需求规格书 8. 分解业务模块 9. 生成 模块规划.md 10. 【检查点】用户确认模块结构 11. 为每个模块生成 模块N-详细设计.md 12. 并行生成规范集合： a. 架构规范.md b. UI-UX规范.md c. 后端开发规范.md d. 数据库设计规范.md 13. 运行校验检查 14. 生成 一致性校验报告.md 15. 【检查点】最终审查 ``` --- ## 快速开始示例 ``` 用户：我想为一个库存管理系统创建规范 助手：好的，我来帮您创建库存管理系统的规范文档。首先让我了解一下基本情况。 **问题 1/12：系统规模与用户量** 请选择预期的系统规模： - A) 小型 - 单仓库，<50用户，基础库存管理 - B) 中型 - 多仓库，50-200用户，需批次管理 - C) 大型 - 多仓多级，200-500用户，需WMS集成 - D) 企业级 - 集团多仓，>500用户，全供应链 - E) 其他（请说明） 请选择或输入您的答案： 用户：B 助手：收到，选择 **B) 中型规模** - 多仓库，50-200用户，需批次管理。 **问题 2/12：技术栈偏好**... [继续逐个交互...] ``` --- ## 问题生成框架 **重要：问题应在交互过程中根据上下文动态生成，而非使用预设问题列表。** 参考 [references/question-bank/questioning-framework.md](references/question-bank/questioning-framework.md) 了解： - **问题生成原则**：上下文感知、渐进深入、避免重复、实用性导向 - **问题分类框架**：业务、技术、安全、性能、用户体验五大维度 - **动态问题生成流程**：如何根据用户回答调整后续问题 - **追问机制**：何时触发追问、如何处理不确定的回答 - **澄清终止条件**：何时可以结束澄清阶段 ### 问题生成核心要点 1. **基于上下文生成**：根据项目类型、用户回答、已有信息动态生成 2. **每次一个问题**：逐个交互，等待回答后再生成下一个 3. **至少4个选项**：覆盖常见场景 + "其他"选项 4. **追踪信息缺口**：持续追踪哪些关键决策点尚未明确