skills/codex-collab/README.md

# Codex Collaboration Skill

**智能协作框架 - 让 Claude Code 和 Codex CLI 高效协作**

## 概述

Codex Collaboration Skill 是一个专为 Claude Code 设计的协作框架，封装了与 Codex CLI 进行高效、安全协作的最佳实践。通过 CodexMCP 协议，实现两个 AI 编程助手的优势互补。

### 核心价值

- **智能任务分类**：自动判断任务复杂度，选择最优协作策略
- **标准化流程**：封装经过验证的协作模式
- **会话管理**：简化多轮对话和上下文管理
- **安全规范**：内置最佳实践和安全准则

## 快速开始

### 安装

1. 确保已安装 CodexMCP：
```bash
claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp
```

2. 将此 skill 添加到 Claude Code skills 目录：
```bash
# 默认 skills 目录：~/.claude/skills/
cp -r codex-collaboration-skill ~/.claude/skills/
```

### 基本使用

当用户需求涉及以下场景时，Claude Code 会自动启用此 skill：

- 代码查找和定位
- 需求分析和方案设计
- 代码审查
- Bug 诊断
- 架构优化

## 工作流程

### 任务复杂度评估

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

### 关键原则

1. **批判性思维**：Codex 是协作伙伴，不是唯一真理来源
2. **独立判断**：对所有建议保持审视
3. **辩论求真**：通过讨论达成最优方案
4. **安全第一**：默认使用 sandbox="read-only"
5. **会话管理**：始终追踪 SESSION_ID

## 文件结构

```
codex-collaboration-skill/
├── skill.md                    # 核心技能文档
├── README.md                   # 本文件
├── templates/                  # 工作流模板
│   ├── code-review.md         # 代码审查模板
│   ├── requirement-analysis.md # 需求分析模板
│   ├── design-proposal.md     # 方案设计模板
│   └── debug-analysis.md      # 调试分析模板
└── examples/                   # 使用示例（待添加）
```

## 模板说明

### 1. Code Review Template
用于代码审查，包含：
- 正确性检查
- 代码质量评估
- 性能分析
- 安全检查
- 测试覆盖验证
- 文档完整性

### 2. Requirement Analysis Template
用于需求分析，包含：
- 需求理解
- 技术可行性评估
- 影响范围分析
- 实施方案建议
- 风险识别
- 测试策略

### 3. Design Proposal Template
用于方案设计，包含：
- 整体设计
- 接口设计
- 数据模型设计
- 核心逻辑设计
- 技术选型
- 安全设计
- 性能考虑
- 实施计划
- 测试策略
- 部署和运维

### 4. Debug Analysis Template
用于调试分析，包含：
- 问题定位
- 影响范围分析
- 解决方案
- 预防措施
- 验证方法

## 使用示例

### 示例 1：代码审查

```python
# 完成编码后，调用代码审查模板
codex(
    PROMPT=code_review_template.format(
        modified_files="- src/auth/login.py: 添加用户登录验证",
        change_description="实现了基于JWT的用户认证",
        requirement="实现用户登录功能"
    ),
    cd="/project",
    SESSION_ID=previous_session
)
```

### 示例 2：需求分析

```python
# 新功能需求分析
codex(
    PROMPT=requirement_analysis_template.format(
        user_requirement="实现实时通知系统",
        context="SaaS平台，使用Python+FastAPI",
        constraints="需要向后兼容"
    ),
    cd="/project",
    sandbox="read-only"
)
```

### 示例 3：调试分析

```python
# Bug 定位和分析
codex(
    PROMPT=debug_analysis_template.format(
        error_message="AssertionError: User should be authenticated",
        reproduction_steps="1. 登录 2. 等待30分钟 3. 创建订单",
        context="订单创建接口需要用户认证",
        recent_changes="昨天修改了JWT解码逻辑"
    ),
    cd="/project",
    sandbox="read-only"
)
```

## Codex Tool 参数

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

### 可选参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `sandbox` | str | "read-only" | 沙箱策略 |
| `SESSION_ID` | UUID | None | 会话ID |
| `return_all_messages` | bool | False | 返回完整推理 |
| `model` | str | None | 指定模型 |

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

## 最佳实践

### DO - 推荐做法

- ✅ 使用 sandbox="read-only" 进行方案设计和审查
- ✅ 要求 Codex 仅提供 unified diff patch
- ✅ 保持批判性思维，质疑不合理的建议
- ✅ 使用 SESSION_ID 进行多轮对话
- ✅ 完成编码后立即让 Codex 审查

### DON'T - 避免做法

- ❌ 盲目接受 Codex 的所有建议
- ❌ 让 Codex 直接修改代码
- ❌ 忽略 SESSION_ID 管理
- ❌ 跳过代码审查环节
- ❌ 使用 danger-full-access 除非绝对必要

## 相关资源

- [CodexMCP 项目](https://github.com/GuDaStudio/codexmcp)
- [Claude Code 文档](https://docs.claude.com/docs/claude-code)
- [Codex CLI 文档](https://developers.openai.com/codex)

## 贡献

欢迎贡献改进建议和新的模板！

## 许可证

MIT License

---

**Made with ❤️ for better AI-assisted programming**