collaborating-with-claude

与 Claude Code (Codex) 协作

使用 Claude Code CLI 作为协作者，同时让 Codex 担任主要实现者。

此技能提供了一个轻量级桥接脚本（scripts/claude_bridge.py），可返回结构化 JSON，并通过 SESSION_ID 支持多轮会话。

适用场景

• 你需要第二种意见（设计权衡、边缘情况、遗漏的测试）。
• 你希望 Claude 提出或审查 统一差异（Claude 不会编辑文件）。
• 你希望在本地实现时进行多轮来回交流。

不适用场景

• 任务很简单，或只需执行一次（直接在 Codex 中完成）。
• 你需要必须通过浏览或引用来源才能获得的权威信息（Claude 可能会猜测）。
• 你可能会粘贴敏感数据（密钥、私钥、生产日志）。

核心规则

• Claude 是协作者；你负责最终结果，并且必须在本地验证更改。
• 不要直接调用 claude；始终使用桥接脚本（scripts/claude_bridge.py），以确保输出和会话处理保持一致。
• 优先提供文件和行号引用，而不是粘贴代码片段。运行桥接脚本时使用 --cd 指定仓库根目录（它会设置 claude 进程的工作目录）；如果 Claude 需要访问其他目录，则使用 --add-dir。
• 对于代码更改，要求仅输出 Unified Diff Patch，并禁止直接修改文件。
• 如果不确定参数，请务必先运行桥接脚本并使用 --help。
• 始终记录 SESSION_ID，并在后续交流中重复使用，以便保留协作上下文。
• 对于自动化，优先使用 --SESSION_ID（恢复会话）。会话选择器不可同时使用：从 --SESSION_ID、--continue 或 --session-id 中选择一个。
• 此技能启用期间，请持续更新简短的协作状态摘要。
• 默认超时：通过 Codex 命令运行器调用时，将 timeout_ms 设为 600000（10 分钟），除非明确要求更短或更长的超时时间。
• 默认模型：日常工作优先使用 sonnet；仅在任务复杂或明确要求时使用 opus。
• 运行无头命令前，确保已登录 Claude Code（如有需要，先运行一次 claude 和 /login）。
• 流式 JSON 需要 --verbose；桥接脚本会自动启用此选项。

模型选择

Claude Code 支持模型别名，因此可以使用 --model sonnet / --model opus，而无需硬编码带版本号的模型 ID。

• 如果省略 --model，Claude Code 会使用已配置的默认值（通常来自 ~/.claude/settings.json，也可能被 .claude/settings.json 和 .claude/settings.local.json 覆盖）。
• 如果需要严格复现，请通过 --model <full-name> 传入完整模型名称。

快速开始（兼容 Shell）

⚠️ 如果提示词中包含 Markdown 反引号（`like/this`），请勿通过 --PROMPT "..." 直接传入（Shell 可能会将反引号视为命令替换）。请改用 heredoc；参见 references/shell-quoting.md。

PROMPT="$(cat <<'EOF'
Review src/auth.py around login() and propose fixes.
OUTPUT: Unified Diff Patch ONLY.
EOF
)"
python3 .codex/skills/collaborating-with-claude/scripts/claude_bridge.py --cd "." --model sonnet --PROMPT "$PROMPT" --output-format stream-json

输出： JSON，包含 success、SESSION_ID、agent_messages，以及可选的 error / all_messages。

多轮会话

# Start a session
PROMPT="$(cat <<'EOF'
Analyze the bug in foo(). Keep it short.
EOF
)"
python3 .codex/skills/collaborating-with-claude/scripts/claude_bridge.py --cd "." --PROMPT "$PROMPT" --output-format stream-json

# Continue the same session
PROMPT="$(cat <<'EOF'
Now propose a minimal fix as Unified Diff Patch ONLY.
EOF
)"
python3 .codex/skills/collaborating-with-claude/scripts/claude_bridge.py --cd "." --SESSION_ID "<SESSION_ID>" --PROMPT "$PROMPT" --output-format stream-json

提示词编写模式（节省令牌）

编写 --PROMPT 时，可使用 assets/prompt-template.md 作为起点。

1) 让 Claude 自行打开文件

请提供：

• 入口文件和大致行号
• 目标和限制条件
• 输出格式（差异或分析）

避免：

• 粘贴大段代码
• 在一次请求中提出多个相互冲突的目标

2) 为代码更改强制要求安全输出

请求代码时，请在提示词末尾添加：

• OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.

3) 善用 Claude 的优势

• 替代方案和边缘情况
• UI/UX 和可读性反馈
• 审查拟议的补丁（发现风险、遗漏的测试）

验证

• 对桥接工具进行冒烟测试：python3 .codex/skills/collaborating-with-claude/scripts/claude_bridge.py --help。
• 如需创建会话：使用 --output-format stream-json 运行一条提示词，并确认 JSON 中包含 success: true 和 SESSION_ID。
• 注意：--output-format text 不会包含新生成的会话 ID；请使用 stream-json/json 来获取它。如果在 text 模式下使用 --SESSION_ID 恢复会话，桥接工具会在其 JSON 输出中回显该 SESSION_ID。

安全与防护措施

• 切勿将机密（私钥、API 密钥、助记词）粘贴到提示词中。
• 对于代码更改，请要求仅提供 Unified Diff Patch，并自行应用更改。
• 将 Claude 的输出视为建议；合并前请在本地验证（测试、代码检查、构建）。

协作状态摘要

协作期间，请在回复末尾附近更新此简短区块：

[Claude Collaboration Capsule]
Goal:
Claude SESSION_ID:
Files/lines handed off:
Last ask:
Claude summary:
Next ask:

参考资料

• assets/prompt-template.md（提示词模式）
• references/shell-quoting.md（Shell 引号与反引号）