collaborating-with-claude

Claude Code（Codex）との協業

Codexを主な実装担当として使いながら、Claude Code CLIを協力者として活用します。

このスキルでは、構造化JSONを返し、SESSION_IDによる複数ターンのセッションに対応した軽量なブリッジスクリプト（scripts/claude_bridge.py）を提供します。

使用する場面

• セカンドオピニオン（設計上のトレードオフ、エッジケース、テスト漏れ）が必要な場合。
• Claudeに統合差分を提案またはレビューしてもらいたい場合（Claudeはファイルを編集しません）。
• ローカルで実装しながら、複数ターンにわたってやり取りしたい場合。

使用しない場面

• タスクが単純、または一度きりの場合（Codexで直接実行してください）。
• ブラウジングや引用が必要な、信頼できる事実が必要な場合（Claudeが推測する可能性があります）。
• 機密データ（シークレット、秘密鍵、本番環境のログ）を貼り付ける可能性がある場合。

基本ルール

• Claudeは協力者です。最終結果の責任は自分で負い、変更内容をローカルで検証する必要があります。
• claudeを直接呼び出さず、必ずブリッジスクリプト（scripts/claude_bridge.py）を使ってください。出力とセッションの処理を一貫させるためです。
• スニペットを貼り付けるよりも、ファイルや行番号を参照してください。ブリッジの実行時には--cdにリポジトリのルートを指定します（これにより、claudeプロセスの作業ディレクトリが設定されます）。Claudeが追加のディレクトリにアクセスする必要がある場合は、--add-dirを使用してください。
• コード変更を依頼するときは、Unified Diff Patch ONLYを要求し、ファイルの直接変更を禁止してください。
• パラメーターが不明な場合は、必ず最初にブリッジスクリプトを--help付きで実行してください。
• 必ずSESSION_IDを取得し、フォローアップで再利用して、会話の文脈を維持してください。
• 自動化では、再開用の--SESSION_IDを優先してください。セッションセレクターは相互排他です。--SESSION_ID、--continue、--session-idのいずれか1つを選んでください。
• このスキルの使用中は、短い協業状態カプセルを更新しておいてください。
• タイムアウトのデフォルト：Codexコマンドランナー経由で呼び出す場合、より短い、または長いタイムアウトが明示的に必要な場合を除き、timeout_msを**600000（10分）**に設定してください。
• モデルのデフォルト：通常の作業ではsonnetを優先してください。複雑なタスク、または明示的な指定がある場合にのみopusを使用してください。
• ヘッドレスコマンドを実行する前に、Claude Codeにログイン済みであることを確認してください。必要であれば、一度claudeを実行して/loginを行ってください。
• ストリーミングJSONには--verboseが必要です。ブリッジが自動的に有効にします。

モデルの選択

Claude Codeはモデルのエイリアスに対応しているため、バージョン付きのモデルIDを直接指定する代わりに、--model sonnet／--model opusを使用できます。

• --modelを省略した場合、Claude Codeは設定済みのデフォルトを使用します（通常は~/.claude/settings.jsonの設定で、.claude/settings.jsonや.claude/settings.local.jsonによる上書きも可能です）。
• 厳密な再現性が必要な場合は、--model <full-name>で完全なモデル名を指定してください。

クイックスタート（シェルセーフ）

⚠️ プロンプトにMarkdownのバッククォート（`like/this`）が含まれる場合、--PROMPT "..."に直接渡さないでください（シェルがバッククォートをコマンド置換として扱う可能性があります）。代わりにヒアドキュメントを使用してください。詳しくは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

出力： success、SESSION_ID、agent_messagesと、任意のerror／all_messagesを含むJSONです。

複数ターンのセッション

# 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自身にファイルを開かせる

以下を提示してください。

• エントリーファイルとおおよその行番号
• 目的と制約
• 出力形式（差分または分析）

以下は避けてください。

• 大きなコードブロックを貼り付けること
• 1つの依頼に、競合する複数の目的を含めること

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 を指定してプロンプトを1つ実行し、JSONに success: true と SESSION_ID が含まれていることを確認します。
• 注意：--output-format text には新しく生成されたセッションIDは含まれません。セッションIDを取得するには stream-json／json を使用します。text モードで --SESSION_ID を指定して再開すると、ブリッジはその SESSION_ID をJSON出力に含めます。

安全性とガードレール

• シークレット（秘密鍵、APIキー、シードフレーズ）をプロンプトに貼り付けないでください。
• コードを変更する場合は、Unified Diff Patch ONLY を要求し、自分で変更を適用してください。
• Claude の出力は提案として扱い、マージする前にローカルで検証（テスト、lint、ビルド）してください。

コラボレーション状態カプセル

共同作業中は、返信の末尾近くにあるこの短いブロックを最新の状態に保ってください：

[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（シェルのクォート／バッククォート）