# Common Spec Driven

> Spec驱动的技能规范，所有变更和需求都需要有变更说明、变更方案、变更受益等规范文档

- Skill: `bage2014/common-spec-driven` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bage2014/common-spec-driven`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bage2014/common-spec-driven/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bage2014 (https://skillmd.com/u/bage2014)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bage2014/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. **风险前置**：在设计阶段充分识别和评估风险