1. 为什么需要子 Agent 分工在复杂项目里单个 Codex 会话往往要同时承担「想清楚怎么做」和「把代码写出来」两类工作。前者需要反复推演、对比方案、评估风险后者需要快速产出代码、跑测试、修报错。两者混在一起既拖慢节奏又容易让主 Agent 的上下文被大量实现细节塞满。把任务拆给子 Agent 是更清晰的做法让一个子 Agent 负责「军师」角色专注分析和规划让另一个子 Agent 负责「搬砖工」角色专注执行和落地。主 Agent 只做调度和决策上下文更干净产出也更稳定。本文以 Sol 和 Luna 两个子 Agent 为例给出完整的 Codex 子 Agent 配置方案包含角色定义、任务分发、上下文传递和实战代码。2. 整体架构整个协作链路可以概括为主 Agent 接收需求把问题交给 Sol 分析Sol 输出方案和任务清单主 Agent 再把具体实现任务交给 LunaLuna 产出代码并回报结果主 Agent 汇总验收。flowchart TD A[主 Agent 接收需求] -- B[Sol 军师分析问题] B -- C[Sol 输出方案与任务清单] C -- D[主 Agent 拆解任务] D -- E[Luna 搬砖工实现代码] E -- F[Luna 回报结果] F -- G[主 Agent 验收与汇总] G -- H[输出最终交付]这套架构的关键在于Sol 不写业务代码Luna 不做架构决策。职责边界清晰上下文才能各司其职。3. 子 Agent 配置基础Codex 子 Agent 的配置通常通过 AGENTS.md 或项目级指令文件来声明。每个子 Agent 需要明确三件事角色定位、工作边界、输出格式。下面是一个基础配置示例定义 Sol 和 Luna 两个子 Agent 的身份与职责。# AGENTS.md 子 AgentSol军师 角色架构师与规划者 职责分析需求、评估方案、输出任务清单 边界不直接修改业务代码 输出格式方案说明 分步任务列表 子 AgentLuna搬砖工 角色实现者与执行者 职责按任务清单编写代码、运行测试、修复报错 边界不擅自改变架构方向 输出格式代码变更说明 测试结果配置写好之后主 Agent 在分发任务时就可以按角色把问题路由到对应的子 Agent。4. 让 Sol 当军师分析与规划Sol 的核心价值在于「想清楚」。当主 Agent 收到一个模糊需求时先把问题交给 Sol让它输出结构化的分析结果。下面是一个 Sol 的提示词模板可以直接复制到 Codex 会话中使用。你是 Sol项目军师。请分析以下需求输出 1. 需求拆解这个需求要解决什么问题 2. 方案对比列出 2 到 3 种可行方案说明各自优缺点 3. 风险点实现过程中可能遇到的坑 4. 任务清单按依赖顺序列出可执行的分步任务 需求 实现一个用户登录接口支持邮箱和手机号两种方式。Sol 的输出应该是一份清晰的规划文档而不是代码。主 Agent 拿到这份规划后再决定如何把任务交给 Luna。5. 让 Luna 当搬砖工实现与落地Luna 的核心价值在于「做出来」。它拿到 Sol 的任务清单后按步骤实现代码并回报结果。下面是一个 Luna 的提示词模板强调执行和验证。你是 Luna项目搬砖工。请按以下任务清单实现代码并运行测试验证结果。 每完成一步回报改动了哪些文件、测试是否通过、有无报错。 任务清单 创建 UserController暴露 POST /api/login 接口 创建 UserService实现邮箱和手机号两种登录逻辑 编写单元测试覆盖成功和失败场景Luna 的回报要具体、可验证。主 Agent 根据回报决定是验收通过还是把问题打回给 Sol 重新分析。6. 主 Agent 调度示例实际使用中主 Agent 需要把 Sol 和 Luna 串起来。下面是一个完整的调度流程示例展示从需求到交付的完整链路。主 Agent 收到需求实现用户登录接口。 第一步交给 Sol 分析 输入需求描述 输出方案对比 任务清单 第二步主 Agent 审核 Sol 的方案 确认方案可行后把任务清单拆给 Luna 第三步交给 Luna 实现 输入任务清单 输出代码变更 测试结果 第四步主 Agent 验收 测试通过则交付 测试失败则把问题反馈给 Sol 重新分析这个流程的核心是主 Agent 不亲自写业务代码也不亲自做深度分析只做调度和决策。这样每个角色的上下文都保持干净。7. 实战登录接口完整实现下面用一个完整的 Java 实战案例演示 Sol 和 Luna 如何协作完成登录接口。首先Sol 输出的任务清单如下Sol 输出 1. 创建 UserController暴露 POST /api/login 接口 2. 创建 UserService实现邮箱和手机号两种登录逻辑 3. 创建 UserRepository负责用户数据查询 4. 编写单元测试覆盖成功和失败场景Luna 拿到清单后开始实现。下面是 UserController 的代码。RestController RequestMapping(/api) public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService userService; } PostMapping(/login) public ResponseEntitylt;LoginResponsegt; login(RequestBody LoginRequest request) { String token userService.login(request.getAccount(), request.getPassword()); return ResponseEntity.ok(new LoginResponse(token)); } }接着是 UserService 的实现处理邮箱和手机号两种登录方式。Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository userRepository; } public String login(String account, String password) { User user userRepository.findByEmailOrPhone(account); if (user null) { throw new RuntimeException(用户不存在); } if (!user.getPassword().equals(password)) { throw new RuntimeException(密码错误); } return generateToken(user.getId()); } private String generateToken(Long userId) { return token- userId - System.currentTimeMillis(); } }然后是 UserRepository负责数据查询。Repository public class UserRepository { private final Maplt;String, Usergt; users new HashMaplt;gt;(); public User findByEmailOrPhone(String account) { return users.get(account); } public void save(User user) { users.put(user.getEmail(), user); users.put(user.getPhone(), user); } }最后是单元测试覆盖成功和失败场景。SpringBootTest class UserServiceTest { Autowired private UserService userService; Autowired private UserRepository userRepository; BeforeEach void setUp() { User user new User(); user.setId(1L); user.setEmail(testexample.com); user.setPhone(13800138000); user.setPassword(123456); userRepository.save(user); } Test void loginWithEmailShouldSucceed() { String token userService.login(testexample.com, 123456); assertNotNull(token); } Test void loginWithWrongPasswordShouldFail() { assertThrows(RuntimeException.class, () -gt; userService.login(testexample.com, wrong)); } }Luna 完成实现后回报测试结果。主 Agent 确认测试通过即可交付。8. 上下文传递技巧子 Agent 协作的关键在于上下文传递。主 Agent 在把任务交给 Sol 或 Luna 时要尽量把上下文压缩成「必要信息」避免把无关细节一起塞过去。给 Sol 的上下文应该包含需求背景、约束条件、期望产出。给 Luna 的上下文应该包含明确的任务清单、涉及的文件路径、验收标准。下面是一个上下文传递的对比示例。不好的传递方式 主 Agent 把整个项目代码都贴给 Luna让它自己找登录接口在哪。 好的传递方式 主 Agent 告诉 Luna 任务实现 UserController 的 login 接口 文件src/main/java/com/example/UserController.java 依赖UserService 已存在直接注入使用 验收POST /api/login 返回 token上下文越精简子 Agent 的产出越稳定出错概率也越低。9. 常见问题与排查子 Agent 协作过程中常见的问题主要有三类。第一类是职责混淆。Sol 开始写代码或者 Luna 开始做架构决策都会导致产出混乱。解决办法是在 AGENTS.md 里明确边界主 Agent 分发任务时反复强调角色。第二类是上下文过载。给子 Agent 塞太多无关信息会导致它抓不住重点。解决办法是只传递任务相关的必要上下文其余信息按需提供。第三类是验收标准缺失。Luna 不知道「什么样算完成」就会产出不符合预期的结果。解决办法是在任务清单里写明验收标准例如「测试通过」「接口返回 200」。10. 总结让 Sol 当军师、Luna 当搬砖工的核心是把「思考」和「执行」分离。Sol 负责想清楚Luna 负责做出来主 Agent 负责调度和决策。三者各司其职上下文干净产出稳定。这套配置适合中大型项目尤其是需求频繁变化、代码量较大的场景。对于小型任务直接让主 Agent 完成即可不必过度拆分。建议从一个小功能开始尝试逐步调整 Sol 和 Luna 的提示词找到最适合自己项目的分工方式。
Codex 子 Agent 配置指南：让 Sol 当军师，Luna 当搬砖工
1. 为什么需要子 Agent 分工在复杂项目里单个 Codex 会话往往要同时承担「想清楚怎么做」和「把代码写出来」两类工作。前者需要反复推演、对比方案、评估风险后者需要快速产出代码、跑测试、修报错。两者混在一起既拖慢节奏又容易让主 Agent 的上下文被大量实现细节塞满。把任务拆给子 Agent 是更清晰的做法让一个子 Agent 负责「军师」角色专注分析和规划让另一个子 Agent 负责「搬砖工」角色专注执行和落地。主 Agent 只做调度和决策上下文更干净产出也更稳定。本文以 Sol 和 Luna 两个子 Agent 为例给出完整的 Codex 子 Agent 配置方案包含角色定义、任务分发、上下文传递和实战代码。2. 整体架构整个协作链路可以概括为主 Agent 接收需求把问题交给 Sol 分析Sol 输出方案和任务清单主 Agent 再把具体实现任务交给 LunaLuna 产出代码并回报结果主 Agent 汇总验收。flowchart TD A[主 Agent 接收需求] -- B[Sol 军师分析问题] B -- C[Sol 输出方案与任务清单] C -- D[主 Agent 拆解任务] D -- E[Luna 搬砖工实现代码] E -- F[Luna 回报结果] F -- G[主 Agent 验收与汇总] G -- H[输出最终交付]这套架构的关键在于Sol 不写业务代码Luna 不做架构决策。职责边界清晰上下文才能各司其职。3. 子 Agent 配置基础Codex 子 Agent 的配置通常通过 AGENTS.md 或项目级指令文件来声明。每个子 Agent 需要明确三件事角色定位、工作边界、输出格式。下面是一个基础配置示例定义 Sol 和 Luna 两个子 Agent 的身份与职责。# AGENTS.md 子 AgentSol军师 角色架构师与规划者 职责分析需求、评估方案、输出任务清单 边界不直接修改业务代码 输出格式方案说明 分步任务列表 子 AgentLuna搬砖工 角色实现者与执行者 职责按任务清单编写代码、运行测试、修复报错 边界不擅自改变架构方向 输出格式代码变更说明 测试结果配置写好之后主 Agent 在分发任务时就可以按角色把问题路由到对应的子 Agent。4. 让 Sol 当军师分析与规划Sol 的核心价值在于「想清楚」。当主 Agent 收到一个模糊需求时先把问题交给 Sol让它输出结构化的分析结果。下面是一个 Sol 的提示词模板可以直接复制到 Codex 会话中使用。你是 Sol项目军师。请分析以下需求输出 1. 需求拆解这个需求要解决什么问题 2. 方案对比列出 2 到 3 种可行方案说明各自优缺点 3. 风险点实现过程中可能遇到的坑 4. 任务清单按依赖顺序列出可执行的分步任务 需求 实现一个用户登录接口支持邮箱和手机号两种方式。Sol 的输出应该是一份清晰的规划文档而不是代码。主 Agent 拿到这份规划后再决定如何把任务交给 Luna。5. 让 Luna 当搬砖工实现与落地Luna 的核心价值在于「做出来」。它拿到 Sol 的任务清单后按步骤实现代码并回报结果。下面是一个 Luna 的提示词模板强调执行和验证。你是 Luna项目搬砖工。请按以下任务清单实现代码并运行测试验证结果。 每完成一步回报改动了哪些文件、测试是否通过、有无报错。 任务清单 创建 UserController暴露 POST /api/login 接口 创建 UserService实现邮箱和手机号两种登录逻辑 编写单元测试覆盖成功和失败场景Luna 的回报要具体、可验证。主 Agent 根据回报决定是验收通过还是把问题打回给 Sol 重新分析。6. 主 Agent 调度示例实际使用中主 Agent 需要把 Sol 和 Luna 串起来。下面是一个完整的调度流程示例展示从需求到交付的完整链路。主 Agent 收到需求实现用户登录接口。 第一步交给 Sol 分析 输入需求描述 输出方案对比 任务清单 第二步主 Agent 审核 Sol 的方案 确认方案可行后把任务清单拆给 Luna 第三步交给 Luna 实现 输入任务清单 输出代码变更 测试结果 第四步主 Agent 验收 测试通过则交付 测试失败则把问题反馈给 Sol 重新分析这个流程的核心是主 Agent 不亲自写业务代码也不亲自做深度分析只做调度和决策。这样每个角色的上下文都保持干净。7. 实战登录接口完整实现下面用一个完整的 Java 实战案例演示 Sol 和 Luna 如何协作完成登录接口。首先Sol 输出的任务清单如下Sol 输出 1. 创建 UserController暴露 POST /api/login 接口 2. 创建 UserService实现邮箱和手机号两种登录逻辑 3. 创建 UserRepository负责用户数据查询 4. 编写单元测试覆盖成功和失败场景Luna 拿到清单后开始实现。下面是 UserController 的代码。RestController RequestMapping(/api) public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService userService; } PostMapping(/login) public ResponseEntitylt;LoginResponsegt; login(RequestBody LoginRequest request) { String token userService.login(request.getAccount(), request.getPassword()); return ResponseEntity.ok(new LoginResponse(token)); } }接着是 UserService 的实现处理邮箱和手机号两种登录方式。Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository userRepository; } public String login(String account, String password) { User user userRepository.findByEmailOrPhone(account); if (user null) { throw new RuntimeException(用户不存在); } if (!user.getPassword().equals(password)) { throw new RuntimeException(密码错误); } return generateToken(user.getId()); } private String generateToken(Long userId) { return token- userId - System.currentTimeMillis(); } }然后是 UserRepository负责数据查询。Repository public class UserRepository { private final Maplt;String, Usergt; users new HashMaplt;gt;(); public User findByEmailOrPhone(String account) { return users.get(account); } public void save(User user) { users.put(user.getEmail(), user); users.put(user.getPhone(), user); } }最后是单元测试覆盖成功和失败场景。SpringBootTest class UserServiceTest { Autowired private UserService userService; Autowired private UserRepository userRepository; BeforeEach void setUp() { User user new User(); user.setId(1L); user.setEmail(testexample.com); user.setPhone(13800138000); user.setPassword(123456); userRepository.save(user); } Test void loginWithEmailShouldSucceed() { String token userService.login(testexample.com, 123456); assertNotNull(token); } Test void loginWithWrongPasswordShouldFail() { assertThrows(RuntimeException.class, () -gt; userService.login(testexample.com, wrong)); } }Luna 完成实现后回报测试结果。主 Agent 确认测试通过即可交付。8. 上下文传递技巧子 Agent 协作的关键在于上下文传递。主 Agent 在把任务交给 Sol 或 Luna 时要尽量把上下文压缩成「必要信息」避免把无关细节一起塞过去。给 Sol 的上下文应该包含需求背景、约束条件、期望产出。给 Luna 的上下文应该包含明确的任务清单、涉及的文件路径、验收标准。下面是一个上下文传递的对比示例。不好的传递方式 主 Agent 把整个项目代码都贴给 Luna让它自己找登录接口在哪。 好的传递方式 主 Agent 告诉 Luna 任务实现 UserController 的 login 接口 文件src/main/java/com/example/UserController.java 依赖UserService 已存在直接注入使用 验收POST /api/login 返回 token上下文越精简子 Agent 的产出越稳定出错概率也越低。9. 常见问题与排查子 Agent 协作过程中常见的问题主要有三类。第一类是职责混淆。Sol 开始写代码或者 Luna 开始做架构决策都会导致产出混乱。解决办法是在 AGENTS.md 里明确边界主 Agent 分发任务时反复强调角色。第二类是上下文过载。给子 Agent 塞太多无关信息会导致它抓不住重点。解决办法是只传递任务相关的必要上下文其余信息按需提供。第三类是验收标准缺失。Luna 不知道「什么样算完成」就会产出不符合预期的结果。解决办法是在任务清单里写明验收标准例如「测试通过」「接口返回 200」。10. 总结让 Sol 当军师、Luna 当搬砖工的核心是把「思考」和「执行」分离。Sol 负责想清楚Luna 负责做出来主 Agent 负责调度和决策。三者各司其职上下文干净产出稳定。这套配置适合中大型项目尤其是需求频繁变化、代码量较大的场景。对于小型任务直接让主 Agent 完成即可不必过度拆分。建议从一个小功能开始尝试逐步调整 Sol 和 Luna 的提示词找到最适合自己项目的分工方式。