collaborating-with-claude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Collaborating with Claude Code (Codex)

与Claude Code（Codex）协作

Use Claude Code CLI as a collaborator while keeping Codex as the primary implementer.

This skill provides a lightweight bridge script (

scripts/claude_bridge.py

) that returns structured JSON and supports multi-turn sessions via

SESSION_ID

将Claude Code CLI作为协作工具，同时以Codex作为主要实现工具。

本技能提供了一个轻量级的桥接脚本（

scripts/claude_bridge.py

），可返回结构化JSON，并支持通过

SESSION_ID

进行多轮会话。

When to use

适用场景

You want a second opinion (design tradeoffs, edge cases, missing tests).
You want Claude to propose or review a unified diff (Claude does not edit files).
You want multi-turn back-and-forth while you implement locally.

你需要第二意见（设计权衡、边缘情况、缺失的测试）。
你希望Claude提出或审查Unified Diff Patch（Claude不会编辑文件）。
你希望在本地实现的同时进行多轮来回沟通。

When not to use

不适用场景

The task is trivial or one-shot (do it directly in Codex).
You need authoritative facts that require browsing/citations (Claude may guess).
You might paste sensitive data (secrets, private keys, prod logs).

任务琐碎或只需单次完成（直接在Codex中操作即可）。
你需要需要浏览/引用的权威事实（Claude可能会猜测）。
你可能会粘贴敏感数据（密钥、私钥、生产日志）。

Core rules

核心规则

Claude is a collaborator; you own the final result and must verify changes locally.
Do not invoke
```
claude
```
directly; always use the bridge script (
```
scripts/claude_bridge.py
```
) so output/session handling stays consistent.
Prefer file/line references over pasting snippets. Run the bridge with
```
--cd
```
set to the repo root (it sets the
```
claude
```
process working directory); use
```
--add-dir
```
when Claude needs access to additional directories.
For code changes, request Unified Diff Patch ONLY and forbid direct file modification.
Always run the bridge script with
```
--help
```
first if you are unsure of parameters.
Always capture
```
SESSION_ID
```
and reuse it for follow-ups to keep the collaboration conversation-aware.
For automation, prefer
```
--SESSION_ID
```
(resume). Session selectors are mutually exclusive: choose one of
```
--SESSION_ID
```
,
```
--continue
```
, or
```
--session-id
```
.
Keep a short Collaboration State Capsule updated while this skill is active.
Default timeout: when invoking via the Codex command runner, set
```
timeout_ms
```
to 600000 (10 minutes) unless a shorter/longer timeout is explicitly required.
Default model: prefer
```
sonnet
```
for routine work; use
```
opus
```
only for complex tasks or when explicitly requested.
Ensure Claude Code is logged in before running headless commands (run
```
claude
```
and
```
/login
```
once if needed).
Streamed JSON requires
```
--verbose
```
; the bridge enables this automatically.

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
```
；桥接脚本会自动启用此选项。

Model selection

模型选择

Claude Code supports model aliases, so you can use

--model sonnet

--model opus

instead of hard-coding versioned model IDs.

If you omit
```
--model
```
, Claude Code uses its configured default (typically from
```
~/.claude/settings.json
```
, optionally overridden by
```
.claude/settings.json
```
and
```
.claude/settings.local.json
```
).
If you need strict reproducibility, pass a full model name via
```
--model <full-name>
```
.

Claude Code支持模型别名，因此你可以使用

--model sonnet

--model opus

，而非硬编码带版本的模型ID。

如果你省略
```
--model
```
，Claude Code将使用其配置的默认模型（通常来自
```
~/.claude/settings.json
```
，可通过
```
.claude/settings.json
```
和
```
.claude/settings.local.json
```
选择性覆盖）。
如果你需要严格的可重复性，通过
```
--model <full-name>
```
传递完整的模型名称。

Quick start (shell-safe)

快速开始（Shell安全）

⚠️ If your prompt contains Markdown backticks (

`like/this`

), do not pass it directly via

--PROMPT "..."

(your shell may treat backticks as command substitution). Use a heredoc instead; see

references/shell-quoting.md

bash

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

Output: JSON with

success

SESSION_ID

agent_messages

, and optional

error

all_messages

⚠️ 如果你的提示包含Markdown反引号（

`like/this`

），请勿直接通过

--PROMPT "..."

传递（你的Shell可能会将反引号视为命令替换）。请改用here文档；详见

references/shell-quoting.md

。

bash

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

输出： 包含

success

、

SESSION_ID

、

agent_messages

以及可选的

error

all_messages

的JSON。

Multi-turn sessions

多轮会话

bash

undefined

bash

undefined

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

undefined

undefined

Prompting patterns (token efficient)

提示模式（Token高效）

Use

assets/prompt-template.md

as a starter when crafting

--PROMPT

制作

--PROMPT

时，可使用

assets/prompt-template.md

作为模板。

1) Ask Claude to open files itself

1) 让Claude自行打开文件

Provide:

Entry file(s) and approximate line numbers
Objective and constraints
Output format (diff vs analysis)

Avoid:

Pasting large code blocks
Multiple competing objectives in one request

提供：

入口文件和大致行号
目标和约束
输出格式（差异对比 vs 分析）

避免：

粘贴大段代码块
一个请求中包含多个相互竞争的目标

2) Enforce safe output for code changes

2) 确保代码更改的输出安全

Append this to prompts when requesting code:

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

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

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

3) Use Claude for what it’s good at

3) 让Claude发挥其优势

Alternative solution paths and edge cases
UI/UX and readability feedback
Review of a proposed patch (risk spotting, missing tests)

替代解决方案路径和边缘情况
UI/UX和可读性反馈
对提议补丁的审查（风险识别、缺失的测试）

Verification

验证

Smoke-test the bridge:

python3 .codex/skills/collaborating-with-claude/scripts/claude_bridge.py --help

If you need a session: run one prompt with
```
--output-format stream-json
```
and confirm the JSON contains
```
success: true
```
and a
```
SESSION_ID
```
.
Note:
```
--output-format text
```
won’t include a newly generated session id; use
```
stream-json
```
/
```
json
```
to capture it. If you resume with
```
--SESSION_ID
```
in
```
text
```
mode, the bridge echoes that
```
SESSION_ID
```
in its JSON output.

烟雾测试桥接脚本：

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
```
。

Safety & guardrails

安全与防护措施

Never paste secrets (private keys, API keys, seed phrases) into prompts.
For code changes, request Unified Diff Patch ONLY and apply changes yourself.
Treat Claude output as suggestions; verify locally (tests, lint, build) before merging.

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

Collaboration State Capsule

协作状态胶囊

Keep this short block updated near the end of your reply while collaborating:

text

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

协作时，请在回复末尾附近更新此简短模块：

text

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

References

参考资料

```
assets/prompt-template.md
```
(prompt patterns)
```
references/shell-quoting.md
```
(shell quoting/backticks)

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