skills/codex-collab/skill.md

Codex Collaboration Skill

Description

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

• Claude Code: 擅长架构设计、需求分析、代码重构
• Codex: 擅长代码生成、精确定位、细节优化

When to Use This Skill

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

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

Task Complexity Assessment

在开始任务前，必须先进行复杂度评估：

Simple Tasks (直接执行)

满足所有以下条件：

• ✅ 无生产影响（如文档、注释、简单查询）
• ✅ 无需新增基础设施或外部依赖
• ✅ 不涉及多个子系统协调

示例：查询数据、添加日志、修改文案、简单重命名

Medium Tasks (Codex协作)

满足至少一个以下条件：

• 📊 有限生产影响（需要测试验证）
• 📊 需要小规模配置调整或库引入
• 📊 需要理解模块间调用关系

示例：功能增强、Bug修复、接口调整、业务逻辑优化

Complex Tasks (深度Codex协作)

满足至少两个以下条件：

• 🔥 高生产影响（安全、性能、数据一致性）
• 🔥 架构变更、新基础设施、核心依赖升级
• 🔥 需要多agent协调或跨团队对齐

示例：新模块开发、架构重构、性能优化、安全加固

Workflow Templates

简单任务工作流

用户需求 → 快速分析 → 直接实现 → 简单自检 → 完成

中等任务工作流

用户需求 → [Codex]查找定位 → [Codex]逻辑梳理
    → [Codex]方案设计 → [Claude]代码实现 → [Codex]代码审查 → 完成

复杂任务工作流

用户需求 → [Codex]深度分析 → [Claude+Codex]并行设计审查
    → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 → 完成

Codex Tool Reference

Required Parameters

• PROMPT (str): 任务指令
• cd (Path): 工作目录根路径

Optional Parameters

参数	类型	默认值	说明
sandbox	str	"read-only"	沙箱策略：read-only / workspace-write / danger-full-access
SESSION_ID	UUID | None	None	会话ID（None表示新会话）
skip_git_repo_check	bool	False	是否允许在非Git仓库运行
return_all_messages	bool	False	是否返回完整推理信息
image	List[Path] | None	None	附加图片文件
model	str | None	None	指定使用的模型
yolo	bool	False	跳过所有审批和沙箱
profile	str | None	None	配置文件名

Return Value

{
  "success": true,
  "SESSION_ID": "uuid-string",
  "agent_messages": "Codex响应内容",
  "all_messages": [...]  // 仅当return_all_messages=True时
}

Critical Principles

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

Session Management

Starting a New Session

不传 SESSION_ID 参数，工具会返回新的 SESSION_ID

Continuing a Session

使用之前返回的 SESSION_ID 参数，保留上下文

Safety Guidelines

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

Prompt Templates

需求分析模板

请分析以下需求，并提供：
1. 需求理解和目标拆解
2. 技术方案建议
3. 风险点和注意事项
4. 实施建议

需求：{user_requirement}

代码审查模板

请审查以下代码改动，检查：
1. 代码质量和可读性
2. 潜在的bug和边界情况
3. 性能和安全问题
4. 与需求的匹配度

改动文件：{modified_files}
改动说明：{change_description}

方案设计模板

请设计以下功能的实现方案：
1. 整体架构设计
2. 模块划分和接口定义
3. 关键技术点
4. 实施步骤

功能需求：{feature_requirement}

Examples

Example 1: 代码定位和Bug修复

# 1. 调用 Codex 定位问题
codex(PROMPT="搜索项目中处理用户认证的相关代码", cd="/project")

# 2. 基于 Codex 的定位结果，Claude Code 分析问题
# 3. Claude Code 编写修复代码
# 4. 调用 Codex 审查修复
codex(PROMPT="审查以下代码改动...", SESSION_ID=previous_session)

Example 2: 新功能开发

# 1. 调用 Codex 进行需求分析
codex(PROMPT="分析以下需求并设计实施方案...", cd="/project")

# 2. 多轮讨论完善方案
codex(PROMPT="关于你的方案，我有以下疑问...", SESSION_ID=session_1)

# 3. Claude Code 基于方案编写代码
# 4. Codex 审查代码
codex(PROMPT="请审查已完成的代码实现", SESSION_ID=session_1)