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

现在的 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 的价值不在数量，而在分工质量。角色越清楚，上下文越干净，主线判断越稳定。

Claude Code subagent 的适用项目与落地方法

适合场景一：大型代码库摸底

如果你刚接手一个陌生项目，最常见的问题不是“代码怎么改”，而是“我根本不知道从哪里看”。

这时 subagent 很有用。你可以让主会话只负责提出问题和汇总结论，然后把探索任务拆出去：

api-reader：只看路由、控制器、接口鉴权。
db-reader：只看 schema、migration、ORM model。
frontend-reader：只看页面结构、状态管理、组件入口。
test-reader：只看测试框架、覆盖范围、运行命令。

每个 subagent 最后只返回 5 到 10 条结论。主会话不用背下整个仓库的细节，只需要拿到一张结构化地图。

这种方式特别适合：

monorepo；
历史包袱较重的业务系统；
前后端混合仓库；
测试、构建、部署脚本散落在多个目录的项目；
接手前需要先做技术债评估的项目。

如果你还在设计 Codex 和 Claude Code 的接力方式，可以把这类“读仓库、摸结构”的任务放在 Claude Code subagent 侧，再把结论交给 Codex 执行更长的修改流程。相关思路可以看站内这篇：Codex 和 Claude Code 任务接力教程：从实现、审查到长任务恢复。

适合场景二：代码审查拆角色

subagent 很适合做代码审查，因为审查本身天然可以按关注点拆开。

例如一次较大的 PR，可以拆成：

bug-reviewer：找逻辑错误、空值、边界条件、回归风险。
security-reviewer：看权限、输入校验、密钥、注入、越权。
performance-reviewer：看循环、查询、缓存、渲染、并发瓶颈。
test-reviewer：看测试是否覆盖真实风险，而不是只补快照。

这样做的好处是，每个 subagent 都不需要理解所有事情。它只需要按照自己的角色，从同一批 diff 里找问题。

但要注意一个边界：审查型 subagent 最好默认只读。

如果你让四个 subagent 同时拥有写权限，它们可能会在同一块代码上做出不同方向的修改。更稳妥的流程是：

主会话收集 diff。
多个只读 subagent 分别审查。
主会话合并结论，决定改哪些。
由主会话或一个明确的 fixer subagent 做小范围修改。

如果你关注“Claude Code 和 Codex 代码审查流程怎么搭”，可以把 subagent 用作 Claude Code 侧的专项审查角色，再由 Codex 做 repo 级修复和验证。站内已有一篇更偏闭环流程的文章：Claude Code 和 Codex 代码审查流程怎么搭：从本地改动到 PR 的闭环工作流。

适合场景三：测试失败和日志噪音处理

自动化测试失败时，主会话最容易被海量输出拖慢。尤其是前端 E2E、后端集成测试、CI 日志，失败信息往往夹在几百行输出里。

这类任务很适合交给 test-runner subagent：

运行指定测试命令；
截取失败用例；
归纳失败原因；
标出最可能相关的文件；
不直接修代码，只返回排查建议。

它的工具可以控制在：

subagent	建议工具	适合任务
`test-runner`	`Bash, Read, Grep`	跑测试、读日志、定位失败
`log-analyzer`	`Read, Grep, Glob`	分析日志和错误堆栈
`coverage-reviewer`	`Read, Grep, Glob`	找缺失测试和高风险分支

如果你已经在用 Claude Code hooks 自动运行测试，可以把 hooks 负责“触发”，subagent 负责“解释失败”。这两者不是替代关系，而是上下游关系：。

适合场景四：大重构前的影响面分析

大重构最怕一上来就改。subagent 更适合先做“只读侦察”。

比如你要替换认证模块、升级数据库访问层、重构前端状态管理，可以让多个 subagent 分别回答：

哪些文件直接依赖旧接口？
哪些测试覆盖了这块逻辑？
哪些调用路径最容易破坏兼容性？
是否存在文档、脚本、配置也要同步改？
哪些地方应该先加测试再动手？

这类任务的关键是：subagent 输出影响面，不要急着输出补丁。

主会话拿到影响面后，再决定是一次性改、分阶段改，还是先补测试。对于长任务来说，这也有助于中断后恢复，因为每个阶段都有清晰结论和可追踪上下文。长任务恢复的写法可以参考：。

不适合场景：别把所有任务都拆成 subagent

subagent 有成本。它会消耗额外上下文、额外等待时间，也会增加协调复杂度。

下面这些场景通常不建议使用：

1. 小到可以直接解决的问题

比如：

改一个 typo；
修一个明显的 import；
调整一个 CSS class；
给一个函数补一行空值判断；
更新一个配置项。

这类任务主会话直接做最快。拆 subagent 只会增加调度成本。

2. 边界不清的需求

如果你自己还没想清楚“要什么结果”，不要先拆 subagent。

例如“帮我优化这个项目”“让这个页面更好看”“重构一下架构”，这些任务在拆分前需要主会话先问清楚目标、约束、验收标准。否则 subagent 会各自理解，最后返回一堆互相冲突的建议。

3. 需要频繁协商的任务

subagent 适合独立工作，不适合来回拉扯。

如果一个任务需要每改两行就重新讨论设计，主会话直接推进更稳。

4. 多个代理同时写同一批文件

这是最容易出问题的场景。

例如你让 frontend-agent、style-agent、accessibility-agent 同时修改同一个 React 组件，它们可能分别做出正确但互相覆盖的修改。更好的方式是让它们先只读审查，再由一个执行者统一落地。

5. 高风险外部操作

涉及生产环境、真实账号、付费 API、删除数据、改权限、发邮件、发消息的任务，不要轻易交给后台 subagent 自动执行。即使要用，也应该限制工具、限制范围，并让主会话做人类可检查的确认点。

项目级 subagent 应该怎么设计

Claude Code 支持把 subagent 写成 Markdown 文件。项目级 subagent 通常放在：

1

.claude/agents/

全局可复用的 subagent 通常放在：

1

~/.claude/agents/

项目级适合写进仓库，因为它反映的是这个项目自己的约定，比如测试命令、目录结构、审查重点、禁止修改的文件、输出格式。

一个最小的只读代码审查 subagent 可以这样写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


---
name: code-reviewer
description: Use when the task needs a read-only review of code changes for bugs, regressions, security risks, and missing tests.
tools: Read, Grep, Glob
---

# Code Reviewer

只做只读审查，不修改文件。

重点检查：

- 逻辑错误和边界条件
- 可能的回归风险
- 安全和权限问题
- 缺失的测试
- 与项目现有风格不一致的实现

输出格式：

1. 先列高风险问题。
2. 每个问题给出文件路径和原因。
3. 没有发现问题时明确说明。
4. 不要输出大段重写后的代码。

这里最重要的不是正文有多长，而是 description 要写清楚。Claude Code 会根据 description 判断什么时候该调用这个 subagent。描述越模糊，自动委派越不稳定。

常见 subagent 组合

实际项目里，不建议一开始就建十几个 subagent。先从 3 到 5 个高频角色开始：

名称	工具	作用
`code-reviewer`	`Read, Grep, Glob`	只读审查 bug、回归和测试缺口
`test-runner`	`Bash, Read, Grep`	运行测试并解释失败
`docs-researcher`	`Read, Grep, Glob`	整理项目文档、迁移说明、约定
`security-reviewer`	`Read, Grep, Glob`	审查权限、输入、密钥、注入风险
`refactor-planner`	`Read, Grep, Glob`	大改前分析影响面和分阶段计划

如果某个 subagent 经常只输出泛泛而谈的建议，说明它的角色太虚。要么缩小任务范围，要么补充项目规则。

怎么调用 subagent

你可以用自然语言显式调用：

1

Use the code-reviewer subagent to review the current diff. Do not modify files.

也可以在会话里点名具体 subagent，例如使用 @code-reviewer 这类方式确保调用指定角色。对于需要从一开始就套用某个 agent 规则的场景，也可以用命令行方式启动：

1

claude --agent code-reviewer

我的建议是：关键任务尽量显式点名，不要完全依赖自动委派。尤其是审查、测试、迁移评估这类任务，明确说“只读”“不要改文件”“只返回结论”，会稳定很多。

一个实用判断公式

如果你不确定某个项目要不要用 subagent，可以按这 5 个问题判断：

任务能不能按模块、目录、角色或关注点拆开？
子任务之间是否相对独立，不需要频繁互相沟通？
子任务输出能不能压缩成明确结论，而不是一堆过程日志？
是否需要不同工具权限，比如有的只读、有的能跑测试、有的能编辑？
拆分带来的上下文隔离收益，是否大于额外 token 和等待成本？

如果 5 个问题里有 3 个以上答案是“是”，就适合尝试 subagent。

如果只有 1 个答案是“是”，那大概率不值得拆。

避坑清单

最后给一个更像项目规范的清单：

subagent 名称要具体，不要叫 helper、assistant、worker。
description 要写触发场景，不要只写“帮助写代码”。
审查型 subagent 默认只读。
写代码型 subagent 一次只负责一个小范围。
大重构先让 subagent 做影响面分析，再决定谁来改。
测试 subagent 应该返回失败摘要，不要把完整日志塞回主会话。
多个 subagent 的输出由主会话合并，不要让它们互相改对方结果。
高风险操作要限制工具和范围。
项目级规则放 .claude/agents/，通用个人习惯放 ~/.claude/agents/。
每隔一段时间删掉低频、重复、输出质量差的 subagent。

参考资料

小结

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

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

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