---
name: subagent-driven-development
description: "Optional executor for large approved plans (many mostly-independent tasks): delegate each task to a fresh Claude subagent, run an automated quality gate per task, and one independent Codex review before merge. For small or tightly-coupled plans, implement directly instead."
---

# Subagent-Driven Development

## 何时使用

- **适用**: 已有批准的 plan、任务多(≥3)且大体相互独立、值得为每个任务开独立上下文。
- **不适用**: 小计划、任务强耦合、探索性工作——直接实现更省更好。

结构:Claude 主会话做控制器;每个任务派一个**全新** Claude subagent 实现;任务完成跑**自动质量门**;全部任务完成后、合并前做**一次** Codex 独立审查(跨模型,消除自评盲区)。

## 流程

### 1. 读计划,建任务清单

读一遍 plan,把每个任务的**全文**与上下文提取出来,进 TodoWrite。之后不再让 subagent 去读 plan 文件——派发时把任务全文直接贴进 prompt。

若项目已建 graphify 知识图谱(`graphify-out/` 存在),先 `/graphify . --update` 刷新;未建图则跳过,不阻断。

### 2. 派发实现 subagent(每任务一个,全新上下文)

用 `Agent` 工具(`subagent_type=general-purpose`),prompt 用 `./claude-implementer-prompt.md` 模板填充(任务全文、上下文、绝对路径)。**记下 agentId**。

- 同一任务的返修一律 `SendMessage(to: agentId)` 发回原 subagent(保留其上下文);只有下一个任务才开新 subagent。
- subagent 以结构化 `STATUS` 块收尾:`DONE` → 进质量门;`NEEDS_CONTEXT` → 补上下文继续;`BLOCKED` → 评估(补上下文/拆任务/计划有误则上报人类);缺失 STATUS 块按 `BLOCKED` 处理。

### 3. 自动质量门(每任务,机器判定)

```bash
conda run -n PolyGateway ruff format --check <changed_files>
conda run -n PolyGateway ruff check <changed_files>
conda run -n PolyGateway radon cc <changed_files> -n C -s   # C 级及以下复杂度即失败
conda run -n PolyGateway pytest tests/ -x -q
# 结构检查: 无裸 except / except Exception: pass;核心文件不超 200 行
```

失败 → 汇总工具输出,`SendMessage` 发回原 subagent 修,最多 2 轮,仍失败则上报人类。仅格式问题可由控制器直接 `ruff format` 修掉。测试超 30s 的在 tmux 里跑(`tmux new-session -d -s sdd-task<N> "<cmd>"`),便于人类 attach。

**不信任 subagent 自述**: 标记任务完成前,控制器亲自看 `git diff` 确认变更真实存在。

### 4. 合并前一次 Codex 独立审查(整分支)

全部任务完成、质量门全绿后,用 `/codex:rescue --fresh --wait` 按 `./merge-reviewer-prompt.md` 做**一次**只读审查,范围是整条分支(所有 SHA + plan 全文),一次覆盖:spec 符合性(缺失/多余/误解)、跨任务集成问题、功能质量、明显的过度设计。

- Critical/Important 问题 → 发回对应 subagent(或自己)修复,复审至清零。
- 前置:Codex 插件可用(`/codex:setup` 报 ready);审查模型用 `.codex/config.toml` 的默认强配置。Codex 不可用时,降级为派一个全新上下文的 Claude verifier subagent 按同一 prompt 审(见 `verification-before-completion`)。

### 5. 收尾

`/graphify . --update`(若在用),然后交给 `finishing-a-development-branch`。

## 纪律(约束点)

- 连续执行,任务间不停下来找人类确认;只有 BLOCKED 无解、真歧义、全部完成三种停法。
- 每任务提交留痕;严禁把多个任务squash成一坨再审。
- 审查不接受"差不多就行":Critical/Important 清零才合并。

## Companion files

- `./claude-implementer-prompt.md` — 实现 subagent 的 prompt 模板。
- `./merge-reviewer-prompt.md` — 合并前一次性 Codex 审查的 prompt 模板。

## Wiki 留痕(`research-wiki/` 存在时)

产生可复用实现知识或有价值审查意见的任务,记 plan/review 实体并连边(工具 `.claude/tools/research_wiki.py`,类型 `implements`/`informs`),纯机械改动跳过。