Claude-Code-Workflow/codex SUBAGENT 策略补充.md

Codex Subagent 策略补充文档

1. 核心架构特点

特点	说明
独立会话上下文	每个 subagent 有独立 agent_id，上下文完全隔离
并行执行	可同时创建多个 subagent 并行处理不同子任务
无状态恢复	close_agent 后不可恢复，需重新创建并粘贴旧输出
显式生命周期	需主动管理创建、等待、关闭全流程
无系统提示词	subagent 无内置 system prompt，需在首条消息加载角色

2. API 调用模式

2.1 标准流程

spawn_agent → wait → [send_input] → close_agent
     ↓          ↓         ↓              ↓
  创建任务   获取结果   追问纠偏      清理回收

2.2 关键 API 语义

API	作用	注意事项
spawn_agent({ message })	创建 subagent	返回 agent_id
wait({ ids, timeout_ms })	获取结果	唯一取结果入口，非 close
send_input({ id, message, interrupt })	继续交互	interrupt=true 慎用
close_agent({ id })	关闭回收	不可逆，关闭后无法恢复

2.3 常见误区

• 误区：以为 close_agent 返回结果

• 正解：wait 才是获取结果的入口，close_agent 只是清理

• 误区：timeout 超时 = 任务失败

• 正解：超时只表示未在指定时间内完成，可继续 wait 或 send_input 催促

3. 与 Claude Code Task 工具对比

维度	Codex Subagent	Claude Code Task
创建方式	spawn_agent({ message })	Task({ subagent_type, prompt })
结果获取	wait({ ids }) 显式等待	同步返回或 TaskOutput 轮询
多 agent 等待	支持批量 wait({ ids: [a,b,c] })	需分别调用或并行发起
追问/纠偏	send_input 继续交互	需 resume 参数恢复 agent
中断能力	interrupt=true 可打断	无对应机制
生命周期	需显式 close_agent 清理	自动回收
系统提示词	无，需首条消息加载角色	内置 agent 定义
上下文传递	在 message 中显式传递	部分 agent 可访问当前上下文

3.1 适用场景对比

Codex Subagent 更适合：

• 需要批量等待多个并行任务的场景
• 需要多轮交互、迭代纠偏的复杂任务
• 对 agent 生命周期有精细控制需求

Claude Code Task 更适合：

• 单次执行、快速返回的任务
• 需要利用预定义 agent 类型的场景
• 简单的并行任务分发

4. 角色加载规范（关键差异）

4.1 问题背景

Codex subagent 没有系统提示词，无法像 Claude Code 那样通过 subagent_type 自动加载角色定义。

解决方案：在 spawn_agent 的首条 message 中显式加载角色文件。

4.2 角色文件位置

~/.codex/agents/
├── cli-explore-agent.md          # 代码探索
├── cli-lite-planning-agent.md    # 轻量规划
├── code-developer.md             # 代码开发
├── context-search-agent.md       # 上下文搜索
├── debug-explore-agent.md        # 调试探索
├── doc-generator.md              # 文档生成
└── ... (共 20+ 角色)

4.3 角色加载模板

// 标准 spawn_agent 消息结构（角色路径传递，agent 自己读取）
spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

注意：角色文件由 agent 自己读取，主流程只传递路径。详见 §9.1 角色加载模式。

4.4 角色映射表

Claude subagent_type	Codex 角色文件
cli-explore-agent	~/.codex/agents/cli-explore-agent.md
cli-lite-planning-agent	~/.codex/agents/cli-lite-planning-agent.md
code-developer	~/.codex/agents/code-developer.md
context-search-agent	~/.codex/agents/context-search-agent.md
debug-explore-agent	~/.codex/agents/debug-explore-agent.md
doc-generator	~/.codex/agents/doc-generator.md
action-planning-agent	~/.codex/agents/action-planning-agent.md
test-fix-agent	~/.codex/agents/test-fix-agent.md
universal-executor	~/.codex/agents/universal-executor.md

5. 结构化交付模式

5.1 推荐输出模板

Summary:
- 一句话总结任务完成情况

Findings:
- 发现 1：具体描述
- 发现 2：具体描述

Proposed changes:
- 文件/模块：path/to/file
- 变更点：具体修改内容
- 风险点：潜在影响

Tests:
- 需要新增/更新的用例：
- 需要运行的测试命令：

Open questions:
1. 待澄清问题 1
2. 待澄清问题 2

5.2 两阶段工作流

阶段 1：澄清
  spawn_agent → 只输出 Open questions
       ↓
  主 agent 回答问题
       ↓
阶段 2：执行
  send_input → 输出完整方案

优势：减少因理解偏差导致的返工

6. 并行拆分策略

6.1 按职责域拆分（推荐）

Worker	职责	交付物	禁止事项
A（调研）	定位入口、调用链、相似实现	文件+符号+证据点	不写方案
B（方案）	最小改动实现路径	变更点清单+风险评估	不写代码
C（测试）	测试策略、边界条件	用例列表+覆盖点	不实现测试

6.2 按模块域拆分

Worker 1: src/auth/**     → 认证模块变更
Worker 2: src/api/**      → API 层变更
Worker 3: src/database/** → 数据层变更

6.3 拆分原则

1. 文件隔离：避免多个 subagent 同时建议修改同一文件
2. 职责单一：每个 subagent 只做一件事
3. 边界清晰：超出范围必须在 Open questions 请求确认
4. 最小上下文：只传递完成任务所需的最小信息

7. 消息设计规范

7.1 spawn_agent message 结构（角色路径传递）

## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

---

Goal: 一句话目标（做什么）

Scope:
- 可做：允许的操作范围
- 不可做：明确禁止的事项
- 目录限制：只看 src/auth/**
- 依赖限制：不允许引入新依赖

Context:
- 关键路径：src/auth/login.ts
- 现状摘要：当前使用 JWT 认证
- 约束条件：必须兼容现有 API

Deliverables:
- 按模板输出 Summary/Findings/Proposed changes/Tests/Open questions

Quality bar:
- 验收标准 1
- 验收标准 2

注意：角色文件路径放在 MANDATORY FIRST STEPS，由 agent 自己读取。主流程不传递角色内容。

7.2 send_input 追问模式

# 回答澄清问题
Re: Open question 1 - 答案是 XXX
Re: Open question 2 - 请按 YYY 方式处理

# 请继续输出完整方案

8. 错误处理与恢复

8.1 超时处理

wait(timeout=30s) → timed_out=true
     ↓
选项 1: 继续 wait，等待完成
选项 2: send_input 催促收敛
选项 3: close_agent 放弃

8.2 已关闭 agent 恢复

close_agent(id) → agent 不可恢复
     ↓
spawn_agent(new_message) → 创建新 agent
     ↓
在 message 中粘贴旧输出作为上下文

9. 最佳实践清单

• 角色文件路径传递：在 MANDATORY FIRST STEPS 中指定 ~/.codex/agents/*.md 路径，由 agent 自己读取
• 创建前明确 Goal/Scope/Context/Deliverables/Quality bar
• 按职责或模块域拆分，避免文件冲突
• 要求统一输出模板，便于合并
• 用 wait 获取结果，不依赖 close_agent
• 复杂任务使用两阶段工作流（先澄清后执行）
• 不要提前 close，除非确定不再需要交互
• 超时后评估是否继续等待或催促收敛
• 合并结果时检查冲突和一致性

9.1 角色加载模式（重要）

❌ 错误模式：主流程读取角色内容并传递

// 主流程读取角色文件内容
const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')

spawn_agent({
  message: `
## ROLE DEFINITION
${exploreRole}  // 内容嵌入到 message 中

## TASK
...
`
})

问题：

• message 体积膨胀，传输开销大
• 角色内容在主流程上下文中占用空间
• 不符合 agent 自主性原则

✅ 正确模式：传递路径，agent 自己读取

spawn_agent({
  message: `
## TASK ASSIGNMENT
...

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json
...
`
})

优势：

• message 精简，只传递任务相关内容
• agent 拥有完整的角色理解上下文
• 遵循 agent 自主执行原则

---

10. Subagent 深度交互准则

10.1 核心理念：充分交流优于多次调用

传统模式问题：

• 探索 → 澄清 → 规划 分离执行，上下文断裂
• 每个阶段独立 subagent，信息传递有损耗
• 多轮用户交互，体验割裂

优化理念：

• 单 subagent 深度交互 > 多 subagent 浅层调用
• 澄清与规划合并，一次完成上下文积累
• send_input 多轮对话，保持上下文连贯

10.2 澄清 + 规划合并模式

原有分离模式（Claude lite-plan）：

Phase 1: spawn explore-agent × N → wait → close
Phase 2: 主 agent 收集澄清问题 → 用户回答
Phase 3: spawn planning-agent → wait → close

优化合并模式（Codex 推荐）：

Phase 1: spawn explore-agent × N → wait (保持 agent 活跃)
Phase 2: send_input 传递澄清答案 → agent 继续生成 plan
Phase 3: wait 获取最终 plan → close

实现示例：

// ==================== 合并模式：探索 + 澄清 + 规划 ====================

// Step 1: 创建探索 agent（带规划能力）
const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')
const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md')

const agent = spawn_agent({
  message: `
## ROLE DEFINITION (DUAL ROLE)

### Primary: Exploration
${exploreRole}

### Secondary: Planning (activated after clarification)
${planningRole}

---

## TASK ASSIGNMENT

### Phase 1: Exploration
Goal: Explore codebase for "${task_description}"
Output: Structured findings + clarification questions (if any)

### Phase 2: Await Clarification (if questions exist)
Output format for questions:
\`\`\`
CLARIFICATION_NEEDED:
Q1: [question] | Options: [A, B, C] | Recommended: [A]
Q2: [question] | Options: [A, B] | Recommended: [B]
\`\`\`

### Phase 3: Generate Plan (after clarification)
Trigger: Receive clarification answers via send_input
Output: plan.json following schema

### Deliverables
- exploration.json (Phase 1)
- plan.json (Phase 3, after clarification)
`
})

// Step 2: 等待探索结果
const exploreResult = wait({ ids: [agent], timeout_ms: 600000 })

// Step 3: 解析是否需要澄清
const needsClarification = exploreResult.status[agent].completed.includes('CLARIFICATION_NEEDED')

if (needsClarification) {
  // Step 4: 获取用户回答（主 agent 处理）
  const userAnswers = collectUserAnswers(exploreResult)
  
  // Step 5: 通过 send_input 继续交互（关键：不 close）
  send_input({
    id: agent,
    message: `
## CLARIFICATION ANSWERS
${userAnswers.map(a => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')}

## NEXT STEP
Based on exploration findings and clarification answers, generate plan.json.
Follow schema: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json
`
  })
  
  // Step 6: 等待规划结果
  const planResult = wait({ ids: [agent], timeout_ms: 900000 })
}

// Step 7: 最终清理
close_agent({ id: agent })

10.3 多轮 send_input 交互模式

场景：复杂任务需要多次迭代确认

// 创建 agent
const agent = spawn_agent({ message: roleDefinition + taskPrompt })

// 第一轮：获取初步方案
const round1 = wait({ ids: [agent], timeout_ms: 300000 })

// 第二轮：用户反馈后迭代
send_input({
  id: agent,
  message: `
## USER FEEDBACK
${userFeedback}

## REQUEST
Revise the plan based on feedback. Focus on:
1. ${focusPoint1}
2. ${focusPoint2}
`
})
const round2 = wait({ ids: [agent], timeout_ms: 300000 })

// 第三轮：确认细节
send_input({
  id: agent,
  message: `
## CONFIRMATION
Plan approved with minor adjustments:
- Change task T2 scope to include ${additionalScope}
- Add dependency T1 → T3

## FINAL REQUEST
Output final plan.json with these adjustments.
`
})
const finalResult = wait({ ids: [agent], timeout_ms: 300000 })

// 清理
close_agent({ id: agent })

10.4 简化命令设计原则

原则 1：减少 Phase 数量

原有模式	优化模式
Phase 1: Explore	Phase 1: Explore + Clarify + Plan (单 agent)
Phase 2: Clarify	↑
Phase 3: Plan	↑
Phase 4: Confirm	Phase 2: Confirm (主 agent)
Phase 5: Execute	Phase 3: Execute

原则 2：延迟 close_agent

// ❌ 错误：过早关闭
const result = wait({ ids: [agent] })
close_agent({ id: agent })  // 关闭后无法继续交互
// ... 发现需要追问，只能重建 agent

// ✅ 正确：延迟关闭
const result = wait({ ids: [agent] })
// 检查是否需要继续交互
if (needsMoreInteraction(result)) {
  send_input({ id: agent, message: followUpMessage })
  const result2 = wait({ ids: [agent] })
}
close_agent({ id: agent })  // 确认不再需要后才关闭

原则 3：上下文复用

// ❌ 错误：每个阶段独立 agent，上下文丢失
const exploreAgent = spawn_agent({ message: explorePrompt })
const exploreResult = wait({ ids: [exploreAgent] })
close_agent({ id: exploreAgent })

const planAgent = spawn_agent({ 
  message: planPrompt + JSON.stringify(exploreResult)  // 需要手动传递上下文
})

// ✅ 正确：单 agent 多阶段，上下文自动保持
const agent = spawn_agent({ message: dualRolePrompt })
const exploreResult = wait({ ids: [agent] })
send_input({ id: agent, message: "Now generate plan based on your findings" })
const planResult = wait({ ids: [agent] })  // agent 自动保持探索上下文
close_agent({ id: agent })

10.5 效果对比

指标	分离模式	合并模式	提升
Agent 创建数	3-5	1-2	60-80% ↓
用户交互轮次	3-4	1-2	50% ↓
上下文传递损耗	高	低	显著 ↓
总执行时间	长（多次 spawn/close）	短（复用 agent）	30-50% ↓
结果一致性	中（多 agent 可能不一致）	高（单 agent 统一视角）	显著 ↑

10.6 适用场景判断

使用合并模式（推荐）：

• 探索 → 澄清 → 规划 流程
• 诊断 → 澄清 → 修复方案 流程
• 任何需要多阶段但上下文强相关的任务

使用分离模式：

• 多角度并行探索（不同角度独立，无需共享上下文）
• 职责完全不同的阶段（如：代码生成 vs 测试生成）
• 需要不同专业角色的场景

---

Claude → Codex 多 Agent 命令转换规范

11. 转换概述

11.1 核心差异

维度	Claude Code	Codex
角色定义	subagent_type 参数自动加载	首条 message 显式加载
并行执行	多个 Task() 调用	多个 spawn_agent() + 批量 wait()
结果获取	同步返回或 TaskOutput 轮询	wait({ ids }) 显式等待
追问/续做	resume 参数	send_input()
生命周期	自动回收	显式 close_agent()

11.2 转换原则

1. 角色前置：每个 subagent 首条消息必须包含角色定义
2. 批量等待：利用 wait({ ids: [...] }) 实现真并行
3. 结果汇聚：主 agent 负责合并多个 subagent 结果
4. 显式清理：任务完成后统一 close

12. 转换模板

12.1 Claude Task 调用转换

Claude 原始调用：

Task(
  subagent_type = "cli-explore-agent",
  run_in_background = false,
  description = "Explore: architecture",
  prompt = `
## Task Objective
Execute architecture exploration...
...
`
)

Codex 转换后：

// Step 1: 读取角色定义
const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md')

// Step 2: 创建 subagent（角色 + 任务合并）
const agentId = spawn_agent({
  message: `
## ROLE DEFINITION
${roleDefinition}

---

## TASK ASSIGNMENT

### Task Objective
Execute architecture exploration...
...

### Output Format
Summary/Findings/Proposed changes/Tests/Open questions
`
})

// Step 3: 等待结果
const result = wait({ ids: [agentId], timeout_ms: 300000 })

// Step 4: 清理（可延迟到所有任务完成）
close_agent({ id: agentId })

12.2 并行多 Agent 转换

Claude 原始调用（并行 3 个 agent）：

// Claude: 发送多个 Task 调用
const tasks = angles.map(angle =>
  Task(
    subagent_type = "cli-explore-agent",
    prompt = `Explore ${angle}...`
  )
)

Codex 转换后：

// Step 1: 读取角色定义（只读一次）
const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md')

// Step 2: 并行创建多个 subagent
const agentIds = angles.map(angle => {
  return spawn_agent({
    message: `
## ROLE DEFINITION
${roleDefinition}

---

## TASK ASSIGNMENT
Goal: Execute ${angle} exploration
Scope: ${scopeForAngle(angle)}
Context: ${contextForAngle(angle)}
Deliverables: JSON output following exploration schema
`
  })
})

// Step 3: 批量等待所有结果（关键优势）
const results = wait({
  ids: agentIds,
  timeout_ms: 600000  // 10 分钟
})

// Step 4: 汇总结果
const aggregatedFindings = agentIds.map(id => results.status[id].completed)

// Step 5: 批量清理
agentIds.forEach(id => close_agent({ id }))

13. lite-plan 命令转换示例

13.1 Phase 1: 探索阶段转换

Claude 原始实现：

// lite-plan.md Phase 1
const explorationTasks = selectedAngles.map((angle, index) =>
  Task(
    subagent_type="cli-explore-agent",
    run_in_background=false,
    description=`Explore: ${angle}`,
    prompt=`
## Task Objective
Execute **${angle}** exploration...
## Assigned Context
- **Exploration Angle**: ${angle}
...
`
  )
)

Codex 转换后：

// Step 1: 加载角色定义
const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')

// Step 2: 并行创建探索 subagent
const explorationAgents = selectedAngles.map((angle, index) => {
  return spawn_agent({
    message: `
## ROLE DEFINITION
${exploreRole}

---

## TASK ASSIGNMENT

### Task Objective
Execute **${angle}** exploration for task planning context.

### Assigned Context
- **Exploration Angle**: ${angle}
- **Task Description**: ${task_description}
- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
- **Output File**: ${sessionFolder}/exploration-${angle}.json

### MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Run: rg -l "{keyword}" --type ts
3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json
4. Read: .workflow/project-tech.json
5. Read: .workflow/project-guidelines.json

### Expected Output
**File**: ${sessionFolder}/exploration-${angle}.json
**Format**: JSON following explore-json-schema

### Success Criteria
- [ ] Schema obtained
- [ ] At least 3 relevant files identified
- [ ] JSON output follows schema exactly
`
  })
})

// Step 3: 批量等待所有探索完成
const explorationResults = wait({
  ids: explorationAgents,
  timeout_ms: 600000
})

// Step 4: 检查超时
if (explorationResults.timed_out) {
  // 部分 agent 可能仍在运行，决定是否继续等待
  console.log('部分探索超时，继续等待或使用已完成结果')
}

// Step 5: 收集结果
const completedExplorations = {}
explorationAgents.forEach((agentId, index) => {
  const angle = selectedAngles[index]
  if (explorationResults.status[agentId].completed) {
    completedExplorations[angle] = explorationResults.status[agentId].completed
  }
})

// Step 6: 清理
explorationAgents.forEach(id => close_agent({ id }))

13.2 Phase 3: 规划阶段转换

Claude 原始实现：

Task(
  subagent_type="cli-lite-planning-agent",
  run_in_background=false,
  description="Generate detailed implementation plan",
  prompt=`
Generate implementation plan and write plan.json.
## Output Schema Reference
...
`
)

Codex 转换后：

// Step 1: 加载规划角色
const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md')

// Step 2: 创建规划 subagent
const planningAgent = spawn_agent({
  message: `
## ROLE DEFINITION
${planningRole}

---

## TASK ASSIGNMENT

### Objective
Generate implementation plan and write plan.json.

### Schema Reference
Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json

### Project Context (MANDATORY)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json

### Task Description
${task_description}

### Multi-Angle Exploration Context
${manifest.explorations.map(exp => `
#### ${exp.angle}
Path: ${exp.path}
`).join('\n')}

### User Clarifications
${JSON.stringify(clarificationContext) || "None"}

### Complexity Level
${complexity}

### Requirements
- Generate plan.json following schema
- Tasks: 2-7 structured tasks (group by feature, NOT by file)
- Include depends_on for true dependencies only

### Output
Write: ${sessionFolder}/plan.json
Return: Brief completion summary
`
})

// Step 3: 等待规划完成
const planResult = wait({
  ids: [planningAgent],
  timeout_ms: 900000  // 15 分钟
})

// Step 4: 清理
close_agent({ id: planningAgent })

14. 完整工作流转换模板

14.1 Codex 多阶段工作流结构

// ==================== Phase 1: 探索 ====================
const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')
const explorationAgents = []

// 并行创建探索 agents
for (const angle of selectedAngles) {
  explorationAgents.push(spawn_agent({
    message: `
## ROLE DEFINITION
${exploreRole}

---

## TASK: ${angle} Exploration
${buildExplorationPrompt(angle, task_description)}
`
  }))
}

// 批量等待
const exploreResults = wait({ ids: explorationAgents, timeout_ms: 600000 })

// 收集结果
const explorations = collectResults(exploreResults, selectedAngles)

// 清理探索 agents
explorationAgents.forEach(id => close_agent({ id }))

// ==================== Phase 2: 澄清（可选）====================
const clarifications = aggregateClarifications(explorations)

if (clarifications.length > 0) {
  // 两阶段模式：先收集问题，再追问
  const clarifyAgent = spawn_agent({
    message: `
## ROLE: Clarification Collector

## Questions to Ask User
${clarifications.map((q, i) => `${i+1}. ${q.question}`).join('\n')}

## Output Format
List questions with options and recommended choice.
`
  })

  const clarifyResult = wait({ ids: [clarifyAgent] })

  // 主 agent 收集用户回答后，继续追问
  send_input({
    id: clarifyAgent,
    message: `
## User Responses
${userResponses.map(r => `Q: ${r.question}\nA: ${r.answer}`).join('\n\n')}

## Next Step
Proceed to generate recommendations based on responses.
`
  })

  const finalClarify = wait({ ids: [clarifyAgent] })
  close_agent({ id: clarifyAgent })
}

// ==================== Phase 3: 规划 ====================
const planRole = Read('~/.codex/agents/cli-lite-planning-agent.md')

const planAgent = spawn_agent({
  message: `
## ROLE DEFINITION
${planRole}

---

## TASK: Generate Implementation Plan
${buildPlanningPrompt(task_description, explorations, clarificationContext)}
`
})

const planResult = wait({ ids: [planAgent], timeout_ms: 900000 })
close_agent({ id: planAgent })

// ==================== Phase 4: 确认 & 执行 ====================
// ... (主 agent 直接处理用户交互)

15. 角色文件管理

15.1 角色文件结构规范

---
name: {agent-name}
description: |
  {简短描述，1-3行}
color: {blue|green|yellow|cyan|...}
---

{角色定义正文}

## Core Capabilities
...

## Execution Process
...

## Key Reminders
**ALWAYS**: ...
**NEVER**: ...

15.2 新增角色检查清单

• 文件位于 ~/.codex/agents/ 目录
• 包含 YAML front matter (name, description, color)
• 定义 Core Capabilities
• 定义 Execution Process/Workflow
• 包含 Key Reminders (ALWAYS/NEVER)
• 在 §4.4 角色映射表中添加条目

16. 常见转换问题

16.1 run_in_background 处理

Claude：run_in_background=false 表示同步等待 Codex：始终异步，通过 wait() 控制同步点

// Claude: run_in_background=false
Task(subagent_type="...", run_in_background=false, prompt="...")

// Codex: spawn + 立即 wait
const agentId = spawn_agent({ message: "..." })
const result = wait({ ids: [agentId] })  // 阻塞直到完成

16.2 resume 转换

Claude：使用 resume 参数恢复 agent Codex：使用 send_input 继续交互

// Claude: resume
Task(subagent_type="...", resume=previousAgentId, prompt="Continue...")

// Codex: send_input（需 agent 未 close）
send_input({ id: previousAgentId, message: "Continue..." })
const result = wait({ ids: [previousAgentId] })

16.3 TaskOutput 轮询转换

Claude：TaskOutput({ task_id, block: false }) 轮询 Codex：wait({ ids, timeout_ms }) 带超时等待

// Claude: 轮询模式
while (!done) {
  const output = TaskOutput({ task_id: id, block: false })
  if (output.status === 'completed') done = true
  sleep(1000)
}

// Codex: 超时等待 + 重试
let result = wait({ ids: [id], timeout_ms: 30000 })
while (result.timed_out) {
  result = wait({ ids: [id], timeout_ms: 30000 })  // 继续等待
}

17. 转换检查清单

转换 Claude 多 Agent 命令到 Codex 时，确保：

• 角色加载：首条 message 包含 ~/.codex/agents/*.md 路径
• 并行优化：多个独立 agent 使用批量 wait({ ids: [...] })
• 超时处理：设置合理 timeout_ms，处理 timed_out 情况
• 结果汇聚：主 agent 负责合并 status[id].completed
• 显式清理：任务完成后调用 close_agent
• 追问模式：需要续做时使用 send_input，不要提前 close
• 输出模板：要求 subagent 使用统一结构化输出格式

18. Skill/命令设计原则

18.1 内容独立性

Codex skill/命令文档中不应包含与 Claude 的对比内容：

• 对比表格属于转换准则（本文档），不属于最终产物
• skill 文档应专注于 Codex 机制本身的使用
• 避免引入无关上下文，保持文档简洁

18.2 模式选择灵活性

不过度约束设计思路：

• 文档提供的模式（单 agent / 多 agent / 混合）是可选方案
• 根据具体场景选择合适模式
• 主 agent 可作为协调器，灵活利用各种机制