bage2014 common-spec-driven
功能描述
Spec驱动的技能规范，确保所有需求变更、功能新增、技术改造都有完整的规范文档。包含变更说明、变更方案、变更受益、风险评估等核心要素。
触发条件
- 需求首次提出时自动触发
- 功能需求变更时触发
- 技术方案变更时触发
- 代码重构或技术改造时触发
- 涉及多个模块的联动变更时触发
何时使用
- 新项目立项时需要编写完整的 Spec 文档
- 功能需求变更时需要更新 Spec 文档
- 技术方案评审前需要准备 Spec 文档
- 代码提交前需要检查 Spec 完整性
何时不使用
- 简单的 Bug 修复（不涉及需求变更）
- 纯代码格式调整或注释优化
- 文档错别字修正
核心功能
1. 变更说明
定义变更的背景、原因和范围，确保所有相关人员理解变更的必要性。
2. 变更方案
详细描述变更的实现方案，包括技术选型、架构设计、接口定义等。
3. 变更受益
分析变更带来的业务价值和技术收益，量化评估变更效果。
4. 风险评估
识别变更可能带来的风险，制定缓解措施。
5. 影响范围
分析变更对系统各模块的影响，评估回归测试范围。
Spec 文档结构
文档模板
# [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 | 否 | 业务价值描述 |
输出格式
{
"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归档
详细步骤
- 需求提出：识别变更需求，填写基本信息
- Spec创建：使用模板生成完整的 Spec 文档
- 方案评审：组织技术评审，收集反馈
- 批准实施：评审通过后批准开发
- 开发测试：按 Spec 文档进行开发和测试
- 验收完成：验证功能符合验收标准
- Spec归档：将最终版本的 Spec 文档归档
Spec 检查清单
| 检查项 | 说明 | 状态 |
|---|---|---|
| 完整性 | Spec文档是否包含所有必需章节 | ✅/❌ |
| 清晰性 | 技术方案描述是否清晰 | ✅/❌ |
| 可行性 | 方案是否在技术和资源范围内可行 | ✅/❌ |
| 风险评估 | 是否识别了主要风险并制定缓解措施 | ✅/❌ |
| 验收标准 | 是否有明确可测试的验收标准 | ✅/❌ |
| 实施计划 | 是否有详细的实施计划和时间节点 | ✅/❌ |
变更类型定义
| 类型 | 说明 | 适用场景 |
|---|---|---|
| feature | 新增功能 | 全新的业务功能开发 |
| change | 需求变更 | 现有功能的需求调整 |
| refactor | 技术改造 | 代码重构、架构优化 |
| bugfix | Bug修复 | 修复生产环境问题 |
优先级定义
| 优先级 | 说明 | 响应时间 |
|---|---|---|
| P0 | 紧急 - 影响核心业务 | 立即处理 |
| P1 | 高 - 影响重要功能 | 24小时内 |
| P2 | 中 - 一般功能变更 | 7天内 |
| P3 | 低 - 优化改进 | 按需安排 |
配置要求
无需额外配置，基于模板引擎生成 Spec 文档。
最佳实践
- 尽早编写：在需求确认后立即开始编写 Spec 文档
- 保持同步：开发过程中若方案变更，及时更新 Spec
- 团队协作：Spec 文档应团队共同评审和维护
- 量化指标：尽可能用数据衡量变更受益
- 风险前置：在设计阶段充分识别和评估风险