Subagent on KnightLi的博客

Codex vs Claude Code：两套 Subagent 机制怎么选

Fri, 08 May 2026 14:01:38 +0800

现在的 AI 编程工具越来越重视 Subagent。原因不是功能跟风，而是单个 Agent 处理真实工程任务时，很快会撞到边界。

一个 Agent 如果同时负责读代码、查日志、改实现、跑测试、分析报错、总结结果，主上下文会很快变脏。搜索结果、命令输出、测试日志和中间推理混在一起，后续判断就会被噪声干扰。任务也很难并行：探索、实现、验证和审查都塞在一条主线上，系统越做越重。

Subagent 的本质，是给 Agent 减压。主会话不再把所有事情从头做到尾，而是更像协调者：判断目标、安排任务、接收结果，再把结果合成最终答案。子 Agent 处理某一段局部工作，例如探索、实现、验证或审查，并只把压缩后的结论带回来。

所以 Subagent 不是“再开一个同款自己”，而是把原来糊成一团的工程工作拆成几个边界更清楚的角色。

成熟 Subagent 系统的底层共识

无论具体产品怎么设计，成熟的 Subagent 系统通常都绕不开四件事：

上下文隔离。
角色专用化。
项目和用户级配置。
工具与权限边界。

上下文隔离是前提。真实仓库里的中间结果很多：搜索结果可能几十条，测试日志可能几百行，命令输出里还混着大量无关信息。这些内容如果直接塞进主会话，主线很快会变乱。Subagent 的价值之一，就是让局部过程先在局部被消化，主会话只看到真正有决策价值的结论。

角色专用化也很关键。多 Agent 不是多开几个一样的模型一起干活。探索型任务要擅长搜索、阅读、总结；实现型任务要专注改代码和处理局部细节；验证型任务要跑检查、识别风险，并把结果清楚汇报。它们的任务边界、工具权限和输出形式都应该不同。

工具和权限边界决定了系统能不能安全落地。子 Agent 不应该默认拥有主会话的全部能力。探索型角色未必需要写文件，验证型角色未必需要改实现，后台任务也不该随意越过工作区边界。权限越清楚，协作越可控。

在这些共识之上，Codex 和 Claude Code 走出了两种不同路线。

Codex：显式派工，主会话始终在场

Codex 的 Subagent 设计气质更克制。

它更像是在说：我给你一套受控、轻量、围绕当前主会话展开的分工机制。什么时候派活、派给谁、什么时候收结果，都由主会话明确决定。控制流始终握在当前任务里。

这种设计的特点是“显式”：

需要子任务时，主会话明确发起委托。
子任务角色数量保持克制。
主会话知道哪个 Agent 在做什么。
结果回到主线后再统一判断。
协作边界比较透明。

公开可见的角色思路也偏简洁：通用角色、探索角色、工作角色这类基础分工已经能覆盖很多工程场景。自定义 Agent 更像配置层上的补充，而不是一套非常重的运行时对象系统。

Codex 这套方式的好处是可预期。它适合需要手动编排、强调确定性、希望主会话始终掌控节奏的团队。比如你正在做一个代码修改任务，可以先派一个探索角色查清调用链，再派一个工作角色做改动，最后由主会话整合并决定是否继续测试。

它的缺点也很清楚：如果任务越来越复杂，所有编排压力仍然落在主会话身上。主会话要判断何时拆分、如何拆分、派给谁、怎么合并结果。对轻量协作来说这很舒服，对长期复杂工程流来说，可能不如平台化系统省心。

Claude Code：把 Agent 做成正式工位

Claude Code 的取向更平台化。

它不是只提供几个临时帮手，而是把 Agent 做成可描述、可选择、可配置、可记忆、可隔离、可后台运行的正式对象。子 Agent 不只是会话里的一个工具，而更像工程系统里的一个工位。

这套思路会把 Agent 列表、适用场景、描述信息、工具边界等内容放进选择逻辑里，让模型判断本轮应该调用哪个角色。这类“模型驱动的委托”会带来更强的自动化：用户不一定每次都显式指定角色，系统可以根据任务类型自己选择。

从机制上看，Claude Code 更强调几类能力。

第一是角色体系。探索、规划、通用处理、验证等角色不是随手加几个名字，而是可以带着用途说明、工具限制、默认模型和运行条件存在。探索型角色可以被限制为只读，规划型角色负责设计方案，验证型角色可以专注检查和汇报。

第二是继承和覆盖。子 Agent 并不是完全自由的，它默认继承主会话的大边界；但在规则允许范围内，也可以通过局部配置调整权限、模式或行为。正确理解不是“全部继承”或“全部覆盖”，而是主会话定义大边界，Agent 在边界内做局部装配。

第三是记忆。记忆不只是“记住一点内容”，而是可以有作用域。用户级记忆更像长期偏好，项目级记忆更像仓库背景知识，本地级记忆更像只留在当前环境里的私人状态。这样某些 Agent 不必每次从零理解项目。

第四是后台和工作区隔离。某些验证任务可以在后台持续跑，主线不用停在原地等待。需要强隔离时，Agent 可以进入独立 worktree，像在主工位旁边分出一张独立桌子：仍然在同一个项目里，但操作空间被明确隔开。

第五是插件生态。只有当 Agent 被视为正式对象时，才会认真考虑它如何被分发、安装、覆盖、排序和接入生态。插件 Agent 可以进入系统，但高风险字段仍应被收口，例如权限模式、hooks、MCP server 等不应该由插件随意声明。

这让 Claude Code 更像一套 Agent 运行时，而不是单次会话里的协作工具。

两种路线的差异

可以把两者理解成两种产品哲学。

Codex 更像受控分工工具：

主会话显式派工。
角色集保持轻量。
控制流清晰。
子任务围绕当前会话展开。
适合强调确定性和人工编排的工作方式。

Claude Code 更像工程工位系统：

Agent 被正式建模。
角色更体系化。
支持记忆、后台、隔离和插件生态。
模型可以参与选择角色。
适合长期项目、复杂工作流和平台化扩展。

这不是谁功能更多谁就更好。真正的差别在于：你希望 Subagent 是“我显式叫来的助手”，还是“系统里长期存在的工位”。

怎么选择

如果你更看重显式控制、轻量分工、当前会话内的安全并行，Codex 的思路更顺手。它让你清楚知道任务什么时候被拆出去，谁在处理，结果什么时候回来。对代码审查、小型改动、明确的实现任务和需要人工节奏控制的场景，这种方式很稳。

如果你更看重体系化角色、长期记忆、后台执行、worktree 隔离、插件扩展和更完整的 Agent 运行时，Claude Code 的路线更合适。它适合把 Agent 当成长期参与项目的成员，而不是临时搬一把的助手。

可以用两个问题判断：

你能不能接受模型自己选择该派谁干活？
你是否需要一套更完整的 Agent 运行时？

如果第一个问题让你不舒服，说明你更适合显式派工。
如果第二个问题答案是肯定的，说明你可能需要平台化的 Agent 工位系统。

使用建议

无论选哪种，都不要把 Subagent 当作“多开几个模型就更强”。

更有效的做法是：

给每个角色明确任务边界。
控制每个角色能用的工具。
让子 Agent 输出结论，而不是搬回全部原始日志。
主会话保留最终决策权。
对后台任务和工作区隔离保持可见性。
对插件 Agent 设置明确安全边界。

工程任务里，Subagent 的价值不在数量，而在分工质量。角色越清楚，上下文越干净，主线判断越稳定。

小结

Codex 和 Claude Code 都在解决同一个问题：单个 Agent 很难独自承载真实工程任务。它们都承认上下文隔离、角色专用、权限边界和局部汇总的重要性。

差异在于实现取向。Codex 更克制，强调显式派工和主会话控制；Claude Code 更体系化，把 Agent 做成可配置、可记忆、可隔离、可后台运行、可进入插件生态的正式工位。

选择哪一个，不是看哪个品牌赢，而是看你的工作方式需要什么：是受控协作工具，还是完整 Agent 运行时。

Claude Code 多 Agent 协作：Subagents 和 Agent Teams 怎么选

Wed, 22 Apr 2026 21:35:52 +0800

Claude Code 里和多 Agent 协作相关的能力，最容易混淆的就是 Subagents 和 Agent Teams。它们看起来都像“多开几个 Agent 一起做事”，但定位并不一样。简单说，前者更适合把独立任务分出去做，后者更适合让多个 Agent 围绕同一件事持续协作、互相验证。

如果你之前用过 Skill，也可以先这样理解：

Skill 负责定义流程和规则
Subagent 或 Agent teammate 负责实际执行任务

所以问题不在于“哪个更高级”，而在于你要解决的是哪一类协作。

Subagents：把支线任务分出去

Subagents 更像是在当前会话里临时派出去的分身。每个分身都有自己的上下文窗口，做完之后只把结果摘要带回来，主对话不会被大量中间输出塞满。

这类能力的优势很直接：

主线对话更干净，不容易被测试日志、搜索结果或长输出污染
可以把相互独立的研究或执行任务并行化
适合“给我结果就行”的任务，不需要持续讨论

原文提到，Claude Code 内置了三类 Subagent：

Explore：只读、适合快速搜索代码库
Plan：只读、适合在 plan mode 下后台收集信息
General-purpose：可读可写，适合同时探索和修改的任务

自定义 Subagent

如果内置能力不够，可以自己定义一个 Subagent。方式也不复杂，本质上就是写一个 Markdown 文件：

.claude/agents/：只对当前项目生效
~/.claude/agents/：对所有项目生效

文件格式类似这样：

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

这里最关键的是 description。Claude 会根据这段描述判断什么时候应该调用这个 Subagent，所以写得越清楚，触发越准。

另外几个常见配置项也很实用：

tools：限制它能用哪些工具
model：决定使用 sonnet、opus、haiku 或 inherit
permissionMode：控制编辑权限和权限提示行为
memory：给 Subagent 配跨对话记忆目录

如果只是临时用一次，也可以直接通过 CLI 注入：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Subagents 适合什么场景

最适合 Subagents 的，通常是这些任务：

跑测试并返回失败摘要，而不是把几千行日志全塞回主会话
并行调查几个互不依赖的模块
把“检查问题”和“修问题”拆成两步流水线

例如：

`1`	`Research the authentication, database, and API modules in parallel using separate subagents`

`1`	`Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them`

但如果任务需要频繁来回修正、多个阶段共享大量上下文，或者改动高度集中在少数几个文件里，那么直接在主对话里做，往往比派 Subagent 更省事。

Agent Teams：多个独立会话一起协作

Agent Teams 是另一个层级的能力。它不是在一个会话里派出分身，而是启动多个彼此独立的 Claude Code 实例，让它们围绕共享任务列表协作，还可以互相发消息。

这意味着它更像一个真正的小团队，而不只是“分出去做个支线”。

原文提到，这项能力目前还是实验功能，需要先开启：

{
    "env": {
        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
    }
}

把它加到 settings.json 后，就可以让 Claude 按你的要求组织一个 team。比如：

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Agent Teams 的组成

一个 Agent Team 主要由三部分组成：

Team lead：你当前正在使用的主会话，负责组队、分派和汇总
Teammates：多个独立的 Claude Code 实例
Task list 和 Mailbox：共享任务列表与消息通道

和 Subagents 最大的不同在于，teammates 之间可以直接沟通，不需要每次都经过 lead 中转。任务状态通常会在 pending、in progress、completed 之间流转，成员完成一个任务后，还可以继续认领下一个任务。

Agent Teams 适合什么场景

当任务需要多角度讨论、互相挑战结论、或者拆成多个模块并行推进时，Agent Teams 会更合适。

原文给了几个很典型的场景：

多人并行审查同一个 PR，但每个人关注不同维度
围绕同一个 bug 提出不同假设，并互相反驳
前端、后端、测试分别推进不同模块

比如并行代码审查：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

再比如竞争假说式调试：

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

这类任务的共性是：不是只要一个结果，而是需要不同 Agent 之间不断交换判断、修正方向，最后再形成比较可靠的结论。

两者怎么选

如果要快速区分，可以直接记这条：

做完给结果，用 Subagents
需要讨论和相互验证，用 Agent Teams

再展开一点，区别主要在这几个维度：

通信方式：Subagents 主要把结果回传给主对话；Agent Teams 的成员之间可以直接通信
协调模式：Subagents 更依赖主会话统一调度；Agent Teams 有共享任务列表，成员可以自己认领任务
Token 成本：Subagents 更省；Agent Teams 成本更高，因为每个 teammate 都是独立实例
适合任务：Subagents 更适合独立、结果导向的任务；Agent Teams 更适合需要讨论、交叉验证的任务

使用时要注意什么

Agent Teams 虽然更强，但并不意味着任何任务都值得开 team。原文特别提醒了几个现实问题：

token 消耗明显更高
同时让多个 teammate 改同一个文件，很容易互相覆盖
teammate 太多会增加协调成本，收益未必继续增长

因此，比较稳妥的做法通常是：

3 到 5 个 teammate 作为起点
按模块或文件拆任务，避免写入冲突
如果 lead 过早接手了 teammate 的任务，要明确告诉它先等队友完成

另外，当前实验能力还有一些限制，例如：

不支持 /resume 和 /rewind 恢复 in-process teammates
任务状态偶尔会滞后，需要人工提醒更新
一个 lead 一次只能管理一个 team
teammate 不能再继续派子 team

简单结论

这两个能力并不是替代关系，而是分别解决两类协作问题。

如果你的需求是“把支线任务并行做掉，别污染主上下文”，优先用 Subagents。如果你的需求是“让几个 Agent 像一个小团队一样协作、讨论、交叉验证”，再考虑 Agent Teams。

先用一个真实场景试一次，通常很快就能体会到差别：一个强调上下文隔离和结果回收，另一个强调多视角协同和持续互动。