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

---
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-design 技能  → 编写开发设计文档
7.5 /req ci         → CI 质量门禁检查与自动修复（PR 提交后执行）
8. /req next        → 推进到 review（需 quality_gate 门禁证据）
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     → 部署生产 + PDV 验收（健康检查 → E2E 验收 → released）
16. /req done       → 归档 (archived)
```

**每个阶段都有明确的任务、检查点和交付物，防止遗漏。**

## 5 阶段文档

| 阶段 | 文档名 | 技能 |
|------|--------|------|
| PRD | 01-PRD.md | `req-prd` |
| 开发 | 02-开发设计.md | `req-design` |
| 测试 | 03-测试报告.md | 自动生成 |
| 发布 | 04-发布记录.md | 自动生成（含 PDV 验收章节） |
| 归档 | 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 验证 |
| 生产 | 最终验收 | 健康检查 + PDV E2E 验收（页面可达、菜单可见、API 连通） |

## 任务关联规范

创建任务时设置 `link_role` 并加阶段前缀：

| link_role | 阶段前缀 | 所属阶段 | 权重 |
|-----------|----------|----------|------|
| prd | 【评审】 | analysis | 10% |
| design | 【评审】 | design | 5% |
| implementation | 【开发】 | dev | 50% |
| code_review | 【代码评审】 | review | 5% |
| test | 【测试】 | testing | 15% |
| deploy | 【部署】 | staging/released | 5% |
| verification | 【验收】 | released | 5% |
| 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)
    └── 【验收】PDV: {需求标题}                     (linkRole: verification)
```

**命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。

## 环境配置

**双环境 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 <prd|dev|test|deploy|archive>`

默认收件人：项目邮件组（见项目配置）

---

## Memory 隔离规则（强制，源自 devflow-claude 借鉴）

**规则：涉及生命周期文档产出（PRD / 设计 / 测试报告 / 部署报告 / 生命周期总结）时，禁止受 auto-memory 影响产出物结构。**

### 禁止行为
1. 不得跳过或合并 5 阶段文档的任一阶段（01-PRD ~ 05-生命周期总结）
2. 不得因 memory 里的历史项目跳过章节
3. 不得因 memory 中的"精简偏好"缩减文档结构
4. 不得读取 `~/.claude/projects/*/memory/` 生成这些文档的正文

### 允许行为
- memory 可影响**交互风格**（如提问详略）
- memory 可影响**通知习惯**（如默认 CC 某人）
- memory 可影响**触发时机**（如归档时是否自动同步思源）

### Why
需求生命周期文档对应审计和交付物。结构变化会破坏检索、对标、复盘。memory 应调节"怎么聊"，不应调节"最终文档长什么样"。

**参考**：devflow-claude `plugins/req/commands/_common.md` 同名规则，以及本项目 REQ-20260416-0017。