什么时候需要自定义 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. 文档喂饭级审查代理

这个站点很适合有这样一个角色。

适合自定义的原因：

• 你会长期写教程。
• 教程有稳定标准：前置、步骤、预期结果、失败分支、验收标准。
• 它不应该改代码。
• 它应该专门看“用户能不能照着做出结果”。

适合写成：

tutorial-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：写喂饭级教程的方法。
自定义 Subagent：专门审查教程是否喂饭级的代理。

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

两者可以组合：

• tutorial-writing Skill 负责写教程流程。
• tutorial-reviewer 自定义子代理负责并行审查教程质量。

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

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

比如：

AGENTS.md：
本项目教程必须面向中文用户，步骤不能跳跃，结尾要有验收标准。

tutorial-reviewer：
你是教程审查代理，只负责检查教程是否符合喂饭级标准，不能改文件。

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

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

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

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

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

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

• name
• description
• developer_instructions

一个极简示例：

name = "tutorial-reviewer"
description = "Review Chinese tutorial docs for step-by-step completeness, missing prerequisites, unclear expected results, and acceptance criteria."
developer_instructions = """
You review tutorial documents only.
Do not modify files.
Focus on whether a beginner can follow the document and get a reliable result.
Return findings with file paths, severity, 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。