Claude CodeからCodexへ文脈を引き継ぐ：長期プロジェクトのコンテキスト設計
この記事について
Claudeのトークンを賢く節約するでは、トークン消費を削減するテクニックを整理しました。この記事では、Claude Codeで進めた作業の文脈をCodexへどう引き継ぐかに絞って、長期プロジェクトで実践していることを記録します。
問題：文脈が切れると最初からになる
トークンとは、AIが処理できる情報量の単位です。会話が長くなるほどトークン消費が増えていき、やがて古い会話は参照できなくなります。
この「文脈が切れる」問題は、Claude CodeからCodexへ作業環境を切り替える長期プロジェクトで顕著です。Codexは、Claude Codeのセッションで確認した情報、決定した方針、修正済みの問題を自動では把握しません。そのままでは「このプロジェクトは〇〇という構造で、Claude Codeでは〇〇まで進めました」という説明から始める必要があります。
説明を繰り返すこと自体がトークンを消費するため、問題が循環します。
対処1：必要な情報を構造化したファイルに書き出す
セッションをまたいで引き継ぐ情報は、ファイルとして保存しておきます。これが agent-handoff文書の設計 で紹介した仕組みです。
具体的には、作業の区切りごとに以下の情報をファイルに書き出します。
- 現在取り組んでいる作業
- 完了済みの変更
- 次のセッションで対応が必要なこと
- 判断の経緯と注意事項
Codexへ引き継ぐとき、このファイルを渡します。「Claude Codeからの引き継ぎとして、このファイルを読んでから作業を再開してください」と伝えることで、作業状況と残タスクを共有できます。
ポイントは「必要な情報だけ」を書くことです。長い説明は読み込みにトークンを使うため、箇条書きで要点だけをまとめるようにしています。
対処2：共通ルールをshared配下に集約する
Claude CodeとCodexの両方が守るルールは、shared/ 配下に集約しています。
Claude Codeは CLAUDE.md、Codexは AGENTS.md を入口として読み、どちらも同じ shared/rules/ を参照します。ツールごとの入口が異なっても、引き継ぐ方針を二重管理せずに済みます。
入口ファイルには、必ず守るルールと参照順だけを書きます。詳細を shared/ 配下へ分けることで、Claude CodeからCodexへ移っても同じ方針を必要な範囲だけ読めるようにしています。
現在のこのプロジェクトでは、詳細なルールを shared/rules/ 配下に置き、CLAUDE.md と AGENTS.md からそのパスを示す構成にしています。
対処3：会話が長くなったら新しいセッションを開始する
同じ作業を1つのセッションで長く続けると、会話履歴が積み重なって文脈が大きくなります。Claude Codeでは /compact コマンドで会話履歴を圧縮することもできますが、圧縮した要約と元の文脈は同一ではないため、細かい経緯が失われる場合があります。
Claude Code側の作業に区切りが来たら、agent-handoff文書を更新し、Codexのセッションをその文書から始める流れにしました。
この方法では「セッションを切り替えるたびに少し時間がかかる」というコストがありますが、長い会話を続けることで発生するトークン消費との比較では、セッションを適切に区切った方がコストを抑えられる場合が多いと感じています。
まとめ
- AIとの会話が長くなると文脈が切れ、説明の繰り返しが発生する
- 解決策として実践していること：
- 作業の区切りごとにagent-handoff文書へ引き継ぎ情報を書き出す
- Claude CodeとCodexの共通ルールは
shared/配下に集約する - Claude Codeの作業に区切りをつけ、引き継ぎ文書からCodexのセッションを開始する
- いずれの方法も「Codexへ最初から説明し直す手間」を減らすことが目的