John Qiu
bfe3815626
- req-workflow: req-dev → req-design (2处) - req-design: changelog 标注"原名 req-dev" - marketplace.json 重新生成 (44→46 plugins) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
456 lines
12 KiB
Markdown
456 lines
12 KiB
Markdown
---
|
||
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、数据模型、文件清单）。
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 版本 | 日期 | 变更内容 |
|
||
|------|------|----------|
|
||
| V1.0 | 2026-01-26 | 初始版本（原名 req-dev） |
|
||
| V2.0 | 2026-04-06 | 重构为 req-design：移除架构指南和编码规范，聚焦 API 契约 + 任务拆分 |
|