---
name: codex-collab
description: Codex 协作框架 - 让 Claude Code 和 Codex CLI 高效协作。适用于代码查找定位、需求分析、方案设计、代码审查、Bug 诊断等场景。
---

# Codex 协作框架

智能协作框架，通过 CodexMCP 协议实现 Claude Code 与 Codex CLI 的优势互补。

## 核心原则

**指导原则**：
- Codex 是协作伙伴，而非唯一真理来源
- 必须有独立思考，对 Codex 的建议保持批判性审视
- 通过辩论和讨论达成最优方案

**职责分工**：
- **Claude Code**：代码编写、文档编写、简单任务直接执行
- **Codex**：代码查找定位、逻辑梳理、代码审查、方案设计、问题诊断

**关键规范**：
- 查找/搜索任务 → 必须调用 Codex
- 方案设计阶段 → 使用 `sandbox="read-only"`
- 代码实现 → Claude Code 基于方案重写生产级代码
- 完成编码后 → 立即让 Codex 审查

## 何时使用

当用户需求涉及以下场景时，应主动使用此 skill：

1. **代码查找和定位**：搜索代码、定位功能、查找引用
2. **需求分析和方案设计**：理解业务需求、设计实施方案
3. **代码审查**：检查代码质量、发现潜在问题
4. **Bug 诊断**：分析错误原因、定位问题代码
5. **架构优化**：评估设计方案、提出改进建议

## 任务复杂度评估

### 简单任务（直接执行）
满足**所有**以下条件：
- 无生产影响（如文档、注释、简单查询）
- 无需新增基础设施或外部依赖
- 不涉及多个子系统协调

### 中等任务（Codex协作）
满足**至少一个**以下条件：
- 有限生产影响（需要测试验证）
- 需要小规模配置调整或库引入
- 需要理解模块间调用关系

### 复杂任务（深度Codex协作）
满足**至少两个**以下条件：
- 高生产影响（安全、性能、数据一致性）
- 架构变更、新基础设施、核心依赖升级
- 需要多agent协调或跨团队对齐

## 工作流程

```
简单任务：直接执行
   ↓
中等任务：[Codex]查找定位 → [Codex]逻辑梳理 → [Codex]方案设计
         → [Claude]代码实现 → [Codex]代码审查
   ↓
复杂任务：[Codex]深度分析 → [Claude+Codex]并行设计审查
         → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查
```

## Codex Tool 速查

### 必选参数
- `PROMPT` (str): 任务指令
- `cd` (Path): 工作目录根路径

### 常用可选参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `sandbox` | "read-only" | 沙箱策略 |
| `SESSION_ID` | None | 会话ID（None=新会话） |
| `return_all_messages` | False | 返回完整推理 |

### 返回值
```json
{
  "success": true,
  "SESSION_ID": "uuid-string",
  "agent_messages": "Codex响应内容"
}
```

## 会话管理

- 每次调用必须保存 `SESSION_ID`
- 同一任务的多次交互使用同一 `SESSION_ID`
- 跨任务时开启新会话

## 安全规范

1. **禁止实际修改**：要求 Codex 仅提供 unified diff patch
2. **仅作参考**：Codex 的代码原型只能作为逻辑参考
3. **重写代码**：由 Claude Code 重新编写为生产级代码
4. **即时审查**：完成编码后立即调用 Codex 进行 review

## 详细模板和示例

- **代码审查模板**：见 [references/code-review.md](references/code-review.md)
- **需求分析模板**：见 [references/requirement-analysis.md](references/requirement-analysis.md)
- **方案设计模板**：见 [references/design-proposal.md](references/design-proposal.md)
- **调试分析模板**：见 [references/debug-analysis.md](references/debug-analysis.md)
- **完整会话示例**：见 [references/complete-session.md](references/complete-session.md)