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

详细步骤

需求提出：识别变更需求，填写基本信息
Spec创建：使用模板生成完整的 Spec 文档
方案评审：组织技术评审，收集反馈
批准实施：评审通过后批准开发
开发测试：按 Spec 文档进行开发和测试
验收完成：验证功能符合验收标准
Spec归档：将最终版本的 Spec 文档归档

Spec 检查清单

检查项	说明	状态
完整性	Spec文档是否包含所有必需章节	✅/❌
清晰性	技术方案描述是否清晰	✅/❌
可行性	方案是否在技术和资源范围内可行	✅/❌
风险评估	是否识别了主要风险并制定缓解措施	✅/❌
验收标准	是否有明确可测试的验收标准	✅/❌
实施计划	是否有详细的实施计划和时间节点	✅/❌

变更类型定义

类型	说明	适用场景
feature	新增功能	全新的业务功能开发
change	需求变更	现有功能的需求调整
refactor	技术改造	代码重构、架构优化
bugfix	Bug修复	修复生产环境问题

优先级定义

优先级	说明	响应时间
P0	紧急 - 影响核心业务	立即处理
P1	高 - 影响重要功能	24小时内
P2	中 - 一般功能变更	7天内
P3	低 - 优化改进	按需安排

配置要求

无需额外配置，基于模板引擎生成 Spec 文档。

最佳实践

尽早编写：在需求确认后立即开始编写 Spec 文档
保持同步：开发过程中若方案变更，及时更新 Spec
团队协作：Spec 文档应团队共同评审和维护
量化指标：尽可能用数据衡量变更受益
风险前置：在设计阶段充分识别和评估风险