Codex Subagent编排优化提示词发布

背景

随着 AI 辅助编程工具（如 Claude Code、Codex 等）在处理复杂、多步骤任务时的广泛应用，大语言模型（LLM）的上下文窗口限制逐渐成为瓶颈。根 Agent 在处理多文件搜索、独立验证、交叉核验等任务时，上下文（Context）容易因堆积大量中间结果而膨胀或“腐烂”，导致注意力分散、推理质量下降。

针对这一问题，社区和实践者开始探索通过“子代理编排”（Subagent Orchestration）来优化工作流。其核心思路是将宽而重的探索与核验任务从主线程中隔离出来，交给专门的轻量级子代理执行，从而让根 Agent 专注于方案决策与最终验证。该方案参考了 Claude Code 等工具的设计理念，通过一套标准化的配置文件与行为准则，在 Codex 环境中实施高效的 Subagent 编排。

核心内容

本篇内容提供了一套完整的 Codex Subagent 编排优化方案，包括配置文件、执行约束以及详细的编排逻辑。其核心目的是通过标准化子代理的角色、委托流程和行为约束，来提升 AI 助手处理复杂任务的可靠性和效率。

一、配置目标与执行约束

方案要求用户在 Codex 的用户级配置中安装一套完整的 Subagent 项目。具体涉及以下文件：

1. ~/.codex/config.toml：主配置文件。需要修改其中的 [agents.default] 和 [features.multi_agent_v2] 两个表，设置描述、配置文件路径、并发线程数等参数。修改时只处理指定键，并保留表中其他无关配置。
2. ~/.codex/AGENTS.md：代理行为指南文档。需要安装或替换其中的“Subagent 编排”章节，该章节定义了所有子代理的协作规则、委派门槛和生命周期。
3. ~/.codex/agents/ 目录下的四个代理配置文件：default.toml、explorer.toml、reviewer.toml、worker.toml。需要创建或更新这些文件，并赋予每个代理特定的角色、模型、推理强度和沙箱模式。

执行约束非常严格，要求主 Agent 必须在读取现有文件结构后再进行最小化、可审阅的修改，不得覆盖无关配置或密钥，并且不委派子代理来完成此配置任务。

二、Subagent 编排逻辑详解

AGENTS.md 中的“Subagent 编排”章节是本方案的核心行为准则，其逻辑被详细划分为以下几个部分：

1. 自主委派硬约束

• 守门原则：根 Agent 必须直接处理小任务、单一事实和即将修改的精确代码。只有明确能减少主线程上下文负担或提供独立核验时，才委派子代理。
• 并发与等待：委派后必须立即使用 wait_agent 等待所有子代理完成，期间停止其他一切分析、命令执行和文件修改，直到所有子代理返回终态（complete, blocked, failed）。
• 禁止扩大委派：不得因“彻底”“多角度”等模糊措辞而扩大委派范围，也不得把综合判断整体外包。

2. 角色与委托

• 角色选择：根据任务类型选择子代理。explorer 用于探索性研究，reviewer 用于独立复核，default 作为无专职角色匹配时的通用选择。
• 自包含契约：每个委托必须是一个“自包含”的指令，包括目标、必要背景、范围、具体问题、权限、禁止事项、成功标准（success criteria）和期望证据（evidence）。