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

name, description, metadata

name	description	metadata
req-dev	需求开发计划编写技能。用于 PRD 到代码转换、代码库分析、开发任务拆分、技术方案设计。当用户执行 /req doc 或需要编写开发计划时自动激活。	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. 现有功能检查（最重要）

# 前端功能检查
## 步骤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分钟	验证视觉效果	仅最后一步

原则：

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

验证示例：

# 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. 截图（可选，仅用于记录）
# 如需要文档化，最后再截图

检查清单总结：

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

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

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

---

开发计划文档模板

# [需求标题] 开发计划

## 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 任务文档创建

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

9.2 子任务拆分

// 拆分子任务
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 开发进度更新

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

## 开发过程

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

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

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

---

12. 工具使用指南

12.1 Task(Explore) 使用

场景1：搜索功能相关代码

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

场景2：定位修改文件

Task({
  subagent_type: "Explore",
  prompt: "找到所有包含 ManualListPage 导航链接的文件",
  description: "Find manual navigation links"
})

12.2 Grep 使用

// 搜索后端代码
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 使用

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

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

---

13. 输出规范

13.1 开发文档结构

# [需求标题] 开发计划

## 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 常用命令速查

# 后端开发
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 - 项目说明
• req SKILL.md - 需求管理
• req-prd SKILL.md - PRD 编写
• dev-coding SKILL.md - 代码实现
• 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：

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