common-spec-driven

# common-spec-driven ## 功能描述 Spec驱动的技能规范，确保所有需求变更、功能新增、技术改造都有完整的规范文档。包含变更说明、变更方案、变更受益、风险评估等核心要素。 ## 触发条件 - 需求首次提出时自动触发 - 功能需求变更时触发 - 技术方案变更时触发 - 代码重构或技术改造时触发 - 涉及多个模块的联动变更时触发 ## 何时使用 - 新项目立项时需要编写完整的 Spec 文档 - 功能需求变更时需要更新 Spec 文档 - 技术方案评审前需要准备 Spec 文档 - 代码提交前需要检查 Spec 完整性 ## 何时不使用 - 简单的 Bug 修复（不涉及需求变更） - 纯代码格式调整或注释优化 - 文档错别字修正 ## 核心功能 ### 1. 变更说明 定义变更的背景、原因和范围，确保所有相关人员理解变更的必要性。 ### 2. 变更方案 详细描述变更的实现方案，包括技术选型、架构设计、接口定义等。 ### 3. 变更受益 分析变更带来的业务价值和技术收益，量化评估变更效果。 ### 4. 风险评估 识别变更可能带来的风险，制定缓解措施。 ### 5. 影响范围 分析变更对系统各模块的影响，评估回归测试范围。 ## Spec 文档结构 ### 文档模板 ```markdown # [SPEC-XXX] 变更说明文档 ## 1. 变更概述 - **变更编号**：SPEC-XXX - **变更标题**：变更的简短描述 - **变更类型**：新增功能/需求变更/技术改造/Bug修复 - **优先级**：P0/P1/P2/P3 - **状态**：草稿/评审中/已批准/进行中/已完成 - **创建日期**：YYYY-MM-DD - **负责人**：XXX ## 2. 变更背景 - 为什么需要这个变更？ - 当前存在什么问题？ - 业务驱动因素是什么？ ## 3. 变更方案 ### 3.1 技术方案 - 技术选型说明 - 架构设计图 - 核心类和方法设计 ### 3.2 接口变更 - 新增/修改的 API 接口 - 参数变更说明 - 返回值变更说明 ### 3.3 数据库变更 - 新增/修改的数据表 - 字段变更说明 - 数据迁移方案 ### 3.4 部署方案 - 部署步骤 - 回滚方案 - 依赖版本要求 ## 4. 变更受益 ### 4.1 业务价值 - 提升的业务指标 - 用户体验改善 - 效率提升 ### 4.2 技术收益 - 代码质量提升 - 架构优化 - 性能改善 ### 4.3 量化指标 | 指标 | 变更前 | 变更后 | 提升幅度 | |------|--------|--------|----------| | 响应时间 | 500ms | 200ms | 60% | ## 5. 风险评估 | 风险项 | 风险等级 | 影响范围 | 缓解措施 | |--------|----------|----------|----------| | 数据库迁移失败 | 高 | 数据层 | 备份后迁移，准备回滚脚本 | | 接口兼容性问题 | 中 | API层 | 提供版本兼容方案 | ## 6. 影响范围 ### 6.1 模块影响 - [ ] 模块A - [ ] 模块B - [ ] 模块C ### 6.2 测试范围 - 新增测试用例数：XX - 回归测试范围：XX - 性能测试：是/否 ## 7. 实施计划 | 阶段 | 时间 | 负责人 | 交付物 | |------|------|--------|--------| | 设计阶段 | YYYY-MM-DD | XXX | 技术方案文档 | | 开发阶段 | YYYY-MM-DD | XXX | 代码提交 | | 测试阶段 | YYYY-MM-DD | XXX | 测试报告 | | 上线阶段 | YYYY-MM-DD | XXX | 上线验证 | ## 8. 验收标准 - [ ] 功能符合需求描述 - [ ] 性能指标达标 - [ ] 代码覆盖率 ≥ 80% - [ ] 无重大 Bug ``` ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | changeType | String | 是 | 变更类型：feature/change/refactor/bugfix | | title | String | 是 | 变更标题 | | description | String | 是 | 变更详细描述 | | priority | String | 否 | 优先级：P0/P1/P2/P3，默认 P1 | | owner | String | 否 | 负责人 | | businessValue | String | 否 | 业务价值描述 | ## 输出格式 ```json { "specId": "SPEC-001", "title": "变更标题", "changeType": "feature", "priority": "P1", "status": "draft", "sections": { "overview": {...}, "background": {...}, "solution": {...}, "benefits": {...}, "risks": [...], "impact": {...}, "plan": [...], "acceptance": [...] }, "createdAt": "2024-01-15T10:00:00Z", "owner": "张三" } ``` ## 使用流程 ``` 需求提出 → Spec文档创建 → 方案评审 → 批准实施 → 开发测试 → 验收完成 → Spec归档 ``` ### 详细步骤 1. **需求提出**：识别变更需求，填写基本信息 2. **Spec创建**：使用模板生成完整的 Spec 文档 3. **方案评审**：组织技术评审，收集反馈 4. **批准实施**：评审通过后批准开发 5. **开发测试**：按 Spec 文档进行开发和测试 6. **验收完成**：验证功能符合验收标准 7. **Spec归档**：将最终版本的 Spec 文档归档 ## Spec 检查清单 | 检查项 | 说明 | 状态 | |--------|------|------| | 完整性 | Spec文档是否包含所有必需章节 | ✅/❌ | | 清晰性 | 技术方案描述是否清晰 | ✅/❌ | | 可行性 | 方案是否在技术和资源范围内可行 | ✅/❌ | | 风险评估 | 是否识别了主要风险并制定缓解措施 | ✅/❌ | | 验收标准 | 是否有明确可测试的验收标准 | ✅/❌ | | 实施计划 | 是否有详细的实施计划和时间节点 | ✅/❌ | ## 变更类型定义 | 类型 | 说明 | 适用场景 | |------|------|----------| | **feature** | 新增功能 | 全新的业务功能开发 | | **change** | 需求变更 | 现有功能的需求调整 | | **refactor** | 技术改造 | 代码重构、架构优化 | | **bugfix** | Bug修复 | 修复生产环境问题 | ## 优先级定义 | 优先级 | 说明 | 响应时间 | |--------|------|----------| | **P0** | 紧急 - 影响核心业务 | 立即处理 | | **P1** | 高 - 影响重要功能 | 24小时内 | | **P2** | 中 - 一般功能变更 | 7天内 | | **P3** | 低 - 优化改进 | 按需安排 | ## 配置要求 无需额外配置，基于模板引擎生成 Spec 文档。 ## 最佳实践 1. **尽早编写**：在需求确认后立即开始编写 Spec 文档 2. **保持同步**：开发过程中若方案变更，及时更新 Spec 3. **团队协作**：Spec 文档应团队共同评审和维护 4. **量化指标**：尽可能用数据衡量变更受益 5. **风险前置**：在设计阶段充分识别和评估风险