Claude CodeとCodex設定同期｜CLAUDE.mdのズレ防止

同一リポジトリで Claude Code と Codex を併用すると、CLAUDE.md と AGENTS.md、Skills、hooks、MCP がホストごとに分岐しやすくなります。

📑目次

Claude Code と Codex の設定差分サマリー
なぜ Claude Code と Codex の設定はすぐズレるのか
公式仕様で押さえる読込ルール（CLAUDE.md と AGENTS.md）
設計パターン比較｜一本化・正本＋アダプタ・peer同期・専用ツール
導入チェックリスト｜同期する面を選び、差分を潰す
よくある失敗と避け方
よくある質問（FAQ）
まとめ｜次にやること

片側だけ直したつもりが、もう片方のエージェントには古い規約が残る——という事故は、人気ツールの話題というより、公式が別々の discovery を定義している構造問題です。

この記事では、次を実務向けにまとめます。

公式の読込仕様を基準にした差分の表整理
一本化・正本＋アダプタ・peer 同期・専用ツールという4パターンの選び方
導入チェックリストと FAQ

Hatena などでの話題度は発見のきっかけに留め、事実は公式ドキュメントと独立した検証ソースに依拠します。

Claude Code と Codex の設定差分サマリー

まず全体像を表にします。同じ「プロジェクト規約」「個人スキル」「接続先」でも、ファイル名も探索順も別です。

面ごとの差分表

クラスメソッドのCLIエージェント設定一本化記事の画面 — CLAUDE.md への一本化と Codex fallback を解説する独立記事の例

出典

観点	Claude Code	Codex	同期の現実
プロジェクト指示	`CLAUDE.md` / `.claude/CLAUDE.md`	`AGENTS.md`（階層 discovery）	名前もロード順も別。単純コピー放置はドリフト源
個人／グローバル指示	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`（override 優先）	グローバルも peer 管理が必要
Skills 探索	`~/.claude/skills/` など	`~/.agents/skills/` など	同内容なら symlink、文面最適化が要るなら peer
設定形式	`settings.json` / `.mcp.json` 等	`config.toml` / hooks 設定	形式変換か「正本＋薄いアダプタ」
path rules	`.claude/rules/`	`~/.codex/rules` は承認ポリシー（別物）	一律同期しない

出典と同期の実務ルール

出典（2026年7月時点）:

結論として、同期対象は「同じ役割の面」に絞り、意味が違う面（とくに Codex の承認 rules）は同期しない、が安全側です。

なぜ Claude Code と Codex の設定はすぐズレるのか

ズレる主因は、同じ役割を別パス・別形式で持つことです。プロジェクト規約、個人 Skills、hooks、MCP はどちらにもありますが、ファイル名・探索ディレクトリ・設定 DSL が揃っていません。

Claude Code 側で起きやすい読み込み前提

人が書く CLAUDE.md は、managed → user → project → local のスコープで読み込まれます。

役割は enforced configuration ではなく context
強い制約が必要なら PreToolUse hook を使う
目安はファイルあたり約200行
@path による import は最大4 hop

詳細は Anthropic Memory docs を参照してください。

Codex 側で起きやすい読み込み前提

ディレクトリごとに次の順で最大1ファイルを選び、リポジトリ root から cwd へ連結します。

AGENTS.override.md
AGENTS.md
project_doc_fallback_filenames に列挙した別名

合計サイズは project_doc_max_bytes（既定 32KiB）で打ち切られます（OpenAI AGENTS.md guide）。

よくある事故

片側の指示ファイルだけ更新し、もう片方が古いルールで動く
mtime（更新時刻）で「どちらが新しいか」を決め、git checkout 後に判定が壊れる
Codex の rules（コマンド承認ポリシー）を Claude の path-scoped rules と同一視して同期する

構造を理解せずに「全部コピー」すると、上記の3点が同時に起きやすくなります。

公式仕様で押さえる読込ルール（CLAUDE.md と AGENTS.md）

設計を選ぶ前に、両公式の discovery を固定します。

Claude Code（CLAUDE.md）

プロジェクト: ./CLAUDE.md または ./.claude/CLAUDE.md
個人用ローカル: CLAUDE.local.md（gitignore 想定）
上位ディレクトリのファイルは起動時にロード、サブディレクトリはオンデマンド
@path/to/import の相対パスは、import を書いたファイル基準。Markdown の code span / fence 内の @ は import されない
長い手順や局所ルールは skill や .claude/rules/ へ移し、CLAUDE.md は常時守らせたい規約に寄せる

/context などで Memory files の読み込み状況を確認できるため、同期後の検証にも使えます。

Codex（AGENTS.md）

グローバル: CODEX_HOME（既定 ~/.codex）で AGENTS.override.md があればそれ、なければ AGENTS.md
プロジェクト: 各ディレクトリで override → AGENTS.md → fallback 名の順に最大1ファイル
マージは root→cwd。近いディレクトリの内容が後段で効く
別名ファイルを使う場合は project_doc_fallback_filenames に列挙（例: CLAUDE.md, README.md）

クラスメソッドの解説が示すとおり、project_doc_fallback_filenames = ["CLAUDE.md","README.md"] で CLAUDE.md を候補にできます。

ただし同じ階層に AGENTS.md がある場合は AGENTS 側が優先されます。「fallback を設定したから CLAUDE.md だけ直せばよい」は誤解になりやすい点です。

Gemini CLI 併記として、.gemini/settings.json の context.fileName で CLAUDE.md を読ませる例もありますが、本記事の主対象は Claude Code と Codex です。

設計パターン比較｜一本化・正本＋アダプタ・peer同期・専用ツール

「何を正本にするか」と「どこまで自動で揃えるか」で、実務パターンは次の4つに分かれます。

4パターン比較表

実務でよく使う4案を、正本の置き方で2グループに分けます。

パターン A・B（一本化と薄いアダプタ）

パターン	正本の置き方	向く状況	主な制約	代表ソース
A. CLAUDE.md 一本化	Codex に fallback で CLAUDE.md	指示ファイルだけ寄せたい	同階層 AGENTS.md があると AGENTS 優先	classmethod
B. 正本＋薄いアダプタ	`AGENTS.md` 正本＋`CLAUDE.md` が `@AGENTS.md`。Skills は `~/.agents/skills` 正本＋symlink	共存前提で分岐を最小化	JSON/TOML 設定そのものは共有不可	Qiita kirozero

パターン C・D（peer監査と同期ツール）

パターン	正本の置き方	向く状況	主な制約	代表ソース
C. peer-file + audit	`claude/` と `codex/` を並べ symlink。manifest／pre-commit でドリフト拒否	両ホストの文面・hooks を揃え、チームで更新漏れを拒否したい	自動マージより可視化・拒否が中心	stafforini
D. 差分対応の同期ツール	agents-sync / ai-config-sync-manager 等	既に差分がある・項目選択・常駐が欲しい	導入コスト、モデル別 prompt 差	Explaza agents-sync、OpenAI Community

出典: 上表リンク（2026年3月〜7月の公開情報）

各パターンの要点

A. 指示だけ一本化

Skills／hooks／MCP の分岐は残る
「規約ファイルの二重管理を止めたい」場合の最小案

B. 共通正本＋薄いアダプタ

kirozero 案の要点は次のとおりです。

プロジェクトルールの正本は AGENTS.md
Claude 側は @AGENTS.md で取り込む
Skills は ~/.agents/skills を正本にし、Claude 側へ個別 symlink
hooks は設定ファイルを共有せず、共有スクリプトだけ両ホストから呼ぶ
Codex App の「Import other agent setup」が Skills をコピー複製する場合は、あとから symlink に寄せ直す

C. peer + audit

stafforini の公開ノートが示す設計は次のとおりです。

version-controlled な peer 実装（CLAUDE.md↔AGENTS.md、skills、hooks）を live の ~/.claude / ~/.codex へ symlink
manifest・pre-commit・audit で対向未更新の commit を拒否
settings.json のように頻繁に書き換わる面は symlink せず、hook スクリプトだけを track する非対称も明示
自動で対向を書き換えるより、「両側を更新したか」を強制する

D. 選択同期ツール

Explaza の Zenn 記事と GitHub DevsProtein/agents-sync（MIT）の特徴:

同一面は symlink
異形式（MCP の .mcp.json と config.toml など）は中立形へ正規化して比較・変換
fingerprint で新旧判定（mtime 不使用）
両側変更時は人手マージ
同期項目を選択できる
macOS では launchd 常駐も可能
プロジェクト内にツール自身を置いて自己同期対象にしない

OpenAI Developer Community 上の ai-config-sync-manager は、次を掲げます。

status／diff／apply／backup
skills／agents／MCP／hooks／permissions を対象にした双方向同期
in-sync／conflict／one-side-only を色分けする inventory board（2026-07-25 更新）

公式の one-shot migrate とは別に、「継続的なドリフト可視化」が論点です。

読者の選び方

指示ファイルだけ寄せたい → A
共存を前提に最小分岐 → B
チームでドリフト commit を拒否したい → C
既存分岐の回収＋項目選択同期 → D

ハイブリッド（指示は B、MCP だけ D）も現実的です。最初から全自動に寄せるより、同期する面としない面を文書化する方が事故が減ります。

導入チェックリスト｜同期する面を選び、差分を潰す

次の番号どおりに進めると、ツール選定の前に失敗点を減らせます。

現状棚卸し
プロジェクト／グローバルの CLAUDE.md、AGENTS.md、skills、hooks、MCP の有無と内容差を一覧化する。
正本方針を決める
A／B／C／D のいずれか、または面ごとのハイブリッド。
同期しない面を明示する
path-scoped Claude rules、モデル固有の prompting、Codex の承認 rules。
初回差分処理
片方向コピー前提にしない。diff → 人間マージ → apply（agents-sync や Community ツールの思想）。
恒久化
symlink、peer＋audit、または選択的 watcher。mtime 同期は使わない。
検証
両ホストで同じタスクを投げ、読まれた指示・skills を確認する（Claude は /context、Codex は instruction sources を確認）。
チーム運用
リポジトリに載せる正本と個人 local の境界、pre-commit／audit の有無を決める。

チェックリスト:

正本ファイルが1系統に決まっている
同期対象（instructions / skills / hooks / MCP）が列挙されている
非同期対象（承認ポリシー等）が文書化されている
両側変更時の人手マージ手順がある
導入後に両 CLI で読込確認した

注意点:

秘密情報を CLAUDE.md／AGENTS.md に直書きしない
同期ツール本体をプロジェクト内に置いて自己同期対象にしない
公式の fallback や byte 上限は更新され得るため、導入時に docs を再確認する

よくある失敗と避け方

失敗	なぜ起きるか	避け方
`~/.codex/rules` を Claude rules と同期	承認ポリシーと指示 rules の混同	同期対象から明示的に外す
fallback の CLAUDE.md だけ直し Codex が読まない	同階層 AGENTS.md が優先	優先順位を確認し、正本をどちらかに固定
全 Skills を機械同期	モデル別 prompting 差で品質低下	項目選択。共通手順だけ同一正本
mtime で正を決める	git checkout で時刻が変わる	fingerprint／内容比較／人手マージ
CLI 間操作だけ勧める	デスクトップアプリ利用者が取り残される	両 UI の設定面を棚卸しに含める

失敗の多くは「全部同じにすれば安心」という前提から来ます。役割が同じ面だけ揃え、意味が違う面は揃えない、が再現性の高い方針です。

関連記事:

よくある質問（FAQ）

Q1. Codex に CLAUDE.md だけ読めさせれば十分ですか？

A. 指示ファイルだけなら project_doc_fallback_filenames で寄せられます。ただし同階層の AGENTS.md が優先されます。Skills／hooks／MCP は別経路のままなので、「十分」とは限りません。

Q2. CLAUDE.md から `@AGENTS.md` するのと、peer の2ファイル運用の違いは？

A. @import は Claude 側の正本寄せです。peer は両ホスト用に文面差（import 記法など）を許容しつつ、audit で意味を揃えます。チームが書き分けを必要とするなら peer＋監査、最小分岐なら import 寄せが向きます。

Q3. agents-sync と ai-config-sync-manager の選び方は？

A. 前者は symlink＋形式変換＋項目選択＋（macOS）常駐が中心です。後者は Community 上の双方向 sync／diff／apply と drift board が中心です。OS、必要な面（permissions を含むか）、既存スタックで比較してください。共通価値は「差分がある状態を前提にする」点です。

Q4. Skills は必ず両ホストで同一文面にすべきですか？

A. 共通手順は同一正本＋symlink が事故が少ないです。モデル固有の prompting 差がある面は同期対象から外し、peer で最適化する選択肢があります。

Q5. 公式の byte／行数目安を超えるとどうなりますか？

A. Codex は project_doc_max_bytes で連結が打ち切られます（既定 32KiB）。Claude は長い CLAUDE.md が context を圧迫し遵守が下がりやすいため、約200行目安と rules／skills への分割が推奨されます。

まとめ｜次にやること

Claude Code と Codex の設定ズレは、公式が別 discovery を定義している以上、放置すると再現します。

パターン A〜D から正本方針を選ぶ
同期する面としない面をチェックリストで固定する
既に分岐しているなら、初回は diff／merge 前提のツールまたは人手で収束させる
以後は symlink・audit・選択 watcher で漏れを構造的に減らす

次のアクション:

両ホストの設定を棚卸しする
パターン（またはハイブリッド）を決める
1プロジェクトで検証する
問題なければチームルールへ昇格する

完璧な全自動より、更新漏れが起きにくい境界設計を優先するのが、運用コスト対効果のバランスが良い判断です。

複数エージェントを1画面で並列運用するワークスペース設計は、wmux の解説も参考になります。

著者

krona23

IT業界20年以上の実務経験を持ち、日本国内有数のPVを誇る大規模Webサービスで事業部長・CTOを複数社で歴任。Windows/iOS/Android/Webと技術の変遷を経験し、現在はAIネイティブへの変革に注力。DevGENTでは、AIコードエディタ・自動化ツール・LLMの実践的な使い方を日英西3言語で発信中。

DevGENT について →

📚 次に読む