[!info] related notes

• 所属 MOC: Coding Agent MOC
• 前置概念: Agent, Orchestrator-Workers
• 并列概念: Coding Agent Skills, Claude Code Workflow
• 关系笔记: Claude Code 多 Agent 编排模式, 多 Agent 编排模式

Coding Agent Subagents

一句话定义

Subagents 是 coding agent 将复杂任务拆分给多个独立 AI 实例并行处理的模式，每个 subagent 有独立的上下文窗口、自定义 system prompt、工具权限和独立权限，主 agent 负责汇总结果。

为什么需要 Subagents

单个 Agent 的上下文窗口和注意力有限。当任务涉及：

• 大量文件搜索和日志分析（会污染主上下文）
• 多维度并行审查（正确性、安全性、性能）
• 多个独立子任务可以同时进行
• 需要专门化的 agent 角色（审查者、实现者、测试者）

Subagent 模式比单 agent 串行处理更高效、更可靠。

核心机制

主 Agent（用户交互入口）
 │
 ├─ Subagent A：分析前端状态/query 流程    → 返回分析报告
 ├─ Subagent B：分析 Go 后端持久化逻辑    → 返回分析报告
 ├─ Subagent C：分析 Python runtime/SSE  → 返回分析报告
 │
 └─ 汇总三个报告 → 输出架构诊断

关键特征：

• 独立上下文：每个 subagent 不知道其他 subagent 的存在
• 结果传递：只能通过主 agent 的脚本逻辑传递结果
• 并发控制：受并发上限约束（通常 min(16, CPU核心数 - 2)）
• Schema 校验：通过 JSON Schema 强制结构化输出，保证 agent 间通信可靠

各产品的实现差异

维度	Codex	Claude Code
触发方式	显式要求 “use subagents”	Agent 工具或 Workflow 脚本
编排控制	Codex 内部决定	确定性脚本（Workflow）或主 agent 自行决定
自定义 agent	支持 custom agents	.claude/agents/*.md 自定义 agent 类型
并发模型	并行执行后汇总	并行屏障（parallel）或流水线（pipeline）
Schema 校验	不明确	JSON Schema 强制校验，不符合自动重试
额度消耗	每个 subagent 独立消耗	预算在主循环和所有 workflow 间共享

Codex 特有

• Codex 只会在你明确要求时启动 subagents
• 每个 subagent 消耗自己的模型和工具用量
• 适合大型架构分析，不适合小 bug
• 支持定义不同模型配置和指令的 custom agents

Claude Code 特有

• Agent 工具：手动调用，主 agent 决定顺序和参数
• Workflow 引擎：确定性脚本编排，支持 parallel()、pipeline()、phase()
• 自定义 agent 类型：.claude/agents/*.md 定义专门化 agent（如 Explore、Plan、code-reviewer）
• 隔离模式：isolation: 'worktree' 让 subagent 在独立 git worktree 中工作
• 缓存恢复：编辑脚本后可从断点恢复，已完成的 agent 调用不重复执行

典型模式

多维度并行审查

主 Agent
 ├─ Subagent: 正确性审查
 ├─ Subagent: 安全性审查
 ├─ Subagent: 边界情况审查
 └─ 汇总：只有 ≥2 个审查通过才认为有效

实现→审查→修复循环

实现 Agent → 审查 Agent 1 (正确性)  ─┐
           → 审查 Agent 2 (安全性)  ─┼→ 汇总 → 修复 Agent → 再审查...
           → 审查 Agent 3 (边界)    ─┘

按领域拆分分析

前端 Agent → 分析 React state/query/route
后端 Agent → 分析 Go API/session/persistence
Runtime Agent → 分析 Python tool_call/SSE
→ 合并为架构报告

边界与易混淆点

• Subagent 不是”更高级的 agent”——它的价值在于独立上下文和并行执行
• 每个 subagent 都是全新独立会话，互相不知道对方存在
• 并行不等于快——如果任务之间有依赖，强行并行会导致错误
• Subagent 消耗额度比单 agent 更多，小任务不值得

最短记忆方式

Subagent = 把子任务委派给独立 AI 实例并行处理，各自有独立上下文，主 agent 汇总结果。

Related notes

• Claude Code 多 Agent 编排模式
• Claude Code Workflow
• Orchestrator-Workers
• Coding Agent MOC