ai-proj-helper/skills-req/req-design-plugin/skills/SKILL.md

---
name: req-design
description: 需求开发设计技能。用于 PRD 到开发设计的转换：API 契约定义、数据模型变更方案、变更文件清单、开发任务拆分、技术风险评估。当用户执行 /req doc 或需要编写开发设计文档时自动激活。
arguments: <REQ-ID>
---

# 需求开发设计 Skill (req-design)

## 概述

本技能用于将 PRD 文档转换为**开发设计文档**，是产品需求（req-prd）和编码实现（dev-coding）之间的桥梁。

**核心输出**：
- API 契约定义（前后端对齐）
- 数据模型变更方案（新增/修改表和字段）
- 变更文件清单（标注层级和改动类型）
- 开发任务拆分（SMART 原则，2-4h 粒度）
- 技术风险评估

**不包含**（由其他技能负责）：
- 具体代码实现 → `dev-coding`
- 代码规范和编码模式 → `dev-coding`
- 深度架构设计 → `dev-arch`（插件）
- 数据库迁移细节 → `db-migration`（插件）

---

## 技能间契约

| 上游 | 本技能输入 | 本技能输出 | 下游 |
|------|-----------|-----------|------|
| req-prd | PRD 文档（用户故事、业务规则、验收标准） | 开发设计文档 | dev-coding |

**输出格式要求**：
- API 契约：B 级格式（见下方标准）
- 变更清单：按文件列出，标注层级和改动类型
- 任务拆分：每任务 2-4h，SMART 原则

---

## 工作流程

```
0. ⚠️ 需求验证（防浪费，5-10 分钟）
   ├── 现有 UI 检查：功能是否已存在？
   ├── 数据检查：字段/API 是否已有？
   └── 价值验证：痛点明确？有更简方案？

1. 获取需求信息
   ├── mcp__ai-proj__get_requirement
   └── mcp__ai-proj__get_requirement_tasks（找 PRD 任务）

2. 分析 PRD 文档
   ├── 提取功能点和业务规则
   ├── 识别数据实体和关系
   └── 确定非功能需求（性能、安全）

3. 探索代码库
   ├── 搜索相关现有代码（Grep/Glob/Explore）
   ├── 识别修改文件和可复用代码
   └── 分析依赖关系

4. 设计 API 契约
   ├── 定义新增/修改接口（B 级格式）
   ├── 定义请求/响应结构
   └── 定义错误码

5. 设计数据模型变更
   ├── 新增/修改表和字段
   ├── 索引设计
   └── 数据迁移方案（如需要）

6. 生成变更文件清单
   ├── 后端：Model → Repository → Service → Handler → Route → Migration
   ├── 前端：Types → Services → Components → Pages
   └── 标注每个文件的改动类型（新增/修改/删除）

7. 拆分开发任务
   ├── 按模块/文件拆分子任务
   └── mcp__ai-proj__create_subtask

8. 技术风险评估
   ├── 影响分析（兼容性、性能）
   └── 回退方案
```

---

## 需求验证（第 0 步）

> **教训**：不先验证需求，可能花几小时实现冗余功能。

**验证清单**（5-10 分钟）：

1. **现有功能检查**（最重要）
   - 打开相关页面，目视检查功能是否已存在
   - 检查数据库是否已有相关字段
   - 检查 API 是否已返回所需数据

2. **价值验证**
   - 解决什么具体痛点？
   - 有无更简单的替代方案？
   - 投入产出比是否合理？

3. **设计审查**
   - UI 设计是否合理？不重复、不混乱？
   - 是否符合现有设计规范？

**通过验证后再开始设计！**

---

## API 契约格式标准（B 级）

所有新增/修改 API 必须使用以下格式定义契约，作为前后端对齐的桥梁：

```
### POST /api/v1/enterprises
描述: 创建企业

请求体:
  - name: string (required) — 企业名称，最长 100 字符
  - code: string (required) — 企业编码，唯一，正则 ^[A-Z0-9-]+$
  - contact_email: string (optional) — 联系邮箱

响应 200:
  - id: int
  - name: string
  - code: string
  - created_at: datetime

错误:
  - 400: 参数校验失败（name/code 为空或格式错误）
  - 409: 编码已存在
  - 403: 无权限创建企业
```

**B 级规则**：
- 列出所有字段、类型、必填/可选
- 标注校验规则（长度、格式、唯一性）
- 列出所有可能的错误码和含义
- 不需要 JSON 示例（A 级才需要）

---

## 开发设计文档模板

```markdown
# [需求标题] 开发设计文档

## 1. 需求概述

### 1.1 需求信息
| 项目 | 内容 |
|------|------|
| 需求编号 | REQ-YYYYMMDD-XXXX |
| 需求标题 | [标题] |
| 优先级 | high/medium/low |
| 预估工时 | Xh |

### 1.2 功能点清单
- [ ] 功能点1：[描述]
- [ ] 功能点2：[描述]

---

## 2. 代码库分析

### 2.1 相关现有代码
| 文件路径 | 层级 | 当前功能 | 改动类型 |
|---------|------|----------|---------|
| `backend/models/xxx.go` | Model | 数据模型 | 新增字段 |
| `backend/services/xxx_service.go` | Service | 业务逻辑 | 新增方法 |

### 2.2 可复用代码
- [描述已有的可参考实现]

### 2.3 依赖关系
- [需要注意的调用链和依赖]

---

## 3. API 契约

### 3.1 新增接口

### POST /api/v1/xxx
描述: [功能描述]

请求体:
  - field1: type (required) — 说明
  - field2: type (optional) — 说明

响应 200:
  - field1: type
  - field2: type

错误:
  - 400: [说明]
  - 404: [说明]

### 3.2 修改接口
[列出需要修改的现有接口及变更内容]

---

## 4. 数据模型变更

### 4.1 新增表
| 表名 | 说明 |
|------|------|
| xxx | [用途] |

**字段设计**：
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGSERIAL | PK | 主键 |
| tenant_id | BIGINT | NOT NULL, INDEX | 租户ID |
| name | VARCHAR(255) | NOT NULL | 名称 |
| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | 创建时间 |

**索引**：
| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| idx_xxx_tenant | tenant_id | B-tree | 租户查询 |

### 4.2 修改表
| 表名 | 变更 | 说明 |
|------|------|------|
| xxx | 新增字段 yyy | [用途] |

### 4.3 数据迁移（如需要）
[迁移方案描述]

---

## 5. 变更文件清单

### 后端
| 文件 | 层级 | 改动类型 | 改动说明 |
|------|------|---------|---------|
| `models/xxx.go` | Model | 修改 | 新增字段 |
| `database/xxx_repository.go` | Repository | 修改 | 新增查询方法 |
| `services/xxx_service.go` | Service | 修改 | 新增业务方法 |
| `handlers/xxx_handler.go` | Handler | 修改 | 新增接口 |
| `routes/xxx_routes.go` | Route | 修改 | 注册新路由 |
| `migrations/YYYYMMDD_xxx.up.sql` | Migration | 新增 | 表结构变更 |

### 前端
| 文件 | 层级 | 改动类型 | 改动说明 |
|------|------|---------|---------|
| `types/xxx.ts` | Types | 修改 | 新增接口定义 |
| `services/xxxService.ts` | Service | 修改 | 新增 API 调用 |
| `pages/XxxPage.tsx` | Page | 修改 | 新增功能 UI |

---

## 6. 开发任务拆分

### 6.1 任务列表
| # | 任务标题 | 预估工时 | 依赖 |
|---|---------|---------|------|
| 1 | [后端] Model + Migration | 1h | - |
| 2 | [后端] Repository + Service | 2h | #1 |
| 3 | [后端] Handler + Route | 2h | #2 |
| 4 | [前端] Types + Service | 1h | #3 |
| 5 | [前端] 页面开发 | 3h | #4 |
| 6 | [测试] 单元测试 | 2h | #3, #5 |

### 6.2 实施顺序
[按依赖关系排列的开发步骤]

---

## 7. 技术风险评估

### 7.1 影响分析
| 改动类型 | 影响范围 | 风险等级 | 应对措施 |
|---------|---------|---------|---------|
| [描述] | [范围] | 高/中/低 | [措施] |

### 7.2 风险清单
- [ ] 数据库：是否需要数据迁移？是否影响数据完整性？
- [ ] API：是否破坏兼容性？是否需要版本管理？
- [ ] 前端：是否影响现有页面？是否有性能瓶颈？
- [ ] 业务：是否影响核心流程？是否需要灰度？

### 7.3 回退方案
[如果上线出问题，如何回退]

---

## 8. 注意事项
[特殊说明、边界情况、兼容性要求]
```

---

## 任务拆分规则

### SMART 原则

- **Specific**（具体）：明确要修改哪个文件/模块
- **Measurable**（可衡量）：清晰的完成标准
- **Achievable**（可实现）：单个任务 2-4 小时完成
- **Relevant**（相关）：与需求直接相关
- **Time-bound**（有时限）：预估工时

### 拆分粒度

- ✅ 好的粒度：`[Handler] 修改 manual_handler.go 添加发布接口（2h）`
- ❌ 太粗：`[后端] 实现所有后端功能`
- ❌ 太细：`[Handler] 添加 import 语句`

### 按文件拆分（推荐）
- 每个文件对应一个子任务
- 格式：`[层级] 修改 文件名 简要说明`

### 按功能模块拆分（大改动）
- 将相关文件归为一个模块
- 格式：`[模块] 功能描述`

### 标准开发顺序

```
第一阶段：数据层
├── Model 层：定义数据结构
├── Migration：创建/修改表
└── Repository 层：实现数据访问

第二阶段：业务层
├── Service 层：实现业务逻辑
└── 编写单元测试

第三阶段：接口层
├── Handler 层：实现 HTTP 接口
├── Route 层：注册路由
└── API 文档（Swagger）

第四阶段：前端层
├── Types：定义 TypeScript 接口
├── Services：封装 API 调用
├── Components：开发可复用组件
└── Pages：实现业务页面

第五阶段：测试与优化
├── 后端单元测试
├── 前端组件测试
└── E2E 测试
```

---

## 技术风险评估框架

### 影响分析矩阵

| 改动类型 | 影响范围 | 风险等级 | 应对措施 |
|---------|---------|---------|---------|
| 新增字段（非必填） | 低 | 低 | 添加 Migration，向后兼容 |
| 修改字段类型 | 中 | 中 | 数据迁移脚本，充分测试 |
| 删除字段 | 高 | 高 | 确认无依赖，先标记废弃 |
| 新增 API 接口 | 低 | 低 | 接口设计评审 |
| 修改 API 接口 | 中 | 中 | 保留旧接口，添加版本号 |
| 删除 API 接口 | 高 | 高 | 确认无调用，发布公告 |
| 新增前端页面 | 低 | 低 | 路由冲突检查 |
| 修改核心组件 | 高 | 高 | 充分测试所有使用场景 |

### 性能影响评估

| 维度 | 评估项 |
|------|--------|
| 数据库 | 查询复杂度、索引使用、数据量、并发影响 |
| API | 响应时间预期、QPS 预估、缓存策略、限流需求 |
| 前端 | 首屏加载影响、渲染性能、内存占用 |

---

## 与 ai-proj 集成

### 文档创建

```typescript
// 创建开发设计文档并关联任务
mcp__ai-proj__create-and-attach({
  taskId: <设计任务ID>,
  title: "开发设计文档 - [需求标题]",
  content: "<使用上方模板生成的内容>"
})
```

### 子任务拆分

```typescript
mcp__ai-proj__create_subtask({
  parentId: <开发任务ID>,
  title: "[Handler] 修改 manual_handler.go 添加发布接口"
})
```

### 进度更新

```typescript
mcp__ai-proj__update_task_document({
  taskId: <设计任务ID>,
  content: "<更新后的设计文档>"
})
```

---

## 插件触发

| 插件 | 触发条件 | 说明 |
|------|---------|------|
| `dev-arch` | 新模块/新表/复杂架构 | 深度架构设计 |
| `db-migration` | 涉及数据库变更 | 数据库迁移方案 |

当检测到以上条件时，建议用户启用对应插件。

---

## 最佳实践

1. **先验证再设计** — 5 分钟验证省 3 小时返工
2. **API 契约先行** — 前后端对齐的桥梁，先定义再实现
3. **复用优于新建** — 充分探索代码库，识别可复用代码
4. **风险前置** — 在设计阶段识别风险，而非编码时才发现
5. **粒度适中** — 任务拆分 2-4h，不要太粗也不要太细
6. **文档可操作** — 开发者可直接按设计文档实施

---

## 常见问题

### Q1: 如何确定是否需要新增数据库表？
检查：新数据是否与现有实体有独立生命周期？是否需要独立查询？是否 1:N 或 N:N 关系？任一满足则新增表。

### Q2: 什么时候需要创建子任务？
修改 3 个以上文件 / 预估工时 > 4h / 涉及多个层级 → 创建子任务。

### Q3: API 契约需要多详细？
B 级：字段 + 类型 + 必填/可选 + 校验规则 + 错误码。不需要 JSON 示例。

### Q4: 设计文档和 PRD 的边界？
PRD 说「做什么」（用户故事、业务规则、验收标准），设计文档说「怎么做」（API、数据模型、文件清单）。

---

## Memory 隔离规则（强制，源自 devflow-claude 借鉴）

**规则：本 skill 产出的设计文档禁止受 auto-memory 影响结构和字段定义。**

### 禁止行为
1. 不得用 memory 里的历史 API 契约填充当前设计（避免张冠李戴）
2. 不得根据 memory 偏好省略"变更文件清单"/"数据模型变更"等章节
3. 不得读取 `~/.claude/projects/*/memory/` 生成 API 字段或 SQL

### 允许行为
- memory 可影响交互风格、命令推荐
- memory 可记住"用户偏好 RESTful 而非 RPC" 这类**偏好**，但字段定义必须基于当前需求

### Why
设计文档是开发契约，字段/接口/表结构错一个字就是 bug。memory 污染会让 AI 脑补出"看起来像但不对"的字段。必须严格基于当前 PRD + 代码现状生成。

**参考**：devflow-claude `plugins/req/commands/_common.md` 同名规则。

---

## 变更记录

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| V1.0 | 2026-01-26 | 初始版本（原名 req-dev） |
| V2.0 | 2026-04-06 | 重构为 req-design：移除架构指南和编码规范，聚焦 API 契约 + 任务拆分 |
| V2.1 | 2026-04-16 | 新增 Memory 隔离规则（REQ-20260416-0017） |