name: orchestration-patterns description: 用于长运行任务的代理编排模式。实现基于证据的交付和迭代代理循环。在管理多步工作、协调工作流或编排PR工作流时使用。
编排模式技能
目的
为协调复杂、长运行任务而制定基于证据的交付和迭代代理循环。这些模式确保可验证的进度和智能升级。
当此技能适用时
- 编排多步实施任务
- 管理跨多步的工作
- 运行需要检查点的长运行会话
- 准备合并PR（强制QA门）
- 协调团队交接
代理循环
核心理念: “迭代直到成功或阻塞，然后升级。”
┌─────────────────────────────────────────────────────────┐
│ 代理循环（针对每个任务） │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. 目标定义 │
│ └─ 清晰的验收标准（来自规范/工单） │
│ │
│ 2. 模式发现 │
│ └─ 搜索代码库、文档、先前会话 │
│ └─ 使用：模式发现技能（自动调用） │
│ └─ 或：/search-pattern 进行显式代码搜索 │
│ │
│ 3. 迭代执行循环： │
│ ┌─────────────────────────────────────────────┐ │
│ │ 实施方法 │ │
│ │ ↓ │ │
│ │ 运行验证（yarn ci:validate） │ │
│ │ ↓ │ │
│ │ 如果通过 → 继续到证据 │ │
│ │ 如果失败 → 分析错误，调整，重复 │ │
│ │ 如果阻塞 → 使用上下文升级 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ 4. 证据附加 │
│ └─ 将证明附加到Linear（见下方模板） │
│ │
│ 5. QA门（合并前强制） │
│ └─ PR的独立审核 │
│ │
└─────────────────────────────────────────────────────────┘
基于证据的交付
核心原则: “所有工作都需要可验证的证据 – 没有‘相信我，它有效’”
证据类型
| 类型 | 证明什么 | 示例 |
|---|---|---|
| 测试结果 | 代码按预期工作 | yarn ci:validate 输出 |
| 截图 | UI更改正确 | 前后对比 |
| 命令输出 | 操作完成 | 构建日志，迁移日志 |
| QA报告 | 独立验证 | QA验证Markdown |
| 会话ID | 完整审计轨迹可用 | 会话引用 |
阶段证据要求
| 阶段 | 所需证据 | Linear模板 |
|---|---|---|
| 开发 | 测试结果，命令输出 | 开发证据模板 |
| 测试环境 | 用户验收测试或N/A + 原因 | 测试环境模板 |
| 完成 | QA报告，合并确认 | 完成证据模板 |
合并前QA门
强制: 在合并任何PR之前，执行独立审核。
为什么QA门重要
- 关注点分离: QA验证但不编写产品代码
- 独立验证: 捕捉实施者遗漏的内容
- 偏见预防: 对提交信息、模式有新的视角
- Linear中的证据: QA将最终证据 + 裁决发布到Linear（记录系统）
QA审核清单
## QA审核 - PR #XXX 对应 {{TICKET_PREFIX}}-YYY
### 提交信息验证
- [ ] 主题行中有工单引用
- [ ] 正确格式：`type(scope): description [{{TICKET_PREFIX}}-XXX]`
### 代码模式验证
- [ ] 使用RLS上下文助手（无直接Prisma）
- [ ] 遵循命名约定
- [ ] 文件结构匹配模式
### CI状态
- [ ] 所有检查通过
- [ ] 无新增lint警告
### 证据验证
- [ ] 开发证据附加到Linear
- [ ] 验收标准已处理
### 裁决
- [ ] 批准合并
- [ ] 要求更改（下方列出）
QA输出位置
所有QA报告发送到: docs/agent-outputs/qa-validations/{{TICKET_PREFIX}}-{number}-qa-validation.md
升级模式
何时升级
| 条件 | 升级到 | 包含内容 |
|---|---|---|
| 阻塞超过4小时 | TDM | 完整上下文，尝试过的方法 |
| 架构不明确 | ARCHitect | 选项，权衡 |
| 跨团队依赖 | TDM | 哪些团队，什么被阻塞 |
| 安全问题 | SecEng | 具体风险，证据 |
升级模板
**需要升级**
**阻塞于**: [具体阻塞项]
**尝试过的方法**:
1. [你尝试了什么]
2. [你尝试了什么]
**上下文**:
- 工单: {{TICKET_PREFIX}}-XXX
- 会话ID: [如果可用]
- 阻塞时间: X小时
**请求**: [具体需求 – 你需要什么？]
长运行任务检查点
对于跨越多个步骤或会话的任务：
检查点模式
每10-15步骤:
1. 更新进度与当前状态
2. 如果接近限制，总结状态
3. 如果需要交接，提供继续上下文
在会话边界:
1. 总结已完成的工作
2. 列出剩余项目
3. 记录任何阻塞
4. 将证据附加到Linear
状态保存
**会话检查点**
**已完成**:
- [x] 任务1
- [x] 任务2
**进行中**:
- [ ] 任务3（在步骤X）
**剩余**:
- [ ] 任务4
- [ ] 任务5
**阻塞**: [如果有]
**下一步动作**: [具体下一步]
编排工作流示例
# 功能实施的完整工作流:
1. /start-work {{TICKET_PREFIX}}-XXX
└─ 同步到主分支，创建分支，设置上下文
2. 模式发现（技能自动调用或使用 /search-pattern）
└─ 在实施前找到相关模式
3. [使用代理循环实施]
├─ 实施
├─ 验证（yarn ci:validate）
├─ 根据需要调整
└─ 重复直到通过
4. /pre-pr
└─ 完整验证清单
5. 创建PR并附带证据
6. [QA门 – 强制]
└─ 执行QA审核
└─ 修复任何阻塞问题
└─ 提交QA报告
7. 合并（仅QA批准后）
8. /end-work
└─ 更新Linear，清理
参考
- AGENT_WORKFLOW_SOP.md: 完整代理工作流文档
- CONTRIBUTING.md: 工作流要求
- linear-sop skill: Linear的证据模板
要避免的反模式
| 反模式 | 为什么不好 | 替代做法 |
|---|---|---|
| 跳过QA审核 | 遗漏提交信息问题 | 始终执行合并前QA审核 |
| Linear中无证据 | 无审计轨迹 | 每个阶段附加证据 |
| 忽略CI失败 | 损坏代码进入主分支 | 在代理循环中修复，不跳过 |
| 不检查强制推送 | 可能丢失团队成员更改 | 使用 --force-with-lease |
| 阻塞时继续 | 浪费时间，无进展 | 使用上下文升级 |