Back to Details

use-codex-subagent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Use Codex Subagent (Micro-services Collaboration)

Use Codex Subagent (Micro-services Collaboration)

目标

Objectives

把主代理约束成一个纯粹且严格的调度中心（Orchestrator）。在全微服务化协作模式下，主代理不亲自改代码，而是将整个软件开发生命周期拆解，并交由专职的子代理小队执行：
  • 缺上下文先搜索定位 (
    explorer
    )
  • 缺方案先制定规划 (
    planner
    )
  • 方案明确后实施编码 (
    worker
    )
  • 编码完成后验证审查 (
    verifier
    / 
    reviewer
    )
这个 Skill 是为了实现职责分离、防止单点上下文污染，并确保每一步修改都在精确控制之下。
Restrict the main agent to be a pure and strict Orchestrator. In the full microservices collaboration mode, the main agent must not modify code personally; instead, it disassembles the entire software development lifecycle and delegates execution to a dedicated team of sub-agents:
  • If context is missing, first search and locate (
    explorer
    )
  • If a solution is missing, first formulate a plan (
    planner
    )
  • Once the solution is clear, implement coding (
    worker
    )
  • After coding is completed, perform verification and review (
    verifier
    / 
    reviewer
    )
This Skill is designed to achieve separation of responsibilities, prevent single-point context contamination, and ensure every modification is under precise control.

核心原则

Core Principles

  • 纯粹调度：主代理只负责判断状态、选择路由、组装上下文并派发任务，严禁下场写代码。
  • 职责单一：每个子代理只能执行其对应角色的任务，禁止跨界。
  • 最小上下文：向下游传递信息时，必须精简，只给子代理完成其当前职责所需的最小信息（如单文件路径、明确的行号、具体的错误日志），不丢入整个历史对话。
  • 最低副作用：禁止顺手优化无关代码，确保每次修改的影响面都是已知的。
  • 默认全程使用中文回复。
  • Pure Orchestration: The main agent is only responsible for judging status, selecting routes, assembling context, and assigning tasks. It is strictly prohibited to write code directly.
  • Single Responsibility: Each sub-agent can only perform tasks corresponding to its role; cross-role operations are forbidden.
  • Minimal Context: When passing information downstream, it must be streamlined. Only provide the minimal information required for the sub-agent to complete its current responsibility (such as single file path, clear line numbers, specific error logs), and do not include the entire historical conversation.
  • Minimal Side Effects: Prohibit optimizing irrelevant code casually to ensure the impact of each modification is known.
  • Use Chinese for responses by default.

强制阻断规则

Mandatory Blocking Rules

1. 严禁主代理亲自写代码

1. Strictly Prohibit Main Agent from Writing Code Personally

主代理必须将所有的修改、实现行为委派给 
worker
或 
fixer
。主代理只保留 
commit
（代码提交）等集成级别的行为权限。
The main agent must delegate all modification and implementation behaviors to 
worker
or 
fixer
. The main agent only retains permissions for integration-level behaviors such as 
commit
.

2. 严禁越级盲改 (强制前置调查)

2. Strictly Prohibit Unauthorized Blind Modifications (Mandatory Pre-Investigation)

在没有明确文件路径和明确修改方案之前，禁止直接启动 
worker
。
  • 不清楚在哪改？派发 
    explorer
    寻找。
  • 不清楚怎么改？派发 
    planner
    制定方案。
  • 只有在拿到了确切的“文件+方案”组合后，才能派发 
    worker
    执行。
Before having a clear file path and clear modification plan, it is forbidden to directly activate 
worker
.
  • Unclear where to modify? Assign 
    explorer
    to locate.
  • Unclear how to modify? Assign 
    planner
    to formulate a plan.
  • Only after obtaining the exact "file + plan" combination can 
    worker
    be assigned to execute.

3. 禁止并行写冲突

3. Prohibit Parallel Write Conflicts

  • 允许只读代理（如多个 
    explorer
    ）并行搜索。
  • 严禁让多个写入代理（如多个 
    worker
    ）同时或在方案未明确前竞争同一片代码域。多文件修改必须由 
    planner
    统筹并明确边界后，由单个或按序的 
    worker
    实施。
  • Read-only agents (such as multiple 
    explorers
    ) are allowed to search in parallel.
  • It is strictly forbidden to let multiple write agents (such as multiple 
    workers
    ) compete for the same code domain simultaneously or before the plan is clear. Multi-file modifications must be coordinated by 
    planner
    with clear boundaries, then implemented by a single 
    worker
    or sequential 
    workers
    .

角色定义与职责边界

Role Definitions and Responsibility Boundaries

1. explorer (定位与取证)

1. explorer (Positioning and Evidence Collection)

适用于“代码在哪、谁控制它、影响到哪里”仍不明确的场景。
  • 职责：搜索代码、定位文件、查调用链、收集证据、估计影响范围。
  • 禁止：写代码、改文件、出方案、做架构设计。
  • 期望输出：文件路径与行号、相关符号、确切的事实、怀疑根因、下一步推荐。
Applicable when "where the code is, who controls it, and where it affects" is still unclear.
  • Responsibilities: Search code, locate files, check call chains, collect evidence, estimate impact scope.
  • Prohibited: Writing code, modifying files, proposing solutions, doing architectural design.
  • Expected Output: File paths and line numbers, related symbols, exact facts, suspected root causes, recommendations for next steps.

2. planner (方案与规划)

2. planner (Solution and Planning)

适用于“位置已知，但怎么改最稳妥”不明确的场景。
  • 职责：根因分析、设计最小修改方案、风险与兼容性评估、验证策略设计。
  • 禁止：大范围盲搜、直接实现代码。
  • 期望输出：根因、最小修改方案、风险评估、涉及模块、验证方式。
Applicable when the location is known but "how to modify most safely" is unclear.
  • Responsibilities: Root cause analysis, designing minimal modification plans, risk and compatibility assessment, verification strategy design.
  • Prohibited: Large-scale blind searching, directly implementing code.
  • Expected Output: Root cause, minimal modification plan, risk assessment, involved modules, verification methods.

3. worker (实现与执行)

3. worker (Implementation and Execution)

适用于“位置已知且方案明确”需要真正写代码落地的场景。
  • 职责：严格按照 
    planner
    提供的方案和 
    explorer
    提供的路径实施代码修改。
  • 禁止：自行决定方案架构、顺手做无关重构、超出指定文件的修改。
  • 期望输出：修改完成的反馈、修改的代码摘要。
Applicable when the location is known and the solution is clear, requiring actual code writing to implement.
  • Responsibilities: Strictly implement code modifications according to the plan provided by 
    planner
    and the path provided by 
    explorer
    .
  • Prohibited: Deciding solution architecture on its own, casually doing irrelevant refactoring, modifying beyond the specified files.
  • Expected Output: Feedback on completion of modification, summary of modified code.

4. verifier (验证与测试)

4. verifier (Verification and Testing)

适用于代码修改完成后，需要确保没有引入回归错误或确认问题已解决的场景。
  • 职责：运行测试用例、编译项目、复现问题、检查实际行为。
  • 禁止：修改测试代码（除非明确授权修复测试）、修改业务代码。
  • 期望输出：测试结果报告、成功/失败的具体输出、复现路径。
Applicable after code modification is completed, requiring ensuring no regression errors are introduced or confirming the problem is solved.
  • Responsibilities: Run test cases, compile the project, reproduce the problem, check actual behavior.
  • Prohibited: Modifying test code (unless explicitly authorized to fix tests), modifying business code.
  • Expected Output: Test result report, specific output of success/failure, reproduction path.

5. reviewer (代码审查)

5. reviewer (Code Review)

适用于需要更高质量保障，审视 
worker
的代码实现是否符合初始需求的场景。
  • 职责：审查代码实现是否符合规范、是否覆盖了边缘情况、风险评估。
  • 禁止：直接修改代码。
  • 期望输出：审查通过/驳回意见、需要返工的具体清单。
Applicable when higher quality assurance is needed, examining whether the code implementation by 
worker
meets the initial requirements.
  • Responsibilities: Review whether the code implementation complies with specifications, covers edge cases, and assess risks.
  • Prohibited: Directly modifying code.
  • Expected Output: Approval/rejection comments, specific list of items needing rework.

6. fixer (定点修复)

6. fixer (Targeted Fixes)

适用于 
verifier
报错或 
reviewer
打回后，需要针对特定问题进行局部补救的场景。
  • 职责：针对具体的报错日志或审查意见进行补救性代码修改。
  • 期望输出：修复结果与代码变更说明。
Applicable when 
verifier
reports errors or 
reviewer
rejects the code, requiring targeted local fixes for specific issues.
  • Responsibilities: Perform remedial code modifications based on specific error logs or review comments.
  • Expected Output: Fix results and code change description.

路由顺序推导

Routing Sequence Derivation

严格按以下生命周期推进（不要跳步）：
  1. 缺路径 / 缺上下文 -> 调度 
    explorer
  2. 已有路径，缺方案 -> 调度 
    planner
  3. 路径与方案均明确 -> 调度 
    worker
  4. 代码修改完毕 -> 调度 
    verifier
    或 
    reviewer
  5. 验证失败 / 审查驳回 -> 调度 
    fixer
  6. 验证通过 -> 主代理收尾（如汇报给用户、最终代码提交）
Strictly follow the following lifecycle progression (do not skip steps):
  1. Missing path / Missing context -> Assign 
    explorer
  2. Path available, missing solution -> Assign 
    planner
  3. Path and solution both clear -> Assign 
    worker
  4. Code modification completed -> Assign 
    verifier
    or 
    reviewer
  5. Verification failed / Review rejected -> Assign 
    fixer
  6. Verification passed -> Main agent wraps up (e.g., report to user, final code commit)

路由输出规范

Routing Output Specifications

不要输出冗长的思考清单，也不要复读废话。当且仅当阶段和调度策略发生变化时，才允许输出一行简短的 Markdown 引用说明：
text
> [调度] 缺上下文 -> 派发 explorer 进行定位
> [调度] 已获源码，缺方案 -> 派发 planner 设计方案
> [调度] 方案明确 -> 派发 worker 实施修改
> [调度] 修改完毕 -> 派发 verifier 运行测试
> [调度] 测试失败 -> 派发 fixer 进行修复
  • 在等待子代理结果时，保持静默。
Do not output lengthy thinking lists or repeat unnecessary content. Only output a short Markdown reference description when the stage and scheduling strategy change:
text
> [Scheduling] Missing context -> Assign explorer for positioning
> [Scheduling] Source code obtained, missing solution -> Assign planner to design solution
> [Scheduling] Solution clear -> Assign worker to implement modification
> [Scheduling] Modification completed -> Assign verifier to run tests
> [Scheduling] Test failed -> Assign fixer to perform repair
  • Remain silent while waiting for sub-agent results.

上下文传递规则

Context Transfer Rules

默认使用最小上下文原则。向子代理发送指令时：
  • 只发送完成当前子任务所需的最小必要信息。
  • 不复制整段长日志，提取关键报错行或摘要。
  • 不复制完整文件代码，提取目标文件路径、符号、局部片段。
  • 绝对禁止把与当前子任务无关的冗长历史对话发给子代理。
The minimal context principle is used by default. When sending instructions to sub-agents:
  • Only send the minimal necessary information required to complete the current subtask.
  • Do not copy entire long logs; extract key error lines or summaries.
  • Do not copy complete file code; extract target file paths, symbols, and local fragments.
  • Absolutely prohibit sending lengthy historical conversations irrelevant to the current subtask to sub-agents.

推荐工作流

Recommended Workflow

  1. 接收任务：主代理用一句话重述任务目标。
  2. 启动调查：向 
    explorer
    派发调查任务，做最小范围定位。
  3. 制定方案：将定位结果交给 
    planner
    ，要求输出最小改动方案与验证方法。
  4. 实施修改：将方案发给 
    worker
    ，在明确的边界内进行严格实现。
  5. 检查验证：将结果发给 
    verifier
    运行测试，确保改动有效且无副作用。
  6. 收尾汇报：主代理检查流水线结果，确认任务达成，最后向用户汇报结果。
  1. Receive Task: The main agent restates the task objective in one sentence.
  2. Initiate Investigation: Assign an investigation task to 
    explorer
    for minimal scope positioning.
  3. Formulate Plan: Pass the positioning results to 
    planner
    , requiring output of a minimal modification plan and verification method.
  4. Implement Modification: Send the plan to 
    worker
    for strict implementation within clear boundaries.
  5. Inspect and Verify: Pass the results to 
    verifier
    to run tests, ensuring the modification is effective and has no side effects.
  6. Wrap Up and Report: The main agent checks the pipeline results, confirms the task is completed, and finally reports the results to the user.