diff --git a/skills-req/req-plugin/skills/SKILL.md b/skills-req/req-plugin/skills/SKILL.md index 15c824b..5ad1571 100644 --- a/skills-req/req-plugin/skills/SKILL.md +++ b/skills-req/req-plugin/skills/SKILL.md @@ -86,6 +86,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 1. /req new → 创建需求 (draft) 2. 需求讨论 → 输出结论摘要，用户确认 3. req-prd 技能 → 编写 PRD（创建【评审】PRD 任务） +3.5 /req prototype → 生成 Stitch 原型（可选，有 UI 时推荐） 4. /req submit → 提交评审 (pending)，含 4 道门禁 5. /req review pass → 评审通过 (approved, delivery_stage=analysis) 6. /req next → 推进到 design/dev 阶段 @@ -94,7 +95,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 9. /req cr → 代码评审（创建【代码评审】任务） 10. /req next → 推进到 testing 阶段 11. /req test → 测试验收（5-Gate 流程） -12. /req deploy → 批量部署（DG1-DG6 Deploy Gates） +12. /req deploy → 批量部署（build-and-push.sh → Jenkins ai-proj） 13. /req done → 归档 (archived) + git commit + push ``` @@ -231,6 +232,18 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD **`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联 +### 原型设计 + +**`/req prototype [REQ-ID]`** — 基于 PRD 生成 Stitch 原型： +1. 读取 PRD 文档，提取 UI 相关描述 +2. 创建 Stitch 项目 + 生成页面（调用 req-prototype 子技能） +3. 截图回填 PRD「4.2 界面原型」章节 +- 参数：`--device [desktop|mobile|tablet]`，`--model [pro|flash]` + +**`/req prototype edit [REQ-ID] --prompt "..."`** — 修改已有原型 + +**`/req prototype variant [REQ-ID]`** — 生成设计变体供选择 + ### 提交评审 **`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径： @@ -281,13 +294,15 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD **`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程 -**`/req deploy [--project ] [--env ]`** — 项目级批量部署： +**`/req deploy [--project ] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）： 1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed） 2. AskUserQuestion 确认范围 3. `ai-proj task create` 创建部署批次任务 -4. Deploy Gates DG1-DG6：staging 部署 → 冒烟测试 → 回归 → 生产部署 -5. `ai-proj task append-doc` 记录部署文档 -6. `ai-proj req advance --id --to released` 批量推进 +4. 部署前检查（变更检测、数据库迁移） +5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify` +6. 部署后验证（截图 + 定向验证） +7. `ai-proj task append-doc` 记录部署文档 + 写入需求历史 +8. `ai-proj req advance --id --to released` 批量推进 **`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id `： - **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops @@ -376,185 +391,10 @@ ai-proj req tasks --id # 查看关联任务 **linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `regression`, `documentation` -## 详细阶段管理命令 - -### `/req phase [REQ-ID]` -查看需求当前开发阶段和任务状态。 - -**执行逻辑**： -1. `get_requirement(id)` → 获取 `delivery_stage` -2. `get_requirement_tasks(id)` → 获取所有关联任务 -3. 按 linkRole 分组展示，标注当前阶段任务完成度 - -**输出示例**： -``` -REQ-20260218-0013 | 阶段: dev (开发) -──────────────────────────────────── -✅ analysis (评审) - ✅ #6035 【评审】PRD: 需求全生命周期阶段化管理 -▶ dev (开发) ← 当前阶段 - 🔄 #6042 【开发-后端】实现阶段管理 API [in_progress] - ⬜ #6043 【开发-前端】阶段可视化组件 [todo] -⬜ review (代码评审) -⬜ testing (测试) -``` - -### `/req resume [REQ-ID]` -从上次中断的位置恢复工作。**会话被截断后的首选命令**。 - -**执行逻辑**： -1. 若无 REQ-ID → `list_requirements(status=approved)` 找最近活跃需求 -2. `get_requirement(id)` → 获取 delivery_stage -3. `get_requirement_tasks(id)` → 获取所有关联任务及状态 -4. 汇总展示恢复上下文 - -**输出格式**： -``` -📋 恢复工作上下文 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -需求: REQ-20260218-0016 | 需求标题 -状态: approved | 阶段: dev (开发) - -📊 任务进度: 2/4 完成 - ✅ #6051 【开发-后端】实现 API - 🔄 #6053 【开发-Skill】xxx [in_progress] - ⬜ #6054 【开发-Skill】xxx [todo] - -▶ 建议操作: - 1. 继续任务 #6053（当前 in_progress） - 2. 执行 /req next 推进阶段 -``` - -### `/req regression [--module ] [--mode ]` -**运行回归测试**。系统级持续质量活动。 - -- `--module` 指定模块，不指定则按影响域推断 -- `--mode`：`impact`（影响域，默认）| `critical`（关键路径）| `full`（全量） - -**执行逻辑**： -1. 确定范围：指定 module → 直接运行；未指定 → `git diff` + `module-deps.json` 推断 -2. 运行 `regression-suite/suites/` 下对应脚本 -3. 对比上次运行结果，标记回归（上次 PASS + 本次 FAIL） -4. 有回归 → AskUserQuestion「是否创建 bug 需求？」 - -## 辅助命令 - -**`/req link [REQ-ID] --task-id [TASK-ID]`** — 关联任务到需求 - -**`/req decompose [REQ-ID]`** — 分解需求为任务，自动加阶段前缀 - -**`/req generate-tasks [REQ-ID]`** — 根据 PRD 自动生成开发任务，带【开发】前缀 - -**`/req priority [REQ-ID] [low|medium|high]`** — 设置需求优先级 - -**`/req stats [REQ-ID|--all]`** — 查看需求统计信息 - -## 阶段任务 Checklist 模板 - -`/req next` 推进到新阶段时，通过 `create_stage_task` 自动创建建议任务： - -### analysis（评审） -``` -☐ 【评审】PRD: {需求标题} (linkRole: prd) -☐ 【评审】技术设计: {需求标题} (linkRole: design) [可选] -``` - -### design（设计） -``` -☐ 【设计】技术方案: {需求标题} (linkRole: design) -``` - -### dev（开发） -``` -☐ 【开发-后端】{需求标题} (linkRole: implementation) -☐ 【开发-前端】{需求标题} (linkRole: implementation) [可选] -``` - -### review（代码评审） -``` -☐ 【代码评审】{需求标题} (linkRole: code_review) -``` - -### testing（测试） -``` -☐ 【测试】单元测试: {需求标题} (linkRole: test) -☐ 【测试】集成测试: {需求标题} (linkRole: test) [可选] -``` - -### 部署（由 `/req deploy` 批量触发） -``` -testing 完成 → 进入「待部署池」→ /req deploy 创建批次任务 -``` - -**按需求类型的最低测试标准**： - -| 需求类型 | 最低测试要求 | -|----------|-------------| -| **code** | `go test` 或前端测试通过 + API 验证 + 截图验证 | -| **skill** | 关键词一致性 + 规则无歧义 + 边界情况（至少 3 项） | -| **ops** | 部署命令可执行 + 健康检查通过 | - -## MCP 工具映射 - -| 命令 | MCP 工具 | -|------|----------| -| `/req` | `list_requirements` | -| `/req new` | `create_requirement` | -| `/req phase` | `get_requirement` + `get_requirement_tasks` | -| `/req next` | `advance_delivery_stage` + `create_stage_task` | -| `/req resume` | `get_requirement` + `get_requirement_tasks` | -| `/req dev` | `get_requirement` + `get_requirement_tasks` + `start_task_with_timer` | -| `/req cr` | `get_requirement_tasks` + Git diff | -| `/req test` | `req-test-gate` 5-Gate 流程 | -| `/req deploy` | Deploy Gates DG1-DG6 | -| `/req regression` | `git diff` + 回归套件 | -| `/req done` | 类型推断 + 检查清单 + `archive_requirement` | -| `/req review` | `submit_requirement` | -| `/req review pass` | `approve_requirement` | -| `/req link` | `link_tasks_to_requirement` | - -## 环境选择 - -> **重要**：正式需求应直接在**生产环境** (`mcp__ai-proj-prod__*`) 创建。 -> 仅在功能测试、流程验证时使用开发环境 (`mcp__ai-proj-dev__*`)。 -> 开发环境同步到生产时，`due_date`、`reviewer_id`、`allow_self_approve` 等字段会丢失，需手动补充。 - -## Hook 自动同步 - -需求操作自动触发同步，无需手动执行： - -| 事件 | 触发操作 | -|------|----------| -| `requirement.created` | 同步到远程 | -| `requirement.approved` | 同步需求和任务 | -| `task.completed` | 同步任务状态 | -| `requirement.archived` | 最终同步 + 思源笔记 | - -**手动同步**： -```typescript -mcp__ai-proj__sync_requirement_to_remote(requirementId) -mcp__ai-proj__batch_sync_tasks_to_remote(taskIds) -``` - -**同步已知限制**： -| 字段 | 同步支持 | 说明 | -|------|----------|------| -| title, description, status, priority | ✅ | 正常同步 | -| **due_date** | ❌ | 不会同步，需手动补充 | -| reviewer_id | ❌ | 不会同步 | -| allow_self_approve | ❌ | 不会同步 | - -## 思源笔记集成 - -归档时自动同步 5 阶段文档到思源笔记： -- 路径：`需求管理/REQ-XXXX/` -- 文档：01-PRD.md ~ 05-生命周期总结.md -- 手动同步：`/req sync-siyuan [REQ-ID]` - ## 相关技能 | 技能 | 用途 | |------|------| | `req-prd` | PRD 文档编写 + 评审方法论 | -| `req-test-gate` | 测试 5-Gate + Deploy Gates | -| `req-dev` | PRD 到代码转换、开发计划 | +| `req-prototype` | Stitch 原型生成 + 迭代 | +| `dev-test` | 测试 + 质量门禁 | diff --git a/skills-req/req-prd-plugin/skills/SKILL.md b/skills-req/req-prd-plugin/skills/SKILL.md index f64c127..581fce2 100644 --- a/skills-req/req-prd-plugin/skills/SKILL.md +++ b/skills-req/req-prd-plugin/skills/SKILL.md @@ -1,6 +1,6 @@ --- name: req-prd -description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划、PRD 评审。当用户提到产品设计、PRD、需求文档、功能规划、用户故事、PRD 评审相关任务时自动激活。 +description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划。当用户提到产品设计、PRD、需求文档、功能规划、用户故事相关任务时自动激活。 --- # 产品需求设计 Skill (req-prd) @@ -304,7 +304,11 @@ CREATE TABLE `prd_product_label` ( [流程图或步骤描述] ### 4.2 界面原型 -[原型链接或描述] + +> 使用 `/req prototype [REQ-ID]` 基于 PRD 自动生成 Stitch 原型。 +> 生成后截图将自动回填到此章节。 + +[执行 `/req prototype` 后自动填充] ## 5. 技术要求 ### 5.1 性能要求 @@ -619,7 +623,8 @@ mcp__ai-proj__export_task_document_to_file ## 常用工具 ### 原型设计 -- Figma +- **Stitch** (Google AI) — 集成在 `/req prototype`，自动从 PRD 生成原型 +- Figma — 手动精细设计 - Sketch - Axure @@ -657,114 +662,3 @@ mcp__ai-proj__export_task_document_to_file - 数据安全分级 - 敏感操作审计 - 权限最小化原则 - ---- - -## PRD 评审方法论 - -PRD 评审是需求流程的关键质量关卡。 - -### 评审流程 - -``` -PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论 -``` - -### 结构完整性检查 - -| 检查项 | 必须 | 说明 | -|--------|:----:|------| -| 基本信息 | ✓ | 编号、标题、日期、作者 | -| 需求背景 | ✓ | 为什么需要这个功能 | -| 目标用户 | ✓ | 面向的用户群体 | -| 功能描述 | ✓ | 详细功能需求 | -| 数据模型 | ✓ | 数据库表结构 | -| API 设计 | ✓ | RESTful 接口 | -| 验收标准 | ✓ | 验收条件 | -| 用户故事 | ○ | As a... I want... | -| 页面原型 | ○ | 界面布局 | -| 非功能需求 | ○ | 性能、安全 | - -### 需求清晰度（SMART 原则） - -| 原则 | 检查点 | -|------|--------| -| **S**pecific | 描述是否具体明确 | -| **M**easurable | 是否有量化指标 | -| **A**chievable | 技术上是否可行 | -| **R**elevant | 是否与业务目标相关 | -| **T**ime-bound | 是否有时间范围 | - -**示例**： -- ❌ "用户可以搜索需求" -- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示" - -### 技术可行性 - -| 维度 | 评估内容 | -|------|----------| -| 技术栈兼容 | 现有栈是否支持 | -| 架构影响 | 是否需修改架构 | -| 第三方依赖 | 是否引入新依赖 | -| 性能影响 | 潜在性能问题 | -| 安全考量 | 安全风险 | - -### 数据模型验证 - -| 检查项 | 说明 | -|--------|------| -| 表结构 | 字段类型、约束、索引 | -| 关联关系 | 外键、多对多 | -| 命名规范 | 符合项目规范 | -| 扩展性 | 预留扩展字段 | -| 查询性能 | 常用查询有索引 | - -### API 设计审查 - -| 检查项 | 标准 | -|--------|------| -| RESTful | URL 用名词，HTTP 方法语义正确 | -| 响应格式 | `{success, data, message}` | -| 错误处理 | 明确的错误码 | -| 分页 | `?page=1&page_size=20` | -| 版本控制 | `/api/v1/...` | - -### 评审结论模板 - -**通过**： -``` -✅ PRD 评审通过 - -【结论】文档完整，需求清晰，方案可行，建议批准。 -【肯定】需求背景清晰、数据模型合理、API 规范 -【建议】（非阻塞）补充性能测试用例 -【评审人】xxx 【时间】2026-xx-xx -``` - -**驳回**： -``` -❌ PRD 评审驳回 - -【原因】 -1. 数据模型缺少索引 -2. API 缺少错误处理 -3. 搜索需求描述模糊 - -【修改要求】 -□ 补充索引设计 -□ 明确错误码 -□ 细化搜索实现 - -【驳回人】xxx 【时间】2026-xx-xx -``` - -### 常见驳回原因 - -| 类别 | 问题 | 建议 | -|------|------|------| -| 结构缺失 | 缺数据模型或 API | 补充技术设计 | -| 需求模糊 | 描述不具体 | 按 SMART 重写 | -| 边界不清 | 缺异常处理 | 补充边界条件 | -| 设计缺陷 | 模型/API 不合理 | 重新设计 | -| 范围过大 | 难以实现 | 拆分为多需求 | -| 验收不明 | 缺验收标准 | 补充验收条件 | diff --git a/skills-req/req-prototype-plugin/.claude-plugin/plugin.json b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..03a6ced --- /dev/null +++ b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "req-prototype-plugin", + "description": "Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-req/req-prototype-plugin/skills/SKILL.md b/skills-req/req-prototype-plugin/skills/SKILL.md new file mode 100644 index 0000000..68295d1 --- /dev/null +++ b/skills-req/req-prototype-plugin/skills/SKILL.md @@ -0,0 +1,164 @@ +--- +name: req-prototype +description: Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型，支持编辑和变体生成。当执行 /req prototype 或需要生成界面原型时使用。 +arguments: [REQ-ID] [--device desktop|mobile|tablet] [--model pro|flash] [--prompt "..."] +--- + +# Stitch 原型设计 Skill (req-prototype) + +## 概述 + +基于 PRD 文档自动生成 Stitch UI 原型，插入在 PRD 编写完成后、submit 评审前。 + +**核心流程**：读取 PRD → 提取 UI 描述 → 转英文 prompt → 调用 Stitch API → 截图回填 PRD + +## 前置条件 + +执行前必须检查： + +| 检查项 | 方式 | 失败处理 | +|--------|------|----------| +| 需求存在 | `ai-proj req get --id ` | 报错：需求不存在 | +| PRD 文档存在 | `ai-proj req tasks --id ` 找 linkRole=prd 任务 + 检查文档 | 报错：请先执行 req-prd 编写 PRD | +| PRD 包含 UI 描述 | 检查 PRD 中「功能需求」「交互设计」「界面原型」章节 | 警告：PRD 未包含 UI 相关描述，建议先补充 | + +## 子命令 + +### 1. `/req prototype [REQ-ID]` — 生成原型 + +**流程**： + +``` +1. 前置条件检查 +2. 读取 PRD 文档（ai-proj task get-doc） +3. 提取 UI 相关内容（功能需求 + 交互设计章节） +4. PRD → Stitch Prompt 转换（中文 → 英文设计描述） +5. 创建 Stitch 项目（mcp__stitch__create_project） +6. 生成页面（mcp__stitch__generate_screen_from_text） +7. 获取截图（mcp__stitch__get_screen） +8. 回填 PRD「4.2 界面原型」章节 +``` + +**参数**： + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `--device` | `desktop` | 设备类型：desktop / mobile / tablet | +| `--model` | `pro` | 模型：pro (GEMINI_3_1_PRO) / flash (GEMINI_3_FLASH) | + +### 2. `/req prototype edit [REQ-ID] --prompt "..."` — 编辑原型 + +**流程**： + +``` +1. 从 PRD「4.2 界面原型」元数据获取 stitch_project_id 和 screen_id +2. 调用 mcp__stitch__edit_screens 编辑指定页面 +3. 获取更新后截图 +4. 更新 PRD「4.2 界面原型」章节 +``` + +### 3. `/req prototype variant [REQ-ID]` — 生成变体 + +**流程**： + +``` +1. 从 PRD「4.2 界面原型」元数据获取 stitch_project_id 和 screen_id +2. 调用 mcp__stitch__generate_variants 生成变体 +3. 展示所有变体截图供用户选择 +4. 用户选择后更新 PRD +``` + +**变体参数**： + +| 参数 | 选项 | 说明 | +|------|------|------| +| `creativeRange` | REFINE / EXPLORE / REIMAGINE | 创意程度 | +| `aspects` | LAYOUT / COLOR_SCHEME / IMAGES / TEXT_FONT / TEXT_CONTENT | 变化维度 | + +## PRD → Stitch Prompt 转换策略 + +从 PRD 提取以下章节内容，转换为英文设计 prompt： + +1. **功能需求**（第 3 章）→ 提取功能列表和交互描述 +2. **交互设计**（第 4 章）→ 提取用户流程和界面描述 +3. **目标用户**（第 2 章）→ 确定设计风格和复杂度 + +**转换模板**： + +``` +Design a [device_type] web application for [product_name]. + +Target users: [user_description] + +Key features: +- [feature_1]: [description] +- [feature_2]: [description] +... + +User flow: +1. [step_1] +2. [step_2] +... + +UI requirements: +- [layout_requirement] +- [interaction_requirement] +... + +Style: Clean, modern, professional SaaS interface with clear navigation. +``` + +## Stitch API 参数映射 + +| 用户参数 | Stitch API 参数 | 值映射 | +|----------|-----------------|--------| +| `--device desktop` | `deviceType` | `DESKTOP` | +| `--device mobile` | `deviceType` | `MOBILE` | +| `--device tablet` | `deviceType` | `TABLET` | +| `--model pro` | `modelId` | `GEMINI_3_1_PRO` | +| `--model flash` | `modelId` | `GEMINI_3_FLASH` | + +## PRD 回填逻辑 + +定位 PRD 中 `### 4.2 界面原型` 章节，替换内容为： + +```markdown +### 4.2 界面原型 + +> Stitch AI 自动生成原型，基于本 PRD 功能需求和交互设计。 + +**原型预览**： + +| 页面 | 截图 | 说明 | +|------|------|------| +| [screen_name_1] | ![screenshot](screenshot_url_1) | [描述] | +| [screen_name_2] | ![screenshot](screenshot_url_2) | [描述] | + +**Stitch 项目信息**： +```yaml +stitch_project_id: "" +screens: + - id: "" + name: "" + device: "" + - id: "" + name: "" + device: "" +model: "" +generated_at: "" +``` + +**编辑原型**：`/req prototype edit [REQ-ID] --prompt "修改说明"` +**生成变体**：`/req prototype variant [REQ-ID]` +``` + +## 异常处理 + +| 异常 | 处理 | +|------|------| +| 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` | +| PRD 无 UI 相关描述 | 警告并询问：`PRD 未包含明确的 UI 描述，是否基于功能需求自动推断？` | +| Stitch API 超时 | 提示：`Stitch 生成耗时约 1-2 分钟，请稍候...` 超过 3 分钟报错 | +| Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 | +| PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 | +| 已有原型元数据 | 询问：`已存在原型，是否覆盖？` | diff --git a/skills-req/req-review-plugin/.claude-plugin/plugin.json b/skills-req/req-review-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..e9fbd23 --- /dev/null +++ b/skills-req/req-review-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "req-review-plugin", + "description": "PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-req/req-review-plugin/skills/SKILL.md b/skills-req/req-review-plugin/skills/SKILL.md new file mode 100644 index 0000000..559f322 --- /dev/null +++ b/skills-req/req-review-plugin/skills/SKILL.md @@ -0,0 +1,124 @@ +--- +name: req-review +description: PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。当执行 /req review 或需要评审 PRD 文档时使用。 +--- + +# PRD 评审方法论 + +PRD 评审是需求流程的关键质量关卡。 + +## 评审流程 + +``` +PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论 +``` + +## 结构完整性检查 + +| 检查项 | 必须 | 说明 | +|--------|:----:|------| +| 基本信息 | ✓ | 编号、标题、日期、作者 | +| 需求背景 | ✓ | 为什么需要这个功能 | +| 目标用户 | ✓ | 面向的用户群体 | +| 功能描述 | ✓ | 详细功能需求 | +| 数据模型 | ✓ | 数据库表结构 | +| API 设计 | ✓ | RESTful 接口 | +| 验收标准 | ✓ | 验收条件 | +| 用户故事 | ○ | As a... I want... | +| 页面原型 | ○ | 如有 Stitch 原型则必审：布局合理性、与 PRD 描述一致性 | +| 非功能需求 | ○ | 性能、安全 | + +## 需求清晰度（SMART 原则） + +| 原则 | 检查点 | +|------|--------| +| **S**pecific | 描述是否具体明确 | +| **M**easurable | 是否有量化指标 | +| **A**chievable | 技术上是否可行 | +| **R**elevant | 是否与业务目标相关 | +| **T**ime-bound | 是否有时间范围 | + +**示例**： +- ❌ "用户可以搜索需求" +- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示" + +## 技术可行性 + +| 维度 | 评估内容 | +|------|----------| +| 技术栈兼容 | 现有栈是否支持 | +| 架构影响 | 是否需修改架构 | +| 第三方依赖 | 是否引入新依赖 | +| 性能影响 | 潜在性能问题 | +| 安全考量 | 安全风险 | + +## 数据模型验证 + +| 检查项 | 说明 | +|--------|------| +| 表结构 | 字段类型、约束、索引 | +| 关联关系 | 外键、多对多 | +| 命名规范 | 符合项目规范 | +| 扩展性 | 预留扩展字段 | +| 查询性能 | 常用查询有索引 | + +## API 设计审查 + +| 检查项 | 标准 | +|--------|------| +| RESTful | URL 用名词，HTTP 方法语义正确 | +| 响应格式 | `{success, data, message}` | +| 错误处理 | 明确的错误码 | +| 分页 | `?page=1&page_size=20` | +| 版本控制 | `/api/v1/...` | + +## 界面原型检查（如有） + +当 PRD 包含 Stitch 生成的原型时，评审人应检查： + +| 检查项 | 说明 | +|--------|------| +| 页面覆盖 | 原型页面覆盖了 PRD 中描述的主要功能 | +| 布局一致 | 布局与 PRD 功能描述一致（无遗漏关键元素） | +| 交互合理 | 导航、表单、操作按钮逻辑合理 | +| 数据展示 | 列表、详情、表单字段完整 | + +## 评审结论模板 + +**通过**： +``` +✅ PRD 评审通过 + +【结论】文档完整，需求清晰，方案可行，建议批准。 +【肯定】需求背景清晰、数据模型合理、API 规范 +【建议】（非阻塞）补充性能测试用例 +【评审人】xxx 【时间】2026-xx-xx +``` + +**驳回**： +``` +❌ PRD 评审驳回 + +【原因】 +1. 数据模型缺少索引 +2. API 缺少错误处理 +3. 搜索需求描述模糊 + +【修改要求】 +□ 补充索引设计 +□ 明确错误码 +□ 细化搜索实现 + +【驳回人】xxx 【时间】2026-xx-xx +``` + +## 常见驳回原因 + +| 类别 | 问题 | 建议 | +|------|------|------| +| 结构缺失 | 缺数据模型或 API | 补充技术设计 | +| 需求模糊 | 描述不具体 | 按 SMART 重写 | +| 边界不清 | 缺异常处理 | 补充边界条件 | +| 设计缺陷 | 模型/API 不合理 | 重新设计 | +| 范围过大 | 难以实现 | 拆分为多需求 | +| 验收不明 | 缺验收标准 | 补充验收条件 | diff --git a/skills-req/req-workflow-plugin/.claude-plugin/plugin.json b/skills-req/req-workflow-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..ab721c3 --- /dev/null +++ b/skills-req/req-workflow-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "req-workflow-plugin", + "description": "需求完整工作流。从创建到归档的完整流程、Hook 自动同步、测试环境流程。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-req/req-workflow-plugin/skills/SKILL.md b/skills-req/req-workflow-plugin/skills/SKILL.md new file mode 100644 index 0000000..17bdd38 --- /dev/null +++ b/skills-req/req-workflow-plugin/skills/SKILL.md @@ -0,0 +1,184 @@ +--- +name: req-workflow +description: 需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。 +--- + +# 需求完整工作流 + +从 PRD 到归档的完整流程。 + +## 完整流程概览（阶段化） + +``` +1. /req new → 创建需求 (draft) +2. req-prd 技能 → 编写 PRD（创建【评审】PRD 任务） +2.5 /req prototype → 生成 Stitch 原型（可选，有 UI 时推荐） +3. /req review → 提交评审 (pending) +4. /req review pass → 评审通过 (approved, delivery_stage=analysis) +5. /req next → 推进到 design/dev 阶段 +6. /req dev → 启动开发（创建【开发】任务, delivery_stage=dev） +7. req-dev 技能 → 编写开发文档 +8. /req next → 推进到 review 阶段 +9. /req cr → 代码评审（创建【代码评审】任务, delivery_stage=review） +10. /req next → 推进到 testing 阶段 +11. /req test → 测试验收（创建【测试】任务, delivery_stage=testing） +12. /req next → 推进到 staging 阶段 +13. /req deploy staging → 部署 staging（创建【部署】任务, delivery_stage=staging） +14. /req next → 推进到 released 阶段 +15. /req deploy prod → 部署生产（创建【部署】任务, delivery_stage=released） +16. /req done → 归档 (archived) +``` + +**每个阶段都有明确的任务、检查点和交付物，防止遗漏。** + +## 5 阶段文档 + +| 阶段 | 文档名 | 技能 | +|------|--------|------| +| PRD | 01-PRD.md | `req-prd` | +| 开发 | 02-开发设计.md | `req-dev` | +| 测试 | 03-测试报告.md | 自动生成 | +| 发布 | 04-发布记录.md | 自动生成 | +| 归档 | 05-生命周期总结.md | 自动生成 | + +> 注：Stitch 原型不单独编号，嵌入 01-PRD.md 的「4.2 界面原型」章节。 + +## Hook 自动同步 + +需求操作自动触发同步，无需手动执行： + +| 事件 | 触发操作 | +|------|----------| +| `requirement.created` | 同步到远程 | +| `requirement.approved` | 同步需求和任务 | +| `task.completed` | 同步任务状态 | +| `requirement.archived` | 最终同步 + 思源笔记 | + +**手动同步**（如需）： +```typescript +mcp__ai-proj__sync_requirement_to_remote(requirementId) +mcp__ai-proj__batch_sync_tasks_to_remote(taskIds) +``` + +## 测试环境流程 + +**必须按顺序执行，任何阶段失败后从本机重新开始**： + +``` +[本机] → 通过 → [预发布] → 通过 → [生产] + ↑ │ │ + └─────────────────┴──── 失败 ────┘ +``` + +| 环境 | 用途 | 验证方式 | +|------|------|----------| +| 本机 | 开发调试 | `go test ./...` | +| 预发布 | 集成测试 | API 验证 | +| 生产 | 最终验收 | API + 功能验证 | + +## 任务关联规范 + +创建任务时设置 `link_role` 并加阶段前缀： + +| link_role | 阶段前缀 | 所属阶段 | 权重 | +|-----------|----------|----------|------| +| prd | 【评审】 | analysis | 10% | +| design | 【评审】 | design | 5% | +| implementation | 【开发】 | dev | 50% | +| code_review | 【代码评审】 | review | 5% | +| test | 【测试】 | testing | 15% | +| deploy | 【部署】 | staging/released | 10% | +| documentation | 【文档】 | any | 5% | + +**进度计算**：按 link_role 权重统计已完成任务。 + +## 标准任务结构（阶段化） + +``` +需求 REQ-xxx +├── 📝 analysis 阶段 +│ └── 【评审】PRD: {需求标题} (linkRole: prd) +├── 📐 design 阶段 +│ └── 【评审】技术设计: {需求标题} (linkRole: design) +├── 💻 dev 阶段 +│ ├── 【开发-后端】{描述} (linkRole: implementation) +│ └── 【开发-前端】{描述} (linkRole: implementation) +├── 🔍 review 阶段 +│ └── 【代码评审】CR: {需求标题} (linkRole: code_review) +├── 🧪 testing 阶段 +│ └── 【测试】集成测试: {需求标题} (linkRole: test) +├── 🚀 staging 阶段 +│ └── 【部署】部署到 staging (singapore) (linkRole: deploy) +└── 🏁 released 阶段 + ├── 【部署】部署到 prod (tools_ai_proj) (linkRole: deploy) + └── 【验收】功能验收确认 (linkRole: documentation) +``` + +**命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。 + +## 环境配置 + +**双环境 MCP 配置**：区分开发测试和生产环境 + +```json +// ~/.claude/.mcp.json +{ + "mcpServers": { + "ai-proj-dev": { + "type": "stdio", + "command": "node", + "args": ["/path/to/mcp-task-bridge/dist/index.js"], + "env": { + "TASK_API_BASE": "http://localhost:8080/api/v1", + "TASK_API_TOKEN": "aiproj_pk_xxx...", + "NODE_ENV": "development" + } + }, + "ai-proj-prod": { + "type": "stdio", + "command": "node", + "args": ["/path/to/mcp-task-bridge/dist/index.js"], + "env": { + "TASK_API_BASE": "https://ai.pipexerp.com/api/v1", + "TASK_API_TOKEN": "aiproj_pk_xxx...", + "NODE_ENV": "production" + } + } + } +} +``` + +**环境使用指南**： + +| 环境 | 使用场景 | 工具前缀 | +|------|----------|----------| +| `ai-proj-dev` | 功能测试、流程验证、本地调试 | `mcp__ai-proj-dev__*` | +| `ai-proj-prod` | 正式需求管理、生产数据操作 | `mcp__ai-proj-prod__*` | + +**跨机器支持**： +- `ai-proj-dev` 支持 melbourne 和 adelaide 机器的本地环境（都是 localhost:8080） +- 无论在哪台开发机器上，都使用 `ai-proj-dev` 连接本地 API + +**项目配置**： +```json +// .claude/settings.local.json +{ + "env": { + "REQUIREMENT_PROJECT": "coolbuy-paas" + } +} +``` + +## 思源笔记集成 + +归档时自动同步 5 阶段文档到思源笔记： +- 路径：`需求管理/REQ-XXXX/` +- 文档：01-PRD.md ~ 05-生命周期总结.md + +手动同步：`/req sync-siyuan [REQ-ID]` + +## 邮件通知 + +发送邮件：`/req notify [REQ-ID] --type ` + +默认收件人：项目邮件组（见项目配置）