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-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)

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

连续推进（continuous）模式

默认按连续模式推进：每个阶段「做事 → 留证据 → 写 checkpoint → 自动 /req next → 下一阶段」，不在阶段边界停发问。适合 Codex 等无人值守 agent。

• 自动终点：staging 部署成功 + 冒烟验证通过；生产发布属硬门禁，必须人工授权。
• 硬门禁（停）：需求方案确认、PRD 评审通过、生产发布授权、force 放行、密钥/权限缺失、需求范围变更。
• 软门禁（不停）：讨论摘要确认、部署范围确认 —— 按默认策略继续，把「待用户确认」写入 checkpoint / REQ 备注。
• checkpoint：每次阶段切换写 .ai-proj/req-<id>.state.json（stage / evidence / next_command / blockers）；新会话先读它 → 复核 evidence → 从 next_command 继续。
• staging 段：部署路径读目标项目 AGENTS.md 的 staging 约定，不在本技能写死。
• 停止只输出五段：卡点 / 原因 / 已做到哪 / 下一步命令 / 需要谁确认。

规则细节（门禁分级表、checkpoint schema、恢复协议、反例）见 references/continuous-mode.md。

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	最终同步 + 思源笔记

手动同步（如需）：

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>

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

---

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。