什么时候需要自定义 Subagents

什么时候需要自定义 Subagents

你已经知道 Subagents 可以并行拆任务。 你也已经跑过一次只读评审。

但这不代表你应该马上创建自定义子代理。

自定义 Subagent 不是“越多越专业”。 更准确地说，它是一把专门工具：

当某类并行任务会反复出现，而且每次都需要稳定的角色、规则、模型或权限边界时，才值得自定义。

前置教程：第一次使用 Subagents 做只读评审
如果你还没有跑通过一次只读评审，先不要做自定义子代理。

依据来源：OpenAI Codex 官方手册中 Subagents、custom agents、built-in agents、sandbox controls、[agents] 全局设置、自定义 agent 文件 schema 等章节。

核心结论

能用提示词拆清楚的，就先用提示词。 同一类子代理任务反复出现，再考虑自定义。

比如你偶尔想让 Codex 并行评审一次项目结构，用普通提示词即可。 但如果你每周都要做 PR 评审，并且每次都要分出“安全审查员、测试审查员、可维护性审查员”，那就可以考虑自定义。

内置子代理已经够用的情况

Codex 本身有内置子代理能力。 你可以通过提示词让它派出不同方向的代理。

下面这些情况先不要自定义：

1. 只是偶尔用一次

例如：

请派 3 个子代理分别看项目结构、文档完整性和构建脚本。

这种任务不需要长期沉淀。 提示词写清楚即可。

2. 任务拆分每次都不一样

今天你要看前端结构，明天你要看后端接口，后天你要看 SEO。

如果每次拆分方向都不一样，自定义子代理反而会变成负担。 它会让你为了“套角色”而扭曲任务。

3. 你还没形成稳定标准

比如你还说不清：

• 安全审查到底看哪些风险。
• 测试审查到底看哪些文件。
• 文档审查到底按什么标准判断。
• 评审结果应该按什么格式输出。

这时不要先写自定义子代理。 先用普通提示词跑几次，把稳定规则总结出来。

4. 只是想换一个名字

不要为了让界面里显示“安全专家”“架构专家”就创建自定义子代理。

自定义的价值不在名字，而在稳定行为。

什么时候值得自定义

满足下面 4 条里的 2 条以上，就可以考虑：

1. 这个角色会反复使用。
2. 这个角色有稳定审查标准。
3. 这个角色需要不同模型、推理强度、工具或沙盒边界。
4. 这个角色的输出格式必须长期保持一致。

适合自定义的典型角色

1. PR 安全审查代理

适合自定义的原因：

• 每次 PR 都可能需要安全审查。
• 安全审查有稳定清单。
• 输出需要按严重程度排序。
• 通常应该只读，不应该主动改代码。

适合写成：

security-reviewer

它的职责可以是：

• 查找密钥泄露。
• 查找权限绕过。
• 查找鉴权遗漏。
• 查找危险文件操作。
• 查找注入风险。
• 输出高 / 中 / 低风险。

2. 测试缺口审查代理

适合自定义的原因：

• 每次改功能都要看测试是否跟上。
• 它关注的点和安全审查不同。
• 它可以只读分析测试文件和业务改动。

适合写成：

test-gap-reviewer

它的职责可以是：

• 找本次改动影响了哪些行为。
• 找是否有对应测试。
• 找测试命令是否明确。
• 标注哪些缺口必须补，哪些可以后续补。

3. 发布前风险审查代理

很多项目在提交或发布前都适合有这样一个角色。

适合自定义的原因：

• 每次交付前都需要检查风险。
• 审查标准相对稳定：改动范围、验证情况、回归风险、配置风险、交付说明。
• 它不应该改代码。
• 它应该专门看“这次修改能不能安全交付”。

适合写成：

risk-reviewer

它的职责可以是：

• 检查是否有无关改动。
• 检查是否遗漏验证。
• 检查是否有明显回归风险。
• 检查是否动了配置、权限、接口或数据结构。
• 检查最终交付说明是否清楚。

4. 架构理解代理

适合大型项目第一次接入时使用。

它不负责改代码，只负责读项目，画出结构。

适合写成：

project-mapper

它的职责可以是：

• 找入口。
• 找核心模块。
• 找数据流。
• 找构建和部署路径。
• 找风险边界。

不适合自定义的角色

1. “万能高级工程师”

不要创建这种：

senior-engineer

如果它什么都能做，就等于没有边界。 没有边界的自定义子代理，很容易和主会话抢职责。

2. “自动修复一切问题”

不要创建这种：

auto-fixer

并行代理自动改代码，风险很高。 尤其是多个代理同时写文件时，会出现冲突、重复修改和责任不清。

3. “所有任务都先派出去”

不要把 Subagents 变成默认动作。

小任务、顺序任务、目标不清的任务，单会话更稳。

自定义前的判断清单

在创建自定义子代理前，先问 Codex：

请帮我判断这个角色是否值得做成自定义 Subagent。

角色设想：
【写清你想创建的角色，比如“教程喂饭级审查代理”】

请按下面标准判断：
1. 这个角色是否会反复使用。
2. 它的职责是否足够窄。
3. 它是否有稳定输出格式。
4. 它是否需要不同模型、推理强度、工具或沙盒边界。
5. 它是否可以先用普通提示词完成。
6. 如果不自定义，会有什么明显损失。

最后请给结论：
- 现在就自定义。
- 先用提示词跑 3 次再沉淀。
- 不建议自定义。

不要创建任何文件。

如果 Codex 建议“先用提示词跑 3 次”，那通常是稳妥答案。

自定义子代理和 Skill 的区别

这两个很容易混。

能力	适合做什么
Skill	复用一套任务方法，让主会话或代理按流程做事
自定义 Subagent	定义一个可被派出去并行工作的角色

举个例子：

Skill：Bug 修复的标准流程。
自定义 Subagent：专门审查本次修复风险的代理。

Skill 更像“流程说明书”。 自定义 Subagent 更像“固定岗位”。

两者可以组合：

• bugfix-flow Skill 负责修复流程。
• risk-reviewer 自定义子代理负责并行审查修改风险。

自定义子代理和 AGENTS.md 的区别

AGENTS.md 写项目规则。 自定义 Subagent 写某个代理角色。

比如：

AGENTS.md：
本项目修改后必须说明影响范围、验证方式和未验证项。

risk-reviewer：
你是风险审查代理，只负责检查本次代码修改是否存在无关改动、遗漏验证或回归风险，不能改文件。

如果是全项目都要遵守的规则，写进 AGENTS.md。 如果是某个并行角色的职责，写进自定义 Subagent。

自定义子代理文件大概长什么样

这一篇先不带你创建文件，只让你看懂结构。

官方手册说明，自定义 agent 可以放在：

• 用户级：~/.codex/agents/
• 项目级：.codex/agents/

每个自定义 agent 是一个独立 TOML 文件。 必填字段是：

• name
• description
• developer_instructions

一个极简示例：

name = "risk-reviewer"
description = "Review code changes for scope creep, regression risk, missing validation, and unclear handoff notes."
developer_instructions = """
You review code changes only.
Do not modify files.
Focus on whether the change stays within scope and can be safely delivered.
Return findings with file paths, severity, risk, reason, and suggested fix.
"""

你现在只需要看懂：

• name 是代理名称。
• description 告诉 Codex 什么时候适合用它。
• developer_instructions 定义这个代理怎么工作。

下一篇才会真正创建。

用户级还是项目级

先按这个原则：

场景	放哪里
只你自己所有项目都要用	~/.codex/agents/
只这个项目要用	.codex/agents/
团队项目希望大家共享	.codex/agents/，并配合项目规则审查

新手第一次创建，建议用项目级。

原因：

• 影响范围小。
• 方便回滚。
• 更容易和当前项目规则绑定。
• 不会污染你所有项目。

模型和权限先不要改

自定义 agent 支持配置模型、推理强度、沙盒、MCP、Skills 等字段。

但第一版不要一上来都配。

建议第一版只写：

• name
• description
• developer_instructions

先跑通职责。 等你发现它确实需要不同模型、不同推理强度或更严格沙盒时，再加配置。

这和我们前面一直坚持的原则一致：

先跑通最小可用，再逐步增加复杂度。

什么时候要限制 max_threads

官方手册里提到全局 [agents] 可以配置并发线程上限和嵌套深度。

新手不用急着改。

只需要知道：

• 并发越多，消耗越高。
• 嵌套越深，越难预测。
• 默认就够大多数人入门使用。

如果你发现自己经常一次派出太多代理，可以先在提示词里限制：

最多派 3 个子代理。
不要嵌套派生新的子代理。

不要一开始就去改全局配置。

本篇验收标准

读完本篇，你应该能回答：

• 什么时候继续用普通提示词拆 Subagents。
• 什么时候才值得自定义 Subagent。
• 为什么不要做“万能高级工程师”代理。
• Skill、AGENTS.md、自定义 Subagent 分别负责什么。
• 自定义 agent 文件必填字段有哪些。
• 用户级和项目级放置位置有什么区别。
• 为什么第一版先不要配置模型、权限和 MCP。

如果这些能说清楚，下一篇就可以创建第一个自定义 Subagent。