Claude CodeからCodexへ作業を引き継ぐ：agent-handoff文書の設計と運用

2026年6月22日

Shiori

この記事について

Claude Codeで進めていた作業をCodexへ移すとき、Codexに「どこまで進んでいたか」を説明し直す手間が発生することがあります。この記事では、Claude CodeからCodexへ作業状況を渡すために設計したagent-handoff文書の内容と運用方法を紹介します。

発端：最初から説明し直すことへの疲労感

あるとき、サイトのナビゲーション構造を修正する作業をAIと進めていました。数時間かけて問題を整理し、修正方針を固め、いくつかのファイルを変更したところで、その日の作業を終えました。

翌日、Codexに続きを依頼しようとして気づいたのは、前日にClaude Codeと進めた経緯がCodexへ自動では渡らないということです。どのファイルを変更したか、何が完了して何が残っているか、どのような判断で現在の状態になったか。すべてを最初から説明する必要がありました。

この「最初から説明し直す」状況は、作業が複雑になるほど負担が大きくなります。

agent-handoff文書とは何か

agent-handoff文書は、Claude Codeでの作業を引き継いだCodexが、作業開始時に読む引き継ぎメモです。

人間のチームでも、担当者が変わるときに引き継ぎ文書を用意します。それと同じ考え方をClaude CodeからCodexへの文脈共有に適用したものです。文書の内容は以下の4項目を基本としています。

現在の作業状況：何に取り組んでいる最中か
完了済みのこと：前回のセッションで終わったこと
残タスク：次のセッションで対応が必要なこと
注意点：判断の経緯、制約、試したが機能しなかったこと

これらを簡潔にまとめたファイルを用意しておくことで、Codexへの引き継ぎ時に「このファイルを読んでから作業を再開してください」と伝えられます。

具体的な記載例

以下は実際に使用している文書の構成例です。

## 現在の作業状況

サイトのブログ記事5本を新規作成する作業を進めています。
日本語版は3本完了、英語版はまだ着手していません。

## 完了済みのこと

- `agent-handoff-documentation.md`（日本語版）の作成
- `japanese-ai-instruction-tips.md`（日本語版）の作成
- `feature-branch-conflict-retreat.md`（日本語版）の作成

## 残タスク

- 残り2本の日本語版を作成する
- 全5本の英語版を作成する
- `npm run review:content` で検証する

## 注意点

- 英語版の一人称は `I` のみ（`we` / `our` / `us` は禁止）
- `npm run build` はユーザーの明示承認なしに実行しない

`npm run agent:handoff` による生成の仕組み

このプロジェクトでは、npm run agent:handoff というコマンドでhandoff文書の雛形を生成できる仕組みを用意しました。

手動でファイルを毎回ゼロから書くのは負担が大きいため、スクリプトがgitの変更履歴を参照しながら「変更されたファイルの一覧」と「直近のコミットメッセージ」を組み合わせたドラフトを出力します。生成されたファイルは .agent-handoff/current.md に保存され、作業者が内容を確認・補足してから使用します。

生成されたファイルはコミットしません。あくまでセッション間の引き継ぎに使う一時的なメモとして扱っています。

実際の効果

handoff文書を使い始めてから、Claude CodeからCodexへ移るときの説明が短くなりました。以前は「Claude Codeでどこまで進めたか」という説明から始まっていたのが、「.agent-handoff/current.md を確認してから続きを始めてください」という一文に変わりました。

AIが前回の文脈を把握した状態で作業を再開できるかどうかは、文書の質に依存します。「完了済みのこと」と「残タスク」の区別が曖昧だったり、注意点が抽象的すぎたりすると、効果が薄くなります。最初のうちは記載が粗かったのですが、数回使ううちに「AIが必要とする情報は何か」が見えてきて、記載の精度が上がりました。

まとめ

Claude Codeのセッション内容は、Codexへ自動では引き継がれない
agent-handoff文書は「Codexが最初に読む引き継ぎメモ」として機能する
記載すべき項目は「現在の状況・完了済み・残タスク・注意点」の4つ
npm run agent:handoff で雛形を生成し、確認・補足してから使用する
文書の質が引き継ぎの精度を左右するため、繰り返し改善する