Claude Code 与 Codex CLI 的对等协作框架。Claude 负责架构设计、代码审查和用户沟通；Codex 负责编码实现、测试调试。通过共享任务板和状态机协议保持同步。
- /teammate 硬执行规则 — 修复
/teammate不调用 skill 的问题。CLAUDE.md 新增关键词触发列表和不可跳过的 preflight 检查点。SKILL.md 重写为 STRICT EXECUTION CHECKLIST。
- Arena 模式 — 启动多个 Codex 实例，分配动态角色（架构师、批评者、务实者）进行自主辩论；Claude 只审查最终报告
- 并行协作 — 多个独立 Codex 任务并发执行，支持依赖感知
- WebUI 任务板 — 可视化仪表盘，查看任务板历史
完整变更记录见 CHANGELOG.md。
- Python 3.12+
- 已安装 Claude Code 和 Codex CLI
# 克隆并安装
git clone https://github.com/UIengF/claude-codex-teamwork.git /tmp/claude-codex-teamwork
python /tmp/claude-codex-teamwork/scripts/install.py安装脚本会将文件复制到 ~/.claude/（scripts、prompts、skills、CLAUDE.md）。如果 settings.json 不存在，会创建模板文件——请在其中设置你的 API token。
# P0 启动诊断：检查关键文件、任务板、命令依赖和可写目录
python ~/.claude/skills/teammate/scripts/startup_diagnostics.py
# 运行 teammate 单元测试
cd ~/.claude/skills/teammate/scripts && python -m pytest -v如果你是一个正在阅读本文档的 agent：克隆仓库，运行 scripts/install.py，然后阅读 skills/teammate/SKILL.md 获取完整协议。工作流入口是 scripts/codex_workflow.py，支持 serial --intent <implement|fix|refactor|test|research>、parallel、max 和 arena 模式。旧命令 implement/fix/refactor/research/test 仍兼容但会输出 deprecation warning。
| 概念 | 作用 |
|---|---|
| 任务板 | 唯一事实源：目标、任务、通信日志、共享上下文、下一步行动者 |
| 状态机 | 5 个状态（PLAN → EXECUTE → REVIEW → BLOCKED → PLAN_CHANGE）控制写权限 |
| Next Actor | 防止双写——只有被指定的一方才能修改任务板 |
| 结构化交接 | 每轮协作必须包含：已完成、待处理、决策、涉及文件 |
| 咨询通道 | Codex 阻塞时可以向 Claude 提问，Claude 回复后继续执行 |
| 模式 | 什么时候用 | 工作方式 |
|---|---|---|
| Max | 大规模重构、深度研究、高风险架构设计 | Claude 与 Codex 并行制定计划（PLAN Phase），对比方案、协商分歧，然后 Codex 逐步执行（Execute Phase）。完整的计划协商循环。 |
| 串行 | 单任务、修 bug、小重构（默认） | Claude 将单个任务分派给 Codex，审查结果后展示给用户。线性流程。 |
| Arena | 复杂设计决策，需要多角度评估 | Claude 分配动态角色（架构师、批评者、务实者等），启动多个 Codex 实例自主辩论。阻断异议需要证据支持。Claude 审查最终共识报告。 |
| 并行 | 多个互不冲突的独立子任务 | Claude 将工作拆解为带 depends_on 和 write_scope 的计划，将独立任务分派给并发 Codex 实例。按拓扑序执行。 |
agent 会根据任务复杂度自动选择模式。你也可以明确指定。
stateDiagram-v2
[*] --> PLAN
PLAN --> EXECUTE
PLAN --> BLOCKED
EXECUTE --> REVIEW
EXECUTE --> BLOCKED
EXECUTE --> PLAN_CHANGE
REVIEW --> PLAN
REVIEW --> EXECUTE
REVIEW --> BLOCKED
BLOCKED --> PLAN
PLAN_CHANGE --> PLAN
PLAN_CHANGE --> EXECUTE
各状态写权限：
| 状态 | 任务板 | 步骤 | 工作区 |
|---|---|---|---|
| PLAN | 双方可写 | 双方可写 | 不可写 |
| EXECUTE | Claude | Codex | Codex |
| REVIEW | Claude | 不可写 | 不可写 |
| BLOCKED | 双方可写 | 不可写 | 不可写 |
| PLAN_CHANGE | 双方可写 | 不可写 | 不可写 |
sequenceDiagram
participant U as 用户
participant C as Claude
participant B as 任务板
participant X as Codex
U->>C: 提交任务
C->>B: 写入计划，设置 Next Actor
C->>X: 分派（codex_workflow.py）
X->>X: 编码 / 测试 / 调试
X->>B: 写入交接，更新状态
X-->>C: 阻塞时咨询
C-->>X: 回复，继续执行
C->>B: 审查结果，设置 Next Actor
C->>U: 展示结果
sequenceDiagram
participant C as Claude
participant A1 as 架构师
participant A2 as 批评者
participant A3 as 务实者
C->>A1: 任务 + 角色 prompt
C->>A2: 任务 + 角色 prompt
C->>A3: 任务 + 角色 prompt
A1->>A1: 第 1 轮：立场分析
A2->>A2: 第 1 轮：质疑对手
A3->>A3: 第 1 轮：务实评估
Note over A1,A3: 阶段快照写入
A1->>A1: 第 2 轮：修订 + 回应
A2->>A2: 第 2 轮：修订 + 回应
A3->>A3: 第 2 轮：修订 + 回应
Note over C: Coordinator 合并报告
C->>C: 审查共识 + 少数意见
- Plan JSON — 用
task_id、template、write_scope、depends_on定义子任务，支持并行调度。 - 咨询通道 —
check_inbox.py读取 Codex 咨询；respond_codex.py回复并恢复执行。 - 历史查询 —
query_board.py按需查询任务板：--last 5、--direction claude、--search "parser"。 - 其他选项 —
--dry-run（预览 prompt）、--output（保存结果）、--zh（中文模板）。
skills/teammate/ 核心协作系统
SKILL.md 协议规范与完整文档
scripts/
arena.py 多 Agent 辩论（Arena Mode）
parallel_scheduler.py 依赖感知的并行调度
sync_task_board.py 任务板原子读写
state_machine.py 5 状态协议引擎
consult_claude.py Codex→Claude 咨询通道
query_board.py 任务板历史查询
startup_diagnostics.py P0 启动诊断
preflight.py 前置检查点
templates/ 交接和步骤的 prompt 模板
skills/codex/ Codex 端配置
SKILL.md Codex 行为规范
scripts/ask_codex.sh 分派脚本
scripts/ 共享工作流脚本
codex_workflow.py 工作流入口（串行 / 并行 / 辩论）
compose_prompt.py Prompt 模板组装
check_inbox.py Inbox 检查
respond_codex.py 回复 Codex 咨询
file_lock.py 跨平台文件锁
prompts/ Prompt 模板（implement, fix, refactor, test, research）
cd skills/teammate/scripts && python -m pytest -v