implementation-workflow git:20260924.4f0fdb9A

Immutable. This exact content never changes and is served at /api/v1/blob/311231421e420078.

---
name: implementation-workflow
description: 实施编排工作流。当用户要求实现功能、修复 Bug、重构代码、补充测试、拆分开发任务、并行编码或按质量门完成开发时使用。负责评估任务、拆分依赖、调度 implementer，并按风险选择性调用 diff-reviewer 和两个审计 agent（complexity-auditor、mutation-auditor）。
user-invocable: true
---

# 实施编排工作流

## 目标

把编码任务安全推进到可验证完成：

```text
理解 → 评估 → 拆分 → 判断并行/串行 → 派发 implementer
→ 集成 → 统一验证 → 按风险审计 → 汇总
```

你负责**编排和决策**。不要把工作机械地交给子 agent，也不要为了并行而并行。

## 何时使用

**使用本工作流**：多模块/多目录改动、前后端或多服务协同、新增接口或数据模型、复杂重构、多个独立可并行的交付物、用户明确要求并行或质量审计。

**不要使用**：文档、注释、简单配置、单文件低风险修复、机械版本号调整、小范围测试补充。
这些由主 Agent 直接完成，或只派发一个 `implementer`。

## 四个质量角色

| Agent / Skill | 职责 | 边界 |
|---|---|---|
| `implementer` | 阅读代码、修改实现、编写测试、运行局部验证 | 只改任务范围内文件 |
| `diff-review` + `diff-reviewer` | Correctness / Standards / Spec 三轴代码评审 | **只报告，不改码；不依赖宿主内置 review** |
| `complexity-auditor` | 复杂度与覆盖率风险审计 | **只报告，不改码** |
| `mutation-auditor` | 突变测试与测试有效性审计 | **只报告，不改码** |

职责细节由各自 agent 和 skill 承载，本工作流只负责编排。

## 执行流程

### 1. 理解任务

读取项目指令文件（`AGENTS.md`、`CLAUDE.md`）、需求或 Spec、相关代码与测试、构建与测试命令、当前 git 状态。

输出简短任务理解：目标、涉及模块、约束、验收标准、暂不处理的范围。

**关键歧义先向用户确认**，不要把歧义扩散给多个子 agent。

若大型改动的主要阻力来自模块边界尚不清楚，可建议用户**开工前**单独运行 `architecture-scout`；等待候选被选定、设计获确认后再拆实施任务。不要在每次实施后自动进行全仓架构扫描。

### 2. 评估规模与风险

| 规模 | 特征 | 执行方式 |
|---|---|---|
| small | 单文件或单模块 | 主 Agent 或 1 个 implementer |
| medium | 多文件、单一模块 | 1 个 implementer，按需审计 |
| large | 多模块、跨端、多交付物 | 拆分后并行 implementer |

风险看**行为影响**而非改动行数。权限、状态机、金额、规则引擎、核心数据流属于高风险。

### 3. 拆分任务

每个子任务写成一个自包含任务卡，格式见 `references/task-card-template.md`。

拆分原则：

- 一个任务一个可验收结果
- 同一文件只由一个并行任务负责
- 共享接口、数据模型、公共类型先确定，再并行实现使用方
- 按业务结果切分，不按目录机械切分

细节见 `references/task-decomposition.md`。

### 4. 判断并行还是串行

**只有同时满足**以下条件才并行：无未解决依赖、不修改同一文件、不共享冲突状态、各有独立验收标准、并行收益大于调度与集成成本。

无法确认是否安全时**默认串行**。

判断规则与反例见 `references/parallel-execution.md`。

### 5. 派发 implementer

每个任务卡必须包含：目标、已确认的设计约束、允许修改范围、禁止修改范围、验收标准、验证命令、返回格式。

并行派发时保留任务编号，等全部返回后再进入集成。子 agent 不得自行改写任务边界。

**若运行环境没有可用的 `implementer` 子 agent，由主 Agent 串行执行同一任务卡，不要假装已完成委派。**

### 6. 集成检查

并行任务返回后，主 Agent 亲自检查：

1. 改动是否落在声明范围内
2. 是否有同文件冲突或互相覆盖
3. 公共接口、命名、错误处理是否一致
4. 是否遗漏任务之间的集成代码
5. 测试是否覆盖真实集成路径
6. 子 agent 报告的验证是否实际执行且结果可信

**子 agent 的「已完成」不等于整体已完成。**

### 7. 统一验证

按项目实际工具运行单元测试、集成测试、Lint、类型检查、构建，必要时端到端测试。

记录实际执行的命令与结果。失败优先修复，不绕过、不伪造。

失败归属判断：子任务内部错误 → 重新派发原 implementer；集成冲突 → 主 Agent 修复；测试或环境问题 → 标记为环境阻塞。

### 8. 选择性质量审计

**不要每次都运行全部审计角色**，按风险选择。集成检查和统一验证通过后，再按下表决定是否调用 `diff-review`、`complexity-auditor` 和 `mutation-auditor`。

| 变更类型 | diff-review | complexity-auditor | mutation-auditor |
|---|---|---|---|
| 文档 / 配置 / 样式 | 按需：检查契约、约定是否一致 | 跳过 | 跳过 |
| 简单字段 / 小修复 | 通常跳过 | 跳过 | 跳过 |
| 普通业务逻辑 | 建议运行 | 视复杂度 | 通常跳过 |
| 复杂逻辑 / 大型重构 | 建议运行 | 建议运行 | 视测试情况 |
| 权限 / 状态机 / 金额 / 规则 | 建议运行 | 建议运行 | 有工具时建议运行 |
| 公共 API / 跨模块契约变更 | 建议运行 | 视复杂度 | 视测试情况 |
| 测试专项 | 按需 | 可选 | 有工具时优先运行 |

**跳过不是遗漏**：每个未调用的审计角色，在最终报告里说明跳过原因。工具缺失、没有可靠基线或找不到 spec 时如实降级，不得为了跑完流程安装工具、伪造 finding 或把“未验证”说成“通过”。

完整调用与跳过条件见 `references/quality-gates.md`。评审和审计角色只报告，修复由 `implementer` 执行；修复后重新运行相关验证，但**不要求反复评审直到零 finding**。

### 9. 汇总

报告包含：任务拆分与完成状态、执行方式（串行/并行）、修改内容、实际验证命令与结果、三个质量角色的运行/跳过/降级结论、未解决问题与环境阻塞。

## 核心原则

1. **并行不是默认行为** —— 只有独立任务才并行。
2. **任务必须有边界** —— 没有文件范围和验收标准，不派发并行任务。
3. **主 Agent 负责集成** —— 委派完成不等于任务完成。
4. **审计按风险调用** —— 不为了流程完整运行昂贵工具。
5. **不为了并行而拆分** —— 调度与集成成本高于收益时直接执行。

## References

- `references/task-decomposition.md` —— 拆分方法、依赖识别、文件边界
- `references/parallel-execution.md` —— 并行条件、必须串行的场景、集成清单
- `references/quality-gates.md` —— 三个审计角色的调用与跳过条件
- `references/task-card-template.md` —— 子任务卡模板
- `skills/diff-review/SKILL.md` —— 三轴代码评审入口