# Subagent 并行执行指引

> 适用场景：`analyze-task` 检测到大任务（isLargeTask=true）且单个 Agent 上下文不足以串行完成所有子任务。
> **另外**：`validate` 阶段会固定尝试派发独立 **review** subagent（`validate-review`），与是否大任务无关，用于审查与实现分离。

## 何时使用 Subagent

1. `analyze-task` 返回 `isLargeTask=true`
2. 当前 Agent 上下文使用率 > 75%（≥150K / 200K，可由 `compress-context` 检测；压缩目标约保留 30%，AC-ID 全文保留）
3. 任务涉及多个模块（API + 组件 + 页面），串行执行会导致上下文溢出
4. **`validate` 自动**：主流程在机械门禁前派发 `validate-review`（新进程、只审不修）

## 前提条件

- 已运行 `analyze-task --run-id <runId>` 生成 `06-Subagent执行计划.md`
- 已运行 `compress-context --run-id <runId>` 确保恢复指引已生成
- 已安装目标 Agent CLI（claude / cursor / codex / openclaw）

## 执行命令

### 查看状态
```bash
npx sdd-flow-kit execute-subagent --run-id <runId> --status
```

### 执行下一个可执行任务（推荐逐步执行）
```bash
npx sdd-flow-kit execute-subagent --run-id <runId> --next --agent claude-code
```

### 执行指定任务
```bash
npx sdd-flow-kit execute-subagent --run-id <runId> --task-id implement-api --agent claude-code
```

### 执行全部任务（按依赖拓扑排序，逐层并行）
```bash
npx sdd-flow-kit execute-subagent --run-id <runId> --all --agent claude-code
npx sdd-flow-kit execute-subagent --run-id <runId> --all --agent claude-code --max-parallel 2
```

### 预演模式（不实际执行，仅生成 prompt）
```bash
npx sdd-flow-kit execute-subagent --run-id <runId> --all --agent claude-code --dry-run
```

## validate 独立审查（P0）

`npx sdd-flow-kit validate --change <name>` 在 prd-review / e2e 等检查之前会：

1. 新进程启动 review subagent（`taskId=validate-review`）
2. 注入压缩 PRD / 05 / 02 等上下文；**不**注入实现对话历史
3. **禁止**修改 `src/**`、`e2e/**` 业务代码；只写：
   - `openspec/PRD/<runId>/.subagents/validate-review/RESULT.md`
   - `openspec/PRD/<runId>/.subagents/validate-review/RESULT.json`（推荐）
   - 标记：`.validate-review.json`
4. 存在开放 **P0/P1** → `verdict=fail` → **validate 硬失败**，回退实现路径修复（审查员不得自己改代码）

### 跳过 / 必选

| 环境变量 | 作用 |
|---------|------|
| `OPSX_SKIP_VALIDATE_REVIEW=1` 或 `SDD_SKIP_VALIDATE_REVIEW=1` | 跳过独立审查 |
| `OPSX_VALIDATE_REVIEW_REQUIRED=1` | 无 Agent CLI / 无 RESULT 时也硬拦（默认软跳过） |

### RESULT 合约摘要

```json
{
  "verdict": "pass | fail",
  "openIssues": [
    { "id": "R-001", "severity": "P0", "acId": "AC-01", "evidence": "...", "expected": "..." }
  ]
}
```

## 上下文注入机制

每个 subagent 启动时会自动注入：

| 注入内容 | 来源 | 说明 |
|---------|------|------|
| 压缩 PRD 概要 | `.context-compression/prd-summary.md` | 优先使用压缩版，否则截取原文 |
| 压缩技术文档概要 | `.context-compression/tech-doc-summary.md` | 优先使用压缩版，否则截取原文 |
| 本任务相关 AC | `05-验收清单.md`（按 acScope 过滤） | 仅包含该任务负责的 AC |
| 本任务改动点 | `02-改动点清单.md`（按 fileScope 过滤） | 仅包含该任务范围内的文件 |
| 恢复指引 | `.context-compression/recovery-guide.md` | 关键决策、待确认项、AC 进度 |
| 前置任务结果 | `.subagents/<taskId>/RESULT.md` | 依赖任务的执行结果 |

## 执行结果

- 每个 subagent 结果写入 `openspec/PRD/<runId>/.subagents/<taskId>/RESULT.md`
- 批量执行汇总写入 `openspec/PRD/<runId>/.subagents/BATCH-RESULT.md`
- 执行日志写入 `openspec/PRD/<runId>/.subagents/<taskId>/EXECUTION-LOG.md`
- validate 审查：`.subagents/validate-review/` + `.validate-review.json`

## 子任务与 delivery-pipeline 的关系

**每个子任务不单独跑 delivery-pipeline**。流程：

1. 主 Agent 检测到大任务 → `analyze-task`
2. 分派 subagent 执行各子任务（各自 TDD Red→Green；**review 类型除外**）
3. 所有 subagent 完成 → 读取 `.subagents/BATCH-RESULT.md` 汇总
4. 主 Agent 运行 `validate`（内含独立 review）+ `delivery-pipeline` 做最终验证

## 失败重试策略

- 单个 subagent 失败不会阻塞同层其他任务
- 失败任务的下游任务自动标记为 skipped
- 可单独重新执行失败任务：
  ```bash
  npx sdd-flow-kit execute-subagent --run-id <runId> --task-id <failed-task-id> --agent claude-code
  ```
- 建议最多重试 3 次，超过后需人工介入
- validate 独立审查失败：由**实现路径**修代码后重跑 `validate`，不要在 review 会话内改 `src`

## 环境变量

| 变量 | 说明 |
|------|------|
| `SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN` | 设为 `1` 允许 claude-code 自动执行 |
| `SDD_FLOW_KIT_ENABLE_CURSOR_AUTORUN` | 设为 `1` 才允许创建独立 Cursor CLI Agent；默认由当前 IDE 会话执行，CLI 失败不影响 SDD run 初始化 |
| `SDD_FLOW_KIT_ENABLE_AGENT_AUTORUN` | 设为 `0` 禁止所有 agent 自动执行 |
| `OPSX_SKIP_VALIDATE_REVIEW` | `1` 跳过 validate 独立审查 |
| `OPSX_VALIDATE_REVIEW_REQUIRED` | `1` 审查不可用时硬拦 validate |