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

name, description

name	description
req-workflow	需求完整工作流。用于从创建到归档的完整流程、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     → 部署生产 + PDV 验收（健康检查 → E2E 验收 → released）
16. /req done       → 归档 (archived)

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

5 阶段文档

阶段	文档名	技能
PRD	01-PRD.md	req-prd
开发	02-开发设计.md	req-dev
测试	03-测试报告.md	自动生成
发布	04-发布记录.md	自动生成（含 PDV 验收章节）
归档	05-生命周期总结.md	自动生成

注：Stitch 原型不单独编号，嵌入 01-PRD.md 的「4.2 界面原型」章节。

Hook 自动同步

需求操作自动触发同步，无需手动执行：

事件	触发操作
requirement.created	同步到远程
requirement.approved	同步需求和任务
task.completed	同步任务状态
requirement.archived	最终同步 + 思源笔记

手动同步（如需）：

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 配置：区分开发测试和生产环境

// ~/.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

项目配置：

// .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>

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