子代理驱动开发（SDD）模式

子代理驱动开发（SDD）模式

学习目标

读完本章后，你将能够：

• 理解 SDD 模式的核心原则：新鲜子代理 per task + 两阶段审核
• 设计按任务复杂度路由到不同模型的策略
• 处理子代理的四种状态报告（DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED）
• 对比 SDD 与并行会话执行、手动执行的适用场景

前置知识

建议先阅读：

• 多 Agent 路由与隔离 — 理解 Agent 隔离的基本维度
• Skill 驱动的 Agent 行为编排 — 理解 Skill 如何控制 Agent 行为

---

核心模式

为什么用子代理而非单 Agent 连续执行

单 Agent 在长会话中面临上下文膨胀和上下文污染两个问题：

• 上下文膨胀：随着实现推进，会话历史越来越长，压缩/摘要会丢失关键细节
• 上下文污染：前一个任务的决策和代码会不自觉影响后一个任务

SDD 模式的解决方式：每个任务分派全新的子代理，由控制器精心构造其指令和上下文。子代理只获得完成任务所需的最小信息，不受之前任务的污染。控制器自身的上下文只用于协调，不用于实现。

两阶段审核架构

关键顺序约束：必须先通过规格合规审核，才能进入代码质量审核。颠倒顺序会导致质量审核在规格尚未满足时浪费精力。

规格合规审核检查：代码是否实现了计划要求的全部内容？是否实现了计划未要求的内容？（防止过度工程）

代码质量审核检查：实现是否健壮？是否有安全隐患？是否有代码异味？测试是否充分？

模型路由策略

SDD 模式为不同角色选择不同的模型，以平衡成本、速度和质量：

角色	模型选择	理由
实现（1-2 文件，规格完整）	最快/最便宜的模型	机械实现任务，不需要深度推理
实现（多文件协调，集成）	标准模型	需要理解跨文件依赖
架构 / 设计 / 审核	最强模型	需要广泛理解和判断力

复杂度信号：

• 触及 1-2 个文件 + 完整规格 → 便宜模型
• 触及多文件 + 集成考量 → 标准模型
• 需要设计判断或广泛代码库理解 → 最强模型

子代理状态处理

实现子代理报告四种状态之一：

状态	含义	控制器动作
DONE	任务完成	进入规格合规审核
DONE_WITH_CONCERNS	完成但有疑虑	先阅读疑虑内容，判断是否影响正确性或范围，再决定是否进入审核
NEEDS_CONTEXT	缺少必要信息	提供缺失上下文，重新分派
BLOCKED	无法完成任务	评估阻塞原因：上下文问题 → 补充上下文重试；需要更多推理 → 升级模型；任务过大 → 拆分子任务；计划错误 → 上报人类

关键原则：永远不要忽略子代理的失败报告。如果子代理说它卡住了，一定有什么需要改变。不要用相同模型重试相同指令。

SDD vs. 其他执行模式

维度	SDD	并行会话执行	手动执行
会话	同一会话内	跨会话	同一会话
上下文	每个子代理独立	每个会话独立	共享，持续污染
审核	自动两阶段	手动检查点	无审核
速度	快（无需人类介入）	中等（需要会话切换）	慢
安全性	高（审核门控）	中等	低
成本	较高（每任务 3 次子代理调用）	中等	最低

选择指南：

• 任务 mostly 独立 + 同一会话 → SDD
• 任务紧密耦合 → 手动执行或 brainstorm 后再拆分
• 需要跨会话并行 → 并行会话执行

陷阱与对策

陷阱	表现	对策
上下文泄漏	控制器把整个会话历史传给子代理	只构造任务所需的最小上下文，包含场景设定和文件范围
跳过审核顺序	先做质量审核再做规格审核	在 Skill 中用 flowchart 和 Red Flags 强制执行顺序
子代理读取计划文件	子代理花费 token 阅读完整计划	控制器预先提取任务全文直接注入，不让子代理读文件
并行分派冲突	同时分派多个实现子代理编辑相同文件	严格串行分派，一次只一个任务在实现中
审核循环无限	审核者反复拒绝，实现者反复修复失败	设定最大循环次数（通常 3 次），超限后控制器介入分析

设计取舍

为什么不用并行实现子代理？

并行执行看似更快，但存在文件编辑冲突的风险。SDD 选择严格串行：一个任务完成后才分派下一个。这在多文件修改时尤为重要——前一个任务的提交可能改变后一个任务的基线。

为什么每个任务需要两个审核子代理而非一个？

合并审核会导致审核者混淆”规格是否满足”和”代码质量如何”两个不同维度的判断。分离审核确保：

1. 规格审核者只关心”做对了事”，不关心代码风格
2. 质量审核者假设规格已满足，专注”做得好不好”

为什么需要自审 + 实际审核两轮？

自审是子代理自己的第一道检查，能捕获明显遗漏。但自审不可靠——子代理可能看不到自己的盲点。实际审核由独立子代理执行，提供新鲜视角。两者缺一不可。

参考来源

• Claude Code Subagent 文档 — 子代理的创建、隔离和上下文管理
• OpenAI Codex Task 文档 — 独立任务分派模式