【ITニュース解説】How to hand off a task from Claude Code to Codex (and back)

システム開発の現場では、プログラミング作業を効率化するために様々なツールが活用されている。近年では、人工知能（AI）を活用したコーディングアシスタントが登場し、開発者の強力な味方となっている。この記事では、AIコーディングアシスタントの中でも特に「Claude Code」と「Codex」という二つのツールを使いこなし、それぞれの得意分野を活かしながらスムーズに作業を引き継ぐ方法について解説する。システムエンジニアを目指す皆さんにとって、これらのAIツールをどのように活用し、連携させるかは、今後の開発効率を大きく左右する重要なスキルとなるだろう。

Claude Codeは主にコードの作成においてその能力を発揮するAIアシスタントであり、一方のCodexは、作成されたコードの実行やテストを得意としている。特にCodexは「Computer Use」というプラグインを持っており、これを使うことで、Mac上で開発されたアプリケーションを実際に起動し、ユーザーのように操作して、どこに問題があるかを報告させることが可能だ。このように、コード作成はClaude Codeに任せ、その後のテストはCodexで行うという役割分担は、非常に効率的な開発フローを構築できる。例えば、アプリケーションをビルドした後、Codexがそのビルドされたアプリを開き、指定された操作をシミュレートし、もしエラーが発生すればそれを検出して教えてくれる。この連携をスムーズに行うためには、Codexが新しくビルドされたものが何であり、何をチェックすべきかを、人間が改めて全て説明しなくても理解している必要がある。

しかし、これらのAIツール間で作業をスムーズに引き継ぐことには一つの課題が存在する。それは、Claude CodeとCodexが互いの会話履歴を直接開くことができない点だ。それぞれのツールは、独自の形式で会話の記録をそれぞれの専用フォルダ（Claude Codeは~/.claude/projects/、Codexは~/.codex/sessions/）に保存している。そのため、Claude CodeのセッションをCodexで読み込んだり、その逆を行ったりするような「インポート」コマンドは存在しない。つまり、タスクの引き継ぎとは、これまでの会話の全てをそのまま転送するのではなく、「新しいセッションを開始する際に、次のエージェント（AI）が作業を継続するのに十分な情報を提供する」という形になる。この情報の質が、引き継ぎの成否を決定する。

では、新しいAIエージェントに何を知ってもらう必要があるだろうか。それは、これまでの会話履歴の全てではなく、しかし最後のメッセージだけでは不十分な、具体的な「コンテキスト」だ。このコンテキストを効果的に伝えるために、「引き継ぎノート」を作成する。このノートには、次の五つの質問に対する答えを含めることが推奨される。 一つ目は、このタスク全体のゴールが何であるか。これを一、二文で簡潔にまとめる。 二つ目は、これまでに何が完了し、どのように確認されたか。 三つ目は、残っている作業は何か、そしてその作業をどのような順序で行うべきか。 四つ目は、これまでにどのような決定が下され、なぜその決定に至ったのか。これは、次のAIが不必要に以前の決定を覆してしまうのを防ぐために重要である。 五つ目は、どのファイルがこの作業に関連し、まだコミットされていない変更があるか。 これらの情報の中で、コード自体はAIエージェントが作業ディレクトリから直接読み取れるため、ノートに記載する必要はない。しかし、なぜそのようなコードになったのか、どのような意図で変更されたのかといった人間の「思考の過程」は、ノートを通じて伝える必要がある。

この引き継ぎノートを作成する最も良い方法は、現在作業を行っているAIエージェント自身に依頼することだ。そのAIは、これまでの作業でどの選択肢がうまくいかなかったか、なぜ現状のコードがそうなっているかという背景を理解しているからである。具体的には、現在のセッションに以下のプロンプトを入力する。「この作業を続ける別のコーディングエージェントのために、HANDOFF.mdというファイルに引き継ぎノートを作成してください。含まれるべき情報は、ゴール、完了した作業とその検証方法、残りの作業の順序、行われた決定とその理由、関連するファイル、そして未コミットの変更点です。具体的に記述し、次のエージェントがコードから読み取れる内容は省略してください。」 もしテストの引き継ぎであれば、アプリケーションのビルド方法、起動方法、変更された機能の流れ、そして何をもって「正常に動作している」と判断するかといったテストの詳細も追加で依頼する。ノートが作成されたら、次のエージェントに引き継ぐ前に、必ず人間がその内容を読み、誤りや不足がないかを確認することが重要だ。このノートこそが、次のエージェントが会話の全てを知る唯一の情報源となるからである。作成されたHANDOFF.mdファイルは、誤って関係ないコミットに含まれないよう、コミットするか.gitignoreに追加するのが適切だ。

新しいAIエージェントをこのノートから起動するには、同じ作業ディレクトリでターミナルを開き、最初のプロンプトとしてノートを読み込ませるコマンドを実行する。例えば、Claude CodeからCodexへ引き継ぐ場合はcodex "Read HANDOFF.md and continue the work described there."、CodexからClaude Codeへ引き継ぐ場合はclaude "Read HANDOFF.md and continue the work described there."といった形になる。これらのコマンドは、最初の引数としてプロンプトを受け取り、それを使って対話型セッションを開始する。新しいエージェントはノートを読み、そこに記載されている関連ファイルを確認し、作業を継続する。ただし、最初の数ステップは注意深く監視し、もしAIがノートに「完了した」と書かれている作業をやり直そうとする場合は、ノートの内容に修正が必要である。常に同じ作業ディレクトリを使用することも重要だ。これにより、両方のエージェントがプロジェクトの指示ファイルを読み込み、パスを正しく解決できる。異なるチェックアウトを使用すると、AIが参照するファイルが異なってしまう可能性がある。

完全な会話履歴を次のエージェントに読ませることも技術的には可能だが、これは通常推奨されない。会話履歴は、そのほとんどがツールの出力やメタデータで構成されており、すぐに巨大なファイルになるからだ。また、そのフォーマットは各ツール内部のものであり、人間にとっても読みにくい。長いセッションの履歴を読み込ませると、AIエージェントが実際の作業に取りかかる前に、そのほとんどのコンテキストウィンドウ（AIが一度に処理できる情報量）を使い果たしてしまう可能性がある。Claude Codeには/exportコマンドがあり、現在の会話をプレーンテキストとして保存できるが、これも要約ではなく会話の全文であり、同様の問題がある。

複数のAIエージェントに同じプロジェクトルールに従わせたい場合もあるだろう。これには、一つのルールファイルを共有する方法がある。例えば、Claude CodeのCLAUDE.mdファイルからAGENTS.mdファイルをインポートする（@AGENTS.mdと記述する）。これにより、Claude CodeはCLAUDE.mdの内容に加えてAGENTS.mdの内容も読み込むようになる。あるいは、CodexがCLAUDE.mdを読み込むように設定することもできる。~/.codex/config.tomlファイルにproject_doc_fallback_filenames = ["CLAUDE.md"]と追記することで、CodexはAGENTS.mdがないディレクトリではCLAUDE.mdをプロジェクトの指示ファイルとして参照するようになる。

タスクの引き継ぎで注意すべき点は、何が引き継がれ、何が引き継がれないかという点だ。まず、これまでの会話履歴そのものは引き継がれず、提供した引き継ぎノートのみが新しいエージェントに伝わる情報となる。そのため、必要な情報はすべてノート、またはコードの中に含まれている必要がある。また、権限や承認の設定も引き継がれない。例えば、Claude Codeで特定の操作を許可していても、Codexでは再度その許可を設定する必要がある。さらに、使用しているツールや統合（MCPサーバー、スキル、フック、カスタムコマンドなど）も各ツールごとに設定されるため、タスクがこれらの設定に依存する場合は、引き継ぎ先のツールでも設定を行う必要がある。最後に、元のセッションは引き継ぎ後も元のツールに残されており、必要であればいつでも元のツールでそのセッションを再開できる。

引き継ぎノートを手動で書く手間を省きたい場合もあるだろう。PonyMuxというツールには、Claude CodeやCodexのセッションに対して「Handoff」アクションが提供されている。これは、セッションの会話履歴を読み取り、自動的にMarkdown形式の引き継ぎファイルを生成してくれる機能だ。生成されるファイルには、セッションのタイトルや作業ディレクトリ、セッションの要約、直近5つのやり取り、そして完全な履歴へのパスが含まれる。その後、生成されたファイルを読み込むプロンプトとともに、別のエージェントを自動で起動してくれる。これにより、コピー＆ペーストの手間は省けるが、生成される情報はあくまで最近の会話の要約であり、人間やAIが意図的に作成した引き継ぎノートのように、タスクの背景や複雑な決定理由まで網羅しているわけではない。そのため、長期にわたる複雑なタスクの場合には、AI自身に適切な引き継ぎノートを作成させる方が、より高品質な引き継ぎが可能となる。また、圧縮形式（.jsonl.zst）で保存されたCodexセッションは、現時点ではPonyMuxによる引き継ぎに対応していない点にも留意が必要だ。

このように、AIコーディングアシスタントのClaude CodeとCodexを効果的に連携させ、タスクを引き継ぐためには、単にコマンドを切り替えるだけでなく、明確な情報伝達の仕組みを理解し、活用することが重要である。特に引き継ぎノートの作成とその内容の質が、AIがスムーズに作業を継続できるかどうかの鍵を握る。これらの知識は、システムエンジニアを目指す皆さんが将来的にAIと共に効率的な開発を行う上で、非常に役立つだろう。