John Qiu
712063071c
skills/ → skills-dev(9), skills-req(10), skills-ops(4), skills-integration(8), skills-biz(4), skills-workflow(7) generate-marketplace.py 改为自动扫描所有 skills-* 目录。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
199 lines
6.9 KiB
Markdown
199 lines
6.9 KiB
Markdown
---
|
||
name: req-workflow
|
||
description: 需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。
|
||
---
|
||
|
||
# 需求完整工作流
|
||
|
||
从 PRD 到归档的完整流程。
|
||
|
||
## 需求创建环境选择
|
||
|
||
> **重要**：正式需求应直接在**生产环境** (`mcp__ai-proj-prod__*`) 创建。
|
||
> 仅在功能测试、流程验证时使用开发环境 (`mcp__ai-proj-dev__*`)。
|
||
> 如果在开发环境创建了需求后同步到生产，`due_date`、`reviewer_id`、`allow_self_approve` 等字段会丢失，需手动补充。
|
||
|
||
## 完整流程概览（阶段化）
|
||
|
||
```
|
||
1. /req new → 创建需求 (draft)
|
||
2. req-prd 技能 → 编写 PRD（创建【评审】PRD 任务）
|
||
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 | 自动生成 |
|
||
|
||
## 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 | ✅ | 正常同步 |
|
||
| project_id | ✅ | 正常同步 |
|
||
| **due_date** | ❌ | **不会同步**，需手动通过 REST API 在目标环境补充 |
|
||
| reviewer_id | ❌ | 不会同步 |
|
||
| allow_self_approve | ❌ | 不会同步 |
|
||
|
||
> **经验教训**（2026-02-20）：`sync_requirement_to_remote` 不同步 `due_date` 字段。同步后务必在目标环境验证并手动补充缺失字段。
|
||
|
||
## 测试环境流程
|
||
|
||
**必须按顺序执行，任何阶段失败后从本机重新开始**：
|
||
|
||
```
|
||
[本机] → 通过 → [预发布] → 通过 → [生产]
|
||
↑ │ │
|
||
└─────────────────┴──── 失败 ────┘
|
||
```
|
||
|
||
| 环境 | 用途 | 验证方式 |
|
||
|------|------|----------|
|
||
| 本机 | 开发调试 | `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 <prd|dev|test|deploy|archive>`
|
||
|
||
默认收件人：项目邮件组（见项目配置）
|