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

name, description, arguments

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

---

开发设计文档模板

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

## 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 集成

文档创建

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

子任务拆分

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

进度更新

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）