common-spec-driven

name	common-spec-driven
description	Spec驱动的技能规范，所有变更和需求都需要有变更说明、变更方案、变更受益等规范文档
trigger	需要对需求或变更进行规范管理时
disable-when	简单的代码修复或无需记录的小变更
category	common
tags	["spec","change","requirement","documentation","governance"]
requires	["common-requirement-clarification"]

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归档

详细步骤

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. 风险前置：在设计阶段充分识别和评估风险