Claude CodeからCodexへ移行する際のベストプラクティス

この記事では、Claude CodeからCodexへ移行する際のベストプラクティスを解説します。

この記事は、Claude CodeからCodexへの移行を検討している開発者、テックリード、VPoE、AI駆動開発を推進する開発責任者向けに解説します。

結論を先に言うと、Codex標準で用意されている移行機能（Codexデスクトップアプリの Import 機能）は、使わない方がいいです。その理由はこの記事で順に解説していきます。

この記事でわかること

Claude CodeからCodexへ移行する全体像
CLAUDE.mdをAGENTS.mdへ移す考え方
skills・hooks・MCP・subagentsの移行ポイント
個人利用とチーム利用で異なる運用設計
移行後の検証方法とチェックリスト
移行時によくある失敗と回避策

まず: Claude CodeからCodexへ何を移行する必要があるのか

Claude CodeからCodexへ移行するとき、移行対象になる設定は次の6種類です。

CLAUDE.md（プロジェクト指示書）
Skills（Agent Skills）
Subagents（サブエージェント）
Slash commands（スラッシュコマンド）
MCP servers（MCP サーバー設定）
Hooks（フック）

それぞれのファイル形式と配置場所、Codex側の対応関係をまとめると次の通りです。

移行対象	Claude Code 側のパス	Codex 側のパス	形式の違い
プロジェクト指示書	`CLAUDE.md`	`AGENTS.md`	同じ Markdown
Skills	`.claude/skills/{name}/SKILL.md`	`.agents/skills/{name}/SKILL.md`	同じ Markdown
Subagents	`.claude/agents/{name}.md`	`.codex/agents/{name}.toml`	Markdown → TOML（形式変換）
Slash commands	`.claude/commands/{name}.md`	skills へ統合（`.agents/skills/{name}/SKILL.md`）	概念マッピング
MCP servers	`settings.json` の `mcpServers`	`config.toml` の `[mcp_servers]`	JSON → TOML（形式変換）
Hooks	`settings.json` の `hooks`	Codex hooks	発火条件の見直し

大事なポイントは、ファイル名・配置パスだけが違って中身は同じもの（CLAUDE.md・Skills）と、形式自体を変換する必要があるもの（Subagents・MCP servers）が混在している、という点です。これが後で重要になります。

AIDDでは、移行支援を行う際、まず記事生成やレビューなど影響範囲の小さいワークフローからCodexへ移行し、AGENTS.mdやskillsの運用が安定してから本番開発へ広げることを推奨しています。

Codex標準の移行機能と、そのデメリット

Codex は公式に移行機能を用意しています。Codex デスクトップアプリの Settings → General → Import other agent setup → Import ボタンを押すと、Claude Code の設定ディレクトリを自動で検出して、Codex 側にインポートしてくれます。

これだけ聞くと「便利そう、まずこれを使おう」と感じるはずですが、実際にはこのインポートはただのファイルコピー機能です。

確認したい人は Codex リポジトリの external-agent-migration クレートを見てください。fs::copy と fs::write のみ使用、シンボリックリンクの呼び出しはありません。

コピー方式だと何が困るのか

インポート直後は次の状態になります。

~/.claude/CLAUDE.md と ~/.codex/AGENTS.md は 別ファイル
~/.claude/skills/ と ~/.agents/skills/ は 別ディレクトリ
元の ~/.claude/ は 削除されない（コピー元として残る）

これが問題になるのは、Claude Code と Codex を併用したい場合、または Codex に移してみたが Claude Code に戻る可能性がある場合 です。コピーした後はファイルが分かれているので、片方を編集してももう片方には反映されません。気付かないうちに両方のルールファイルが別々に育って、どちらが正本か分からなくなります。

「Codex に完全移行して Claude Code を二度と使わない」と決まっているなら、Desktopアプリの自動インポートで構いません。でも実際には Claude Code にも未練を残す人が多いはずなので、最初からファイルを物理的に共有する方式で組んでおくのが安全です。

解決策: シンボリックリンクで一元管理する

コピーではなくシンボリックリンクで Claude Code と Codex から同じファイルを参照させれば、二重管理問題は起きません。片方を編集すれば必ず両方に反映されます。

ただし、すべての設定ディレクトリ（CLAUDE.md・ユーザー skills・プロジェクト skills など複数階層）をユーザーが手動で ln -s するのは現実的ではありません。そこで、この作業を自動化するスキル claude-to-codex を配布します。

ダウンロード

📦 claude-to-codex.zip（6.5KB / SKILL.md・scripts/・agents/ 一式）

インストール

$ curl -O https://aidd.jp/downloads/claude-to-codex.zip
$ unzip claude-to-codex.zip -d ~/.claude/skills/

これで ~/.claude/skills/claude-to-codex/ にスキルが配置されます。Claude Code を再起動すれば、スキルとして認識されます。

使い方

プロジェクトルートで以下を実行します。

# dry-run: 実際の書き込みなしで、何が起きるかだけ表示
$ python ~/.claude/skills/claude-to-codex/scripts/claude_to_codex.py --dry-run

# 本実行
$ python ~/.claude/skills/claude-to-codex/scripts/claude_to_codex.py

# 既存ファイルと競合した場合はバックアップして置換
$ python ~/.claude/skills/claude-to-codex/scripts/claude_to_codex.py --force

冪等に動くので、何度実行しても安全です（既に正しいリンクが貼られていればスキップ）。Python 3.10 以上、標準ライブラリのみで動きます。--force はタイムスタンプ付き .codex-backup-YYYYMMDD-HHMMSS でバックアップを残してから置換します。

スキルが処理する内容

対象	処理
ユーザールール `~/.codex/AGENTS.md`	`~/.claude/CLAUDE.md` へシンボリックリンク
プロジェクトルール `./AGENTS.md`	`./CLAUDE.md` へシンボリックリンク
ユーザー skills `~/.agents/skills/`	`~/.claude/skills/` へシンボリックリンク
Codex ユーザー skills `~/.codex/skills/<skill>/`	各 `~/.claude/skills/<skill>/` へ個別にシンボリックリンク
プロジェクト skills `./.agents/skills/`	`./.claude/skills/` へシンボリックリンク
SKILL.md フロントマター	未クォートで `:` を含む値を YAML として正しく整形
ユーザー subagents `~/.claude/agents/*.md`	`~/.codex/agents/.toml` へ形式変換コピー*
プロジェクト subagents `./.claude/agents/*.md`	`./.codex/agents/.toml` へ形式変換コピー*

注意点: サブエージェントだけはシンボリックリンクではなく形式変換コピー

1点だけ注意があります。シンボリックリンクで共有できない例外が subagents（サブエージェント） です。理由はシンプルで、Claude Code の subagent は YAML フロントマター付き Markdown、Codex の subagent は TOML と、根本的にファイル形式が違うからです。リンクを貼っても Codex が読めません。

変換前（Claude Code: `.claude/agents/reviewer.md`）

---
name: reviewer
description: PRレビュー担当。正確性とセキュリティに集中する
tools: Read, Grep, Glob
---

コードのレビューを行います。
所有者目線で、正確性とセキュリティを最優先してください。

変換後（Codex: `.codex/agents/reviewer.toml`）

name = "reviewer"
description = "PRレビュー担当。正確性とセキュリティに集中する"
developer_instructions = """
コードのレビューを行います。
所有者目線で、正確性とセキュリティを最優先してください。
"""

このスキルは Claude Markdown を正本 として、TOML を変換物として再生成する運用です。

Claude Code 側で .claude/agents/reviewer.md を編集 → スクリプトを再実行 → .codex/agents/reviewer.toml が自動更新
Codex 側で TOML を直接編集すると、次回スクリプト実行で Claude Markdown から再生成されて 上書きされる

両方向で編集したい場面もあるかもしれませんが、ここはどうしようもありません。Claude Code 側を編集 → スクリプト再実行 という運用で諦めてください。毎回手で叩くのが面倒なら、Claude Code の hook（PostToolUse / Stop など）に仕込んで自動実行する方法もあります。

Claude CodeからCodexへの移行でよくある質問

CLAUDE.mdはそのままAGENTS.mdへコピーできますか？

推奨しません。プロジェクトルール、Claude Code固有設定、古い指示を整理してから移行することをおすすめします。

skillsはそのまま使えますか？

Markdown形式のskillsは共有できますが、Claude Code固有の記述がないか確認してください。

subagentsはそのまま移行できますか？

できません。Claude CodeのMarkdown形式から、CodexのTOML形式へ変換が必要です。

Claude CodeとCodexは併用できますか？

可能です。ただし、CLAUDE.mdとAGENTS.mdの正本（SSOT）を決めることを推奨します。

Codexへの移行は小規模なリポジトリから始めるべきですか？

はい。まずは影響範囲の小さいリポジトリで検証し、skillsやMCP、承認ルールが適切に機能するか確認してから利用範囲を広げることをおすすめします。

まとめ

Claude Code から Codex への移行対象は、CLAUDE.md・Skills・Subagents・Slash commands・MCP・Hooks の6種類
Codex 標準の移行機能（Desktopアプリの Import）はただのファイルコピー。併用や Claude Code への戻りを考えるなら使わない方がいい
代わりに claude-to-codex.zip をダウンロードして実行すれば、シンボリックリンクで一元管理できる
subagents だけは形式が違う（Markdown vs TOML）ため、スキルが自動で変換コピーする。Claude Markdown が正本として運用する

まずは --dry-run で何が起きるか確認してから本実行してください。

この記事を書いた人