---
name: rfc-iteration
version: 1.0.0
description: >
  RFC 驱动迭代工作流。复杂功能按 Phase 拆分，每个 Phase 开 testing issue
  带具体验证步骤，逐条验证通过才算完成。适用于需要多轮迭代验证的功能开发。
metadata:
  requiredTools: ["gitee", "gh"]
---

# RFC 驱动迭代工作流

复杂功能用 RFC 先行，Phase 拆分，testing issue 验证，用户视角驱动。

## 核心流程

```
RFC issue 创建（按用户视角拆 Phase）
  → 每个 Phase 开 testing issue（具体步骤 + checkbox）
  → 实现 Phase → 按 testing issue 验证 → close testing issue
  → 重复直到所有 Phase 完成
  → RFC issue 汇总 → close
```

## 何时使用

- 功能涉及多个模块或多轮迭代
- 需要明确的验证标准（不是"看起来能用"）
- 多人协作，需要对齐"完成"的定义
- Agent 需要自主验证功能是否正确

**不需要用的场景：** 一次性 bug fix、简单 CRUD、文档更新。

## Step 1：创建 RFC Issue

```bash
gitee issue create --repo <owner/repo> \
  --title "RFC-XXX: <功能名称>" \
  --body "## 背景
<为什么做>

## Phase 拆分

### Phase 1: <最小可验证功能>
- 验证目标：<用户视角>
- Testing issue: 待创建

### Phase 2: <扩展功能>
- 验证目标：<用户视角>
- Testing issue: 待创建

## 完成标准
- [ ] 所有 Phase 的 testing issue 已 close
- [ ] 线上验证通过"
```

### Phase 拆分原则

- **用户视角**：不是"KV list 返回正确"，而是"用户能看到消息列表"
- **最小可验证**：每个 Phase 1-2 小时能做完并验证
- **可独立验证**：每个 Phase 不依赖后续 Phase 就能验证
- **串行验证、可并行开发**

## Step 2：为每个 Phase 创建 Testing Issue

```bash
gitee issue create --repo <owner/repo> \
  --title "Phase 1 Testing: <验证目标>" \
  --body "## 验证目标
<用户视角的预期结果>

## 测试步骤

- [ ] **Step 1: <操作>**
  \`\`\`bash
  curl -X POST http://localhost:8000/api/xxx -d '{...}'
  \`\`\`
  **预期：** 返回 201，xxx 有效

- [ ] **Step 2: <操作>**
  \`\`\`bash
  curl -X GET http://localhost:8000/api/xxx
  \`\`\`
  **预期：** 返回 200，包含 yyy

## 验证完成标准
✅ 所有 checkbox 打勾
✅ 代码 review 通过
✅ CI 构建成功"
```

### Testing Issue 要求

每个测试步骤必须：
1. **可复制粘贴执行** — 给出具体的 curl/CLI 命令
2. **明确预期结果** — 状态码、返回值、页面状态
3. **可重复执行** — 不依赖特定的运行时状态（或明确说明依赖）

## Step 3：实现 → 验证循环

```bash
# 1. 创建分支
git checkout -b feat/rfc-xxx-phase-1

# 2. 实现功能（或让 coding agent 做）
# ...

# 3. 按 testing issue 逐条验证
curl -X POST http://localhost:8000/api/xxx -d '{...}'
# 检查返回值是否符合预期

# 4. 全部通过后提交
git commit -m "feat: RFC-XXX Phase 1 - <描述> (closes #<testing-issue>)"

# 5. 开 PR
gitee pr create --repo <owner/repo> \
  --title "feat: RFC-XXX Phase 1" \
  --head feat/rfc-xxx-phase-1 --base main \
  --body "## What
Phase 1 of RFC-XXX.

## Testing
All steps in #<testing-issue> verified ✅

Ref: #<rfc-issue>"
```

## Step 4：RFC Issue 汇总

所有 Phase 完成后，在 RFC issue 里 comment 汇总：

```
## 验证结果汇总

- ✅ Phase 1: 基础功能 (#<testing-1>)
- ✅ Phase 2: 扩展功能 (#<testing-2>)
- ✅ Phase 3: 边界情况 (#<testing-3>)

## 上线信息
- 部署版本: v1.2.3
- 上线时间: 2026-04-09 16:30
- 验证环境: production

Close RFC-XXX.
```

## Agent 自主验证模式

Agent 可以自动执行 testing issue 里的验证步骤：

```bash
# Agent 读取 testing issue → 逐条执行 → 报告结果
# 示例：Phase 1 验证

# Step 1
RESULT=$(curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:8000/api/xxx -d '{...}')
[ "$RESULT" = "201" ] && echo "Step 1: ✅ PASS" || echo "Step 1: ❌ FAIL (got $RESULT)"

# Step 2
BODY=$(curl -s http://localhost:8000/api/xxx)
echo "$BODY" | jq -e '.data | length > 0' && echo "Step 2: ✅ PASS" || echo "Step 2: ❌ FAIL"
```

失败时 Agent 应该：
1. 收集日志（`docker compose logs -f api-service | tail -50`）
2. 开 bug issue 并关联 testing issue
3. 修复后重新验证

## 反模式

| ❌ 不要 | ✅ 应该 |
|:--------|:--------|
| RFC 直接开发不拆 Phase | 按用户价值拆 Phase |
| Testing issue 只写"测试功能X" | 具体步骤 + curl 命令 + 预期结果 |
| 代码写完才想验证 | 先写 testing issue 再写代码 |
| 技术指标驱动 | 用户体验驱动 |
| 一个 testing issue 跨多功能 | 一个 Phase 一个 testing issue |

## 参考案例

小橘在 Uncaged RFC-006（Capability Deployment）中用此流程，3.5 小时完成 4 个 Phase 的全流程验证。

来源：[oc-wiki RFC 驱动迭代工作流](https://shazhou-ww.github.io/oc-wiki/shared/rfc-iteration-workflow/)