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

---
name: req-dev
description: 需求开发计划编写技能。用于 PRD 到代码转换、代码库分析、开发任务拆分、技术方案设计。当用户执行 /req doc 或需要编写开发计划时自动激活。
metadata:
  arguments: <REQ-ID>
---
## 概述

本技能用于从 PRD 文档到代码实现的转换工作，包括：
- **PRD 分析**：提取功能点和技术要求
- **代码库探索**：定位相关代码和修改文件
- **架构引导**：按分层架构规划实施顺序
- **任务拆分**：自动拆分开发子任务
- **风险评估**：识别技术风险和影响范围
- **与 ai-proj 集成**：创建开发任务和文档

---

## 核心能力

### 1. PRD 到代码的智能转换

```
PRD 文档
    ↓ 分析
功能点提取
    ↓ 映射
技术实现方案
    ↓ 定位
修改文件清单
    ↓ 拆分
开发子任务
```

### 2. 代码库智能探索

使用 Task(Explore) 工具：
- 搜索相关功能的现有实现
- 识别类似模式和最佳实践
- 定位需要修改的文件
- 分析依赖关系

**探索策略**：
```
1. 关键词搜索（Grep）
   - 功能名称（如 "manual", "手册"）
   - 模型名称（如 "Manual", "ManualHandler"）

2. 文件模式匹配（Glob）
   - 按命名规范定位（如 "*manual*.go", "*Manual*.tsx"）
   - 按层级定位（如 "models/", "handlers/"）

3. 依赖分析
   - 查看 import 语句
   - 查看 API 调用链
```

### 3. 分层架构引导

#### Go 后端架构（ai-proj 项目）

```
1. models/          - 数据模型层
   └── manual.go    - GORM 模型定义、表结构、关联关系

2. database/        - 数据访问层（Repository）
   └── manual_repository.go - CRUD 操作、复杂查询

3. services/        - 业务逻辑层（Service/Biz）
   └── manual_service.go - 业务规则、事务处理

4. handlers/        - HTTP 处理层（Controller）
   └── manual_handler.go - 请求解析、响应封装、参数验证

5. routes/          - 路由层
   └── manual_routes.go - 路由注册、中间件配置

6. migrations/      - 数据库迁移
   └── YYYYMMDDHHMMSS_add_manual_table.up.sql
```

**开发顺序**：Model → Repository → Service → Handler → Route → Migration

#### React 前端架构

```
1. types/           - 类型定义
   └── manual.ts    - TypeScript 接口、枚举

2. services/        - API 服务层
   └── manualService.ts - API 封装、Axios 请求

3. components/      - 可复用组件
   └── ManualCard.tsx - 通用 UI 组件

4. pages/           - 页面组件
   └── ManualListPage.tsx - 业务页面

5. App.tsx          - 路由配置
```

**开发顺序**：Types → Services → Components → Pages → Router

#### iOS 客户端架构 (SwiftUI + MVVM)

```
AI-Proj-iOS/
├── AI_Proj_iOSApp.swift           # App 入口

├── Core/                          # 核心层
│   ├── Architecture/              # 架构组件
│   │   ├── AppCoordinator.swift   # 导航协调器
│   │   └── AppState.swift         # 全局状态
│   ├── Components/                # 通用 UI 组件
│   │   └── LoadingView.swift      # 加载动画等
│   ├── Config.swift               # 配置（API URL 等）
│   ├── Services/                  # 服务层
│   │   ├── APIEndpoints.swift     # API 端点定义
│   │   ├── AuthService.swift      # 认证服务
│   │   ├── DatabaseService.swift  # 本地数据库
│   │   ├── DIContainer.swift      # 依赖注入
│   │   ├── NetworkService.swift   # 网络请求
│   │   └── ServiceProtocols.swift # 服务协议
│   ├── Theme/                     # 主题配置
│   └── Utilities/                 # 工具类
│       └── DeviceAdaptation.swift # 设备适配

├── Features/                      # 功能模块（MVVM）
│   └── Requirements/              # 需求模块示例
│       ├── RequirementListView.swift      # 列表视图
│       ├── RequirementListViewModel.swift # 列表 ViewModel
│       ├── RequirementDetailView.swift    # 详情视图
│       └── RequirementDetailViewModel.swift # 详情 ViewModel

├── Models/                        # 数据模型
│   ├── DTOs/                      # API 响应 DTO
│   │   ├── RequirementListResponse.swift
│   │   └── TaskListResponse.swift
│   ├── RequirementModel.swift     # 需求模型
│   └── TaskModel.swift            # 任务模型

└── Resources/                     # 资源文件
    └── Assets.xcassets            # 图片资源
```

**开发顺序**：Model → DTO → APIEndpoints → ServiceProtocols → ViewModel → View

---

## 工作流程

### 完整流程图

```
0. ⚠️ 需求验证（必须第一步执行）
   ├── 查看现有 UI/功能
   ├── 确认需求价值
   └── 检查冗余/冲突

1. 获取需求信息
   ├── mcp__ai-proj__get_requirement
   └── mcp__ai-proj__get_requirement_tasks

2. 分析 PRD 文档
   ├── 提取功能点
   ├── 识别技术要求
   └── 确定改动范围

3. 探索代码库（Task Explore）
   ├── 搜索相关现有代码
   ├── 识别修改文件
   └── 分析依赖关系

4. 生成技术方案
   ├── 后端改动规划（Go 分层）
   ├── 前端改动规划（React）
   └── 数据库改动（Migration）

5. 拆分开发任务
   ├── 查找开发任务（link_role=implementation）
   ├── 按文件/模块拆分子任务
   └── mcp__ai-proj__create_subtask

6. 生成开发文档
   ├── mcp__ai-proj__create-and-attach
   └── 使用开发计划模板

7. 风险评估
   ├── 功能影响分析
   ├── 性能影响分析
   └── 兼容性检查
```

### ⚠️ 第 0 步：需求验证（防止浪费时间）

**为什么需要这一步？**

> **教训**：如果不先验证需求，可能花几小时实现一个冗余或错误的功能。

**验证清单**（5-10分钟，节省几小时）：

#### 1. 现有功能检查（最重要）

```bash
# 前端功能检查
## 步骤1：打开相关页面
cd /path/to/project
npm start  # 或直接访问 localhost:3000

## 步骤2：手动浏览 UI，回答问题
- [ ] 这个功能是否已经存在？
- [ ] 现有 UI 是否已经显示相关信息？
- [ ] 是否有专门的列/区域显示该数据？
- [ ] 新功能会不会与现有功能重复？

# 后端功能检查
## 步骤1：查看数据库表结构
psql -U user -d database -c "\d table_name"

## 步骤2：检查现有 API
grep -r "router.GET.*manual" backend/routes/

## 步骤3：回答问题
- [ ] 数据库是否已有相关字段？
- [ ] API 是否已返回所需数据？
- [ ] 是否只需修改前端显示，无需后端改动？
```

**示例：REQ-20260126-0010 的失败案例**

```
❌ 错误做法（浪费3小时）：
1. 看到需求"需求列表显示需求类型标签"
2. 直接开始实现：在标题旁边添加 Tag 组件
3. 写代码 → ESLint 修复 → 截图测试
4. 发现：页面已经有"分类"列显示标签！

✅ 正确做法（5分钟验证，避免浪费）：
1. 打开 localhost:3000/requirements
2. 查看现有 UI：发现已有"分类"列显示类别标签
3. 结论：需求冗余，无需实现
4. 与 PM/用户确认：建议优化现有列，而非添加重复信息
```

#### 2. 价值验证

问自己3个问题：

1. **用户痛点**：这个功能解决什么具体问题？
   - ❌ "显示类别标签" - 太抽象，已有列显示
   - ✅ "用户在列表页快速识别需求类型，现有列不够明显" - 具体痛点

2. **替代方案**：是否有更简单的实现方式？
   - ❌ 添加重复信息
   - ✅ 优化现有列（如：增大标签、调整位置）

3. **投入产出比**：实现成本 vs 用户价值
   - 如果只是"显示信息"，但信息已经显示 → 价值为0

#### 3. 设计审查

- [ ] UI 设计是否合理？（不重复、不混乱）
- [ ] 是否符合现有设计规范？
- [ ] 是否有更优的交互方式？

#### 4. 快速验证流程（替代截图测试）

**快速验证方法**（按优先级）：

| 方法 | 耗时 | 用途 | 何时使用 |
|------|------|------|----------|
| **现有UI检查** | 1-2分钟 | 验证功能是否已存在 | **第一步必做** |
| **TypeScript 类型检查** | 10秒 | 验证代码逻辑 | 每次改代码后 |
| **ESLint 检查** | 5秒 | 验证代码规范 | 每次改代码后 |
| **单元测试** | 30秒 | 验证业务逻辑 | 复杂逻辑必做 |
| **手动功能测试** | 2-3分钟 | 验证交互流程 | 实现完成后 |
| **截图验证** | 5-10分钟 | 验证视觉效果 | **仅最后一步** |

**原则**：
- ✅ 在编写代码前先验证需求（最重要）
- ✅ 优先使用自动化检查（快速）
- ✅ 截图仅用于最终视觉确认（不作为主要测试手段）
- ❌ 不要先实现再验证（浪费时间）

**验证示例**：

```bash
# 1. 现有UI检查（1分钟）
# 访问 localhost:3000/requirements
# 目视检查：是否已有分类列？ → 是

# 2. TypeScript检查（10秒）
cd frontend && npm run type-check
# 期望：0 errors

# 3. ESLint检查（5秒）
npm run lint
# 期望：0 errors 或 warnings

# 4. 手动功能测试（2分钟）
# 刷新页面 → 确认标签显示 → 点击筛选 → 确认筛选工作

# 5. 截图（可选，仅用于记录）
# 如需要文档化，最后再截图
```

**检查清单总结**：

```markdown
## 需求实现前验证清单（必做）

- [ ] **现有UI检查**（1-2分钟）- 功能是否已存在？
- [ ] **价值验证** - 解决什么痛点？有无更好方案？
- [ ] **设计审查** - UI设计是否合理？
- [ ] **数据库检查** - 字段是否已存在？
- [ ] **API检查** - 接口是否已返回数据？

**通过验证后再开始编码！**
```

---

## 开发计划文档模板

```markdown
# [需求标题] 开发计划

## 1. 需求概述

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

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

### 1.3 技术要求
- [ ] 性能要求：[描述]
- [ ] 安全要求：[描述]
- [ ] 兼容性要求：[描述]

---

## 2. 代码库分析

### 2.1 相关现有代码

| 文件路径 | 层级/类型 | 当前功能 | 是否需要修改 | 改动类型 |
|---------|----------|----------|-------------|---------|
| `backend/models/manual.go` | Model | 手册数据模型 | ❌ 无需修改 | - |
| `backend/database/manual_repository.go` | Repository | 手册数据访问 | ⚠️ 需检查 | 新增方法 |
| `backend/services/manual_service.go` | Service | 手册业务逻辑 | ✅ 需修改 | 新增业务逻辑 |
| `backend/handlers/manual_handler.go` | Handler | 手册 HTTP 处理 | ✅ 需修改 | 新增接口 |
| `backend/routes/manual_routes.go` | Route | 手册路由 | ✅ 需修改 | 注册新路由 |
| `frontend/src/types/manual.ts` | Types | 类型定义 | ⚠️ 需检查 | 可能新增类型 |
| `frontend/src/services/manualService.ts` | Service | API 服务 | ✅ 需修改 | 新增 API 调用 |
| `frontend/src/pages/ManualListPage.tsx` | Page | 手册列表页 | ✅ 需修改 | 新增功能 |

### 2.2 探索发现
- **现有实现**：[描述已有的相关功能]
- **可复用代码**：[可以参考或复用的代码模式]
- **依赖关系**：[需要注意的依赖和调用链]

---

## 性能影响评估

### 数据库性能
- **查询复杂度**：O(n) / O(n log n) / O(n²)
- **索引使用**：是否使用索引 / 是否需要新增索引
- **数据量**：预估查询数据量（< 100 / < 1000 / > 1000）
- **并发影响**：是否有锁竞争 / 是否需要事务

### API 性能
- **响应时间**：预期 < 100ms / < 500ms / < 1s
- **QPS 预估**：预估每秒请求数
- **缓存策略**：是否需要 Redis 缓存
- **限流策略**：是否需要限流保护

### 前端性能
- **首屏加载**：新增资源大小（JS/CSS/Image）
- **渲染性能**：是否有大列表渲染 / 是否需要虚拟滚动
- **内存占用**：是否有内存泄漏风险
- **交互响应**：用户操作响应时间 < 100ms
```

---

## 9. 与 ai-proj 集成

### 9.1 任务文档创建

```typescript
// 创建开发任务文档
mcp__ai-proj__create-and-attach({
  taskId: 5326, // 开发任务 ID
  title: "开发计划 - 项目手册列表页设计",
  content: "# 开发计划\n\n[使用本模板生成的内容]"
})
```

### 9.2 子任务拆分

```typescript
// 拆分子任务
const subTasks = [
  { title: "[Model] 修改 manual.go" },
  { title: "[Handler] 修改 manual_handler.go" },
  { title: "[Page] 修改 ManualListPage.tsx" }
];

for (const task of subTasks) {
  await mcp__ai-proj__create_subtask({
    parentId: 5326,
    title: task.title
  });
}
```

### 9.3 开发进度更新

```typescript
// 开发过程中更新文档
mcp__ai-proj__update_task_document({
  taskId: 5326,
  content: originalContent + `

## 开发过程

### 实际修改
- 修改了 manual_handler.go，新增了发布接口

### 遇到的问题
- 问题1：路由冲突
  - 解决方案：调整路由顺序

### 代码变更摘要
- 新增 1 个接口
- 修改 2 个文件
`
})
```

---

## 12. 工具使用指南

### 12.1 Task(Explore) 使用

**场景1：搜索功能相关代码**
```typescript
Task({
  subagent_type: "Explore",
  prompt: "搜索项目手册（manual）相关的所有后端代码，包括 Model、Handler、Service",
  description: "Explore manual backend code"
})
```

**场景2：定位修改文件**
```typescript
Task({
  subagent_type: "Explore",
  prompt: "找到所有包含 ManualListPage 导航链接的文件",
  description: "Find manual navigation links"
})
```

### 12.2 Grep 使用

```typescript
// 搜索后端代码
Grep({
  pattern: "func.*Manual",
  path: "backend/handlers",
  output_mode: "content",
  glob: "*.go"
})

// 搜索前端代码
Grep({
  pattern: "ManualListPage",
  path: "frontend/src",
  output_mode: "files_with_matches",
  glob: "*.{tsx,ts}"
})
```

### 12.3 Glob 使用

```typescript
// 查找所有 manual 相关文件
Glob({
  pattern: "**/*manual*.{go,tsx,ts}",
  path: "."
})

// 查找特定目录下的文件
Glob({
  pattern: "*.go",
  path: "backend/handlers"
})
```

---

## 13. 输出规范

### 13.1 开发文档结构

```markdown
# [需求标题] 开发计划

## 1. 需求概述
[需求信息、功能点、技术要求]

## 2. 代码库分析
[相关代码、探索发现、依赖关系]

## 3. 技术方案设计
### 3.1 后端改动
[Model → Repository → Service → Handler → Route]
### 3.2 前端改动
[Types → Services → Components → Pages]
### 3.3 数据库改动
[Migration 脚本]

## 4. 开发任务拆分
[子任务列表，按层级和文件拆分]

## 5. 实施顺序
[详细的开发步骤和时间安排]

## 6. 技术风险评估
[影响分析、风险清单、性能影响]

## 7. 测试策略
[单元测试、集成测试、E2E 测试]

## 8. 注意事项
[特殊说明、依赖关系、兼容性]
```

### 13.2 任务标题规范

```
格式：[层级/类型] 动作 + 文件名/模块名 + 简要说明

示例：
- [Model] 新增 manual.go 手册数据模型
- [Handler] 修改 manual_handler.go 添加发布接口
- [Page] 修改 ManualListPage.tsx 添加发布按钮
- [Migration] 创建手册版本表
- [Test] 添加手册发布功能单元测试
```

---

## 14. 常见问题

### Q1: 如何确定是否需要新增数据库表？
**A**: 检查以下条件：
- 新数据是否与现有实体是 1:N 或 N:N 关系
- 新数据是否有独立的生命周期
- 新数据是否需要独立查询和管理
如果任一条件满足，考虑新增表；否则可以扩展现有表字段。

### Q2: 什么时候需要创建子任务？
**A**: 当以下条件满足时创建子任务：
- 需要修改 3 个以上文件
- 预估总工时 > 4 小时
- 涉及多个层级（如 Model + Service + Handler）
否则可以作为单个任务处理。

### Q3: 如何评估性能影响？
**A**: 关注以下维度：
- 数据库：查询复杂度、索引使用、数据量
- API：响应时间、QPS、缓存策略
- 前端：首屏加载、渲染性能、内存占用
如果任一维度有显著影响，需要优化方案。

### Q4: 什么时候需要 Migration？
**A**: 以下情况需要 Migration：
- 新增/删除/修改表
- 新增/删除/修改字段
- 新增/删除索引
- 数据迁移/转换

---

## 15. 附录

### 15.1 常用命令速查

```bash
# 后端开发
cd backend
go run main.go              # 启动服务
go test ./...               # 运行测试
make swagger                # 生成 Swagger 文档

# Web 前端开发
cd frontend
npm start                   # 启动开发服务器
npm run build               # 构建生产版本
npm test                    # 运行测试

# iOS 开发
cd AI-Proj-iOS
open AI-Proj-iOS.xcodeproj  # 打开 Xcode 项目
xcodebuild -scheme AI-Proj-iOS -sdk iphonesimulator build  # 命令行构建
xcodebuild test -scheme AI-Proj-iOS -sdk iphonesimulator   # 运行测试

# 数据库迁移
cd backend
migrate -path migrations -database "postgres://..." up
```

### 15.2 相关文档

- [CLAUDE.md](../../../CLAUDE.md) - 项目说明
- [req SKILL.md](../../req-plugin/skills/SKILL.md) - 需求管理
- [req-prd SKILL.md](../../req-prd-plugin/skills/SKILL.md) - PRD 编写
- [dev-coding SKILL.md](../../../skills-dev/dev-coding-plugin/skills/SKILL.md) - 代码实现
- [dev-test SKILL.md](../../../skills-dev/dev-test-plugin/skills/dev-test/SKILL.md) - 测试

---

## 变更记录

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| V1.0 | 2026-01-26 | 初始版本，创建 req-dev 技能 | Claude + qiudl |
| V1.1 | 2026-01-29 | 添加 iOS 端开发规范（SwiftUI + MVVM 架构） | Claude Opus 4.5 |
| V1.2 | 2026-08-26 | 新增既有契约与读模型迁移强制门禁，防止新写链路与原 API/前端脱节 | Codex |

## 详细内容

以下章节已移到 [references/details.md](references/details.md)：

- ⚠️ 既有契约与读模型迁移门禁（必须）
- 3. 技术方案设计
- 4. 开发任务拆分
- 5. 实施顺序指南
- 6. 技术风险评估
- 7. 代码规范检查
- 8. 测试策略
- 10. 最佳实践
- 11. 项目特定规范（ai-proj）