codex-bridge

codex-bridge

这个 skill 解决的问题

Claude Code 通过 Bash 直接调用 codex exec 时，只有 prompt 字符串能传给 Codex。结果：

• •当前对话讨论过的方向、ruled-out 的方案 → 丢失
• •plan / 主件代码引用但没 inline 的文件 → Codex 看不到
• •项目约定（CLAUDE.md / AGENTS.md） → 丢失
• •"我已经试过 X、确认 Y" 等隐性信息 → 丢失

本 skill 把"显性外化上下文"变成强制工作流。

角色分工：Claude Code 全面把控 / Codex 补细节盲点（v1.2 新增，根本设计原则）

Claude Code 和 Codex 在协作中角色非对称、能力互补：

Codex 补的"细节维度"：

• •schema 字段引用准确性（Claude Code 容易写 finding.reason 但实际 schema 字段是 finding.content —— Round 4 / Round 7 都证实）
• •文件位置 / section 引用准确性（Claude Code 容易引用不存在的 section —— Round 4 / Round 7 都证实）
• •实施步骤的边界 case（fail vs warn 选择 / 错误处理 / 并发安全 / 防递归）
• •测试覆盖完整性（fixture 是否含正例 + 多种负例 + 组合边界）
• •增量编辑后的全篇一致性（远端文档 / heading / frontmatter 是否同步）
• •隐藏假设暴露（plan 没明说的事）
• •文档真源冲突（多处描述同一规则但措辞不一致）

Codex 的副职（允许但不是主要价值）：发现业务逻辑 / 规划层面的问题也欢迎指出，但不是 Codex 的核心价值。前 7 轮 dogfood 证明 Codex 的最大价值在 Claude Code 单干会漏的细节——业务规划上 Claude Code 通常更强（因为它有完整对话上下文）。

为什么这样设计：

• •Claude Code 与用户直接对话，知道完整 context 和业务意图，适合做战略 + 用户接口
• •Codex 独立于 Claude Code，能跳出 Claude Code 的"自圆其说"盲点（dogfood 7 轮证据）
• •Claude Code 把战略决策权让出去 → "不盲目吸收"discipline 崩 → skill 退化为 "Claude Code 转述 Codex 的话"，失去核心价值

含义（每次 Claude Code 调 Codex 时记住）：

• •Claude Code 决定何时调 Codex / 什么 scenario / 如何打包 bundle / 如何综合 Codex 反馈
• •Codex 给 finding 和 suggestion，但接受/拒绝/部分接受始终是 Claude Code 的判断
• •用户保留最终拍板权——Claude Code 综合后的修订版 plan / 代码呈现给用户

反例（违反角色分工）：

• •❌ Claude Code 让 Codex 直接改代码并接受不审 → 失去 control
• •❌ Codex 说"建议改 X"，Claude Code 不判断直接应用 → 盲目吸收
• •❌ Claude Code 把 Codex finding 原文转给用户让用户自己决定 → 推卸综合责任
• •❌ Codex 试图主导战略 / 用户问 Codex "用哪种架构"（直接让 Codex 回答）→ 角色错位（应由 Claude Code 综合后回答）

触发条件

自然语言触发词：

• •让 Codex 审一下 / Codex 看看这个 plan / Codex 复核
• •交给 Codex 编码 / 让 Codex 实现 / 用 Codex 写
• •Codex review / 跑 Codex / Codex 二审
• •让 Codex 改一下 / Codex 修改一下

显式 slash：/codex-bridge

Skill 激活情境下的隐式触发（v1.2 新增）

前提：用户已主动触发 codex-bridge skill（通过 /codex-bridge 或自然语言触发词；见上方"自然语言触发词"主段）。

规则：在 skill 已激活的同一用户任务里，Claude Code 写完任何 plan 文件后，必须先用 plan-review scenario 让 Codex 审一遍（不需要用户每次再说"让 Codex 审"），综合 finding（按 step 11.5/11.6 走 pattern extraction）后再呈现 plan 给用户。

激活范围：当前用户任务 / 当前 codex-bridge 工作流（不是机械意义上的"整个对话窗口"——长会话、压缩后的会话、用户切换到无关任务都不算激活）。

失活条件（出现任一即失活）：

• •用户明确切换话题（如"先放下 codex-bridge，帮我看下 X"）
• •用户明确表示不要用 Codex（如"这事不用 codex 了"）
• •当前用户任务交付结束（plan 实施完毕 / 用户表示满意）
• •进入纯解释 / 闲聊 / 元讨论而非任务执行

重审条件（防循环）：同一 plan 经 Codex 审过后小修不重新触发；只有重大改写（核心机制变更 / scope 重大扩展 / 新增设计决策）才重新触发 plan-review。防止"修一处就重审一遍"的无限循环。

为什么不是"自动触发"：

• •skill 是否启用由用户决定——用户没说要用 codex-bridge，Claude Code 不应自作主张调 Codex
• •一旦用户决定用 skill 了，"Claude Code 写完 plan 不能直接给用户看，必须先经 Codex" 是 skill 内部的隐式工作流，不需要用户每个 plan 都再次确认

正反例：

• •✅ 用户："帮我用 codex-bridge 规划这个小功能" → Claude Code 写 plan → 隐式调 plan-review → 综合 → 呈现 plan 给用户
• •✅ 用户："/codex-bridge 帮我做..." → 同上
• •✅ 用户在已激活的 codex-bridge 任务里继续："那再帮我规划下一步" → Claude Code 写 plan → 仍然隐式调（skill 还激活着）
• •❌ 用户："帮我规划一下做个 X 功能"（没提 codex / skill）→ Claude Code 写 plan → 不应该自作主张调 Codex
• •❌ 用户："让 Claude Code 改一下 README"（与 codex 无关）→ 不应该调

例外：plan mode 限制 codex exec。Plan mode 内的 plan 视为 provisional draft，ExitPlanMode 后立即跑 plan-review，综合 finding 后再实施或再请用户拍板。

理由：Claude Code 单干写 plan 经常出 2 类问题——schema 字段误读、引用不存在的文件位置（Round 4 / Round 5 / Round 7 都验证了）。让 Codex 在用户看到 plan 前先过一遍，能把 v1 plan 的"草稿质量"提升到 v2 的"审过的质量"。

四个场景（v1.1 起）

codify + review-iteration 组合最多两轮，第二轮后强制结束。 verification-round 用 manifest.purpose 字段标记，不占 codify 的 2 轮硬上限。

强制执行清单（每次必走）

1. 识别场景：plan-review / codify / review-iteration / verification-round
2. 创建 bundle 目录：跑 scripts/create-bundle.sh <scenario>（推荐——自动建目录、复制 schema、初始化 manifest）；或手动 mkdir -p <project>/.codex-bridge/round-<n>/files
3. 过 [checklist](./checklist.md) self-audit
4. 填写 request.md：复制对应场景的 templates/<scenario>/request.md，替换所有 {{VAR}}
5. inline 文件：把 plan 引用的所有相关文件完整复制到 bundle/files/（效果优先，不省 token）
6. 蒸馏 conversation.md：

- 最近 15 条人类↔Claude 交互，每条 1-3 行人话总结 - 此前会话摘要 1 段 - 当前 session JSONL 绝对路径（结构见 jsonl-guide）

1. 拷贝 schema：把对应场景的 templates/<scenario>/response.schema.json 复制到 bundle
2. 写 manifest.json：见 conventions.md
3. 调用 codex：

```bash codex exec \ --cd "<project-absolute-path>" \

--skip-git-repo-check \ -o "<bundle>/response.json" \ < "<bundle>/request.md" ```

注意： - 不要用 --output-schema——在 codexapi 代理下会触发 502 Bad Gateway。schema 文件仍保留作为 prompt 里描述结构的参考（在 request.md §6 / §8 引用），但 CLI 不传它。 - 必须用 stdin (< request.md) 而不是 "$(cat ...)" 命令参数，避免长 inline 触发 shell 参数长度限制。 - --skip-git-repo-check 适用 greenfield 目录；对 git 仓库也无害。

1. 读回 response 并严格校验（替代 --output-schema 协议层校验）：

a) JSON 合法: jq empty <bundle>/response.json

b) Required 字段存在: ``bash jq -e 'has("task_understanding") and has("result") and has("key_findings") and has("specific_suggestions") and has("open_questions") and has("uncertainty")' <bundle>/response.json ``

c) 字段类型正确: ```bash jq -e '

' <bundle>/response.json ```

d) `key_findings[].type` 全在 enum 内: ```bash

```

e) plan-review 场景额外：每个 key_findings 含 dimension 且属于 4 维枚举： ```bash

```

f) codify / review-iteration 场景额外：has("files_changed") + files_changed.{created,modified,deleted} 都是数组： ```bash

```

g) plan-review 场景额外：4 维 dimension 必须全覆盖（不只单项 enum 合法）： ```bash

```

h) 任一检查失败 → 报错并保留 bundle 让用户决定（重跑 / 人工降级）

1. 渲染 response.md：把 JSON 转成人类可读 markdown 给用户看

11.5. Pattern Extraction（v1.1 新增，判断式 + 强制给理由）

对每条 accepted finding（type ∈ risk / hidden_assumption / disagreement）问 3 个问题，写到 <bundle>/extracted-patterns.md：

a) finding.content + related_files 指向什么根因？（参考 Codex 在 result 字段的整体定性） b) 根因是否可能在项目内其他地方复现？ c) 如何具体搜索验证？

强制纪律： - 提取的每个 pattern 必须给"为什么这是 pattern" 理由 - 判定"无 pattern" 的每条 finding 必须给"为什么不是 pattern" 理由 - 空白或隐式跳过 = checklist fail

如果全部 findings 都判 pattern 无：extracted-patterns.md 仅含"无 pattern" 段（每条仍要给理由），跳到 step 12。

11.6. Lateral Verification + 验证轮（v1.1 新增，如有 pattern）

a) 按 extracted-patterns.md 里的搜索方法在项目内执行（grep / find / cat） b) candidates 写回 extracted-patterns.md "横向查证结果" section c) 如有 candidates： - 跑 scripts/create-bundle.sh verification-round - 手动设 manifest.purpose = "verify round-<N> extrapolations" - inline 主轮 response.json + extracted-patterns.md 到验证轮 files/ - 跑 codex exec（同 plan-review 调用方式） - 校验返回（verification schema 的 7 步 jq 校验，见 templates/verification-round/prompt-notes.md） - 综合主轮 finding + 验证轮 verdict 更新 v2 plan / 代码 d) 如无 candidates：跳到 step 12（明示）

1. 判定下一步（如走了 11.6 验证轮，必须综合主轮 + 验证轮的 verifications & additional_findings）：

- plan-review：结束 - codify Round 1：写 claude-review.md → 评估是否需要 Round 2 - review-iteration Round 2：必须结束，不允许 Round 3 - verification-round：本身是 sub-round，决策由触发它的主轮承担

不要做的事

• •❌ 用单行 prompt 字符串调 codex（绕过 bundle）
• •❌ 省略 inline 文件（Codex 看不到就没意义）
• •❌ 超过 2 轮迭代
• •❌ 异步 polling（Bash 调用本身同步阻塞）
• •❌ 不写 conversation.md

失败处理

• •codex exec 返回非 0：报错给用户，保留 bundle 供调试，更新 manifest.status="failed"
• •response.json 不符合 schema：Claude Code 用 jq 验证 required 字段（CLI 不再做协议层校验，因 --output-schema 在 codexapi 代理下 502）；报错让用户决定重跑或人工降级
• •response.json 不存在但 exit code = 0：异常情况，保留 stderr 供诊断
• •codex 进程超时 / 用户中断（SIGINT）：保留 bundle，manifest.status="failed"，向用户提示
• •文件 inline 失败：必须报错，不能静默跳过
• •无 git 项目（codify 需要 git 校验）：见 codify prompt-notes 的 mtime 快照 fallback
• •JSONL 在 sandbox 下不可读：见 jsonl-guide 的 sandbox 验证步骤
• •pattern extraction 跳过且未给理由（v1.1）：checklist fail，要求重写 extracted-patterns.md 含理由
• •验证轮 codex exec 失败（v1.1）：不阻断主流程；记录到 manifest.notes 警告，Claude Code 用主轮 findings 继续

相关文档

• •checklist.md — 写 bundle 前必过的 self-audit
• •conventions.md — bundle 目录与文件约定
• •jsonl-guide.md — Claude Code 会话 JSONL 结构指南
• •templates/plan-review/ — plan 审阅场景模板
• •templates/codify/ — Codex 编码场景模板
• •templates/review-iteration/ — Codex 二轮修改场景模板
• •templates/verification-round/ — Codex 验证轮场景模板（v1.1 新增）