Claude CodeとCodexの設定を1本化する方法

「CLAUDE.md を直したのに、Codex 側は古いルールのまま動いていた」——2つのAIコーディングエージェントを併用していると、誰もが一度はこの二重管理にハマります。

結論から言うと、指示ファイルとスキルの「正本（しょうほん＝おおもとの1ファイル）」を1つに集約し、もう片方からは参照でつなぐと、この二重管理は消えます。編集するのは1箇所、反映されるのは両方です。

株式会社Fyveは、Claude Code と OpenAI Codex を毎日同時に動かしながら、AI業務効率化の受託と顧問サービスを運営しています。本記事では、私が実際に使っている「設定の1本化」を手順そのままで公開し、さらにそこまでやるべき人・やらなくていい人の線引きまで示します。

なぜ2ツール併用で設定が二重管理になるのか

Claude Code と Codex は、それぞれ別の名前の指示ファイルを読みます。Claude Code はプロジェクト直下の CLAUDE.md、Codex は AGENTS.md です。同じ「AIへの指示書」なのに、ファイル名が違うだけで置き場所が2つに分かれます。

スキル（繰り返す作業を定型化した部品）も同じ構図です。Claude Code は .claude/skills/ に、Codex は Codex 側のスキル置き場に持ち、これも二重になります。

問題は数が増えてからです。同じルールを2箇所に書いていると、次のことが必ず起きます。

• 片方だけ直して片方を忘れる：ルールを1つ足したのに、更新したのは CLAUDE.md だけ。Codex は古い前提のまま動きます。
• どちらが最新か分からなくなる：2つのファイルが少しずつズレていき、正しいのがどちらか追えなくなります。
• 挙動が食い違う：同じ指示を出したのに、ツールによって結果が変わる。原因を探すと「設定が古かっただけ」というムダな時間が生まれます。

私自身、ルールを1本足したつもりで、実際には片方のツールにしか効いていなかった、という取りこぼしを何度か経験しました。ファイルが2つある限り、この事故は「うっかり」では防げません。仕組みで正本を1つに寄せるのが唯一の解決策です。

解決の原則——「正本は1つ、もう片方は参照」

考え方はシンプルです。指示もスキルも実体（おおもと）は1つだけ置き、もう片方からはそこを「参照」させます。コピーを2つ持たないので、そもそもズレようがなくなります。

使う部品は3つだけです。この3つが別々の話ではなく、「実体は1つ」という同じ前提の上に乗っているのがポイントです。

• ①指示ファイルの集約：中身は AGENTS.md に一本化する（正本を決める）
• ②@参照（アットさんしょう）：CLAUDE.md からは正本を読み込むだけにする
• ③symlink（シンボリックリンク＝同じファイルを2箇所から見せる近道）：スキルの実体を1つにして共有する

以下、この3部品を手順に落とします。どれもコマンド1〜2行、コピペで再現できます。

読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →↓

手順1｜指示ファイルの正本を AGENTS.md に集める

まず、指示の中身（環境のセットアップ手順・守ってほしいルール・プロジェクトの前提）を AGENTS.md に集約します。CLAUDE.md 側に散らばっている内容も、共通で効かせたいものはすべてこちらへ寄せます。

正本を AGENTS.md にする理由は、これが特定の製品に縛られないオープンな共通フォーマットだからです。AGENTS.md は Codex だけでなく、GitHub Copilot や Cursor など多くのツールが読み込む形式になっており、将来3つ目のツールが増えても正本を作り直さずに済みます。

# AGENTS.md（正本＝おおもと）
## セットアップ
- 依存パッケージは npm install で入れる
## 守ってほしいルール
- 破壊的な操作の前に必ず確認する
- 出力は日本語で返す

AGENTS.md をどこに置き、何を書き、どこまで書くと逆効果になるかは、別記事で詳しくまとめています。正本の中身そのものを整えたい方はこちらを参照してください。

AGENTS.mdの書き方｜Codex設定ファイル実践ガイド

手順2｜CLAUDE.md からは @AGENTS.md で参照させる

次に、Claude Code 側です。Claude Code の CLAUDE.md には @参照（@import）という書き方があり、@ファイルパス と書くと、そのファイルの中身を読み込み時にそのまま展開してくれます。

そこで CLAUDE.md には、正本を読み込む1行と、Claude Code だけの上書き設定だけを残します。共通ルールはもう CLAUDE.md には書きません。

# CLAUDE.md
# 共通ルールは正本を参照する
@AGENTS.md

# ここから下は Claude Code だけの上書き
- （Claude Code 固有の設定があればここに書く）

これで Codex は AGENTS.md を直接読み、Claude Code は CLAUDE.md 経由で同じ AGENTS.md を読むことになります。共通ルールを直すときは AGENTS.md の1箇所を編集するだけで、両方に反映されます。

@参照を使うときの注意点も押さえておきます。

• コンテキストは減らない：@参照は中身をそのまま展開するので、読み込む情報量（コンテキスト）自体は変わりません。整理のための仕組みであって、軽量化の仕組みではありません。
• コードブロック内では効かない：``` で囲んだ中の @ は参照として評価されません。誤爆を防ぐ仕様です。
• 参照は最大5階層まで：参照した先がさらに別ファイルを参照する、という入れ子は5段までです。

なお、Claude Code 側に固有の上書きがまったく無い場合は、参照すら省いて ln -s AGENTS.md CLAUDE.md と symlink を張り、CLAUDE.md の実体を AGENTS.md にしてしまう方法もあります。ファイルが物理的に1つになるので、より確実です。ただし Windows では symlink の作成に管理者権限が必要になる点だけ注意してください。

手順3｜スキルは symlink で実体を1つにする

指示ファイルの次はスキルです。スキルも実体を1箇所に置き、各ツールのスキルフォルダからは symlink（近道）で参照させます。こうすると、スキルを1つ直したときに両方のツールへ同時に反映されます。

やり方は、共有したいスキルの実体を1箇所（たとえば共通のフォルダ）に置き、各ツールのスキル置き場からリンクを張るだけです。

# 実体は共通フォルダに1つだけ置く
# 各ツールのスキル置き場から近道（symlink）を張る
ln -s ../shared-skills/my-skill .claude/skills/my-skill

この「実体は1箇所・参照はsymlink・コピーは作らない」という設計は、スキルに限らずロゴ画像や共通設定など、複数の場所から同じファイルを使いたいとき全般に効きます。symlink と同期の基本設計はこちらにまとめています。

複数プロジェクトのファイル共有｜symlinkと同期設計

落とし穴——「symlinkでつないだ」で油断すると静かに分裂する

ここで一番大事な注意点をお伝えします。参照や symlink でつなぐのは入口にすぎない、ということです。つないだ後の運用で気を抜くと、設定はまた静かに分裂します。

典型的なのは、片方のツールで作業しているときに「このツールだけ効かせたいルール」をつい正本ではなく手元のファイルに書き足してしまうケースです。これを繰り返すと、正本に無いルールが片側だけに溜まり、実質また二重管理に戻ります。

防ぐルールは1つだけです。共通で効かせたいものは必ず正本（AGENTS.md）に書く。各ツールのファイルには「そのツール固有の差分」だけを書く。この線引きを崩さないことが、1本化を維持する条件です。

加えて、ときどき実際に何が読み込まれているかを確認する習慣をつけると安全です。Claude Code なら /memory で、いま読み込まれている指示ファイルを一覧できます。「参照したつもりが効いていない」を早めに見つけられます。

そもそも1本化すべき人・しなくていい人

最後に判定です。設定の1本化は、全員がやるべき作業ではありません。手間に見合うのは、次のような使い方をしている人です。

• やる価値が高い：2つのツールを日常的に併用している／同じルールセットを両方に効かせたい／同じスキルを両方で使い回している
• やらなくていい：どちらか一方がメインで、もう片方はごくたまにしか使わない／プロジェクトのルールがごく軽い／単発の作業でしか使わない

参考までに、私の運用は「Claude Code をメインに据え、Codex には画像生成や長時間の自律作業といった特定タスクだけを渡す」という役割分担です。どちらのツールをどの作業に使い分けるかは、こちらで詳しくまとめています。

Claude Code と Codex を併用する実務者の運用

メインとサブがはっきり分かれていても、私は設定の1本化はやる価値があると考えています。役割は分けても、守ってほしいルールとよく使うスキルは両方のツールで同じように効いてほしいからです。役割分担（どの作業を任せるか）と設定の1本化（同じ前提をどう共有するか）は別のレイヤーの話で、両立します。

まとめ——編集は1箇所、反映は両方

2つのAIコーディングエージェントを併用すると、指示ファイルとスキルは放っておくと必ず二重管理になり、静かにズレていきます。これを防ぐ設計は、突き詰めると次の3つだけです。

• 指示の中身は AGENTS.md を正本に集約する
• CLAUDE.md からは @AGENTS.md で参照する（固有の上書きが無ければ symlink でも可）
• スキルは symlink で実体を1つにして共有する

正本を1つに寄せておけば、編集するのは1箇所、反映されるのは両方です。ツールが増えても正本を作り直さずに済みます。「片方だけ古い設定で動いていた」という取りこぼしを、意志ではなく仕組みで止められるようになります。