feat(skill): REQ-20260406-0004 技能三层分离重构（7主线+16插件）
批次1: req-prd 瘦身 + req-design 重定位 + dev-coding 聚焦 批次2: dev-review 新建 + review-checklist 插件 批次3: dev-integration 新建 + req-compare 拆出 批次4: 插件完善 (req-research/db-migration/dev-scaffold/deploy-rollback) 批次5: 平台拆分 (dev-ios/dev-android/dev-mcp/dev-pda) + dev 分组更新 批次6: marketplace.json 32→44 plugins Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
8
skills-req/req-design-plugin/.claude-plugin/plugin.json
Normal file
8
skills-req/req-design-plugin/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "req-design-plugin",
|
||||
"description": "需求开发设计技能。PRD 到开发设计的转换：API 契约、数据模型变更、任务拆分、风险评估。",
|
||||
"version": "2.0.0",
|
||||
"author": {
|
||||
"name": "qiudl"
|
||||
}
|
||||
}
|
||||
455
skills-req/req-design-plugin/skills/SKILL.md
Normal file
455
skills-req/req-design-plugin/skills/SKILL.md
Normal file
@@ -0,0 +1,455 @@
|
||||
---
|
||||
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 契约 + 任务拆分 |
|
||||
Reference in New Issue
Block a user