2026-10-08

Claude CodeとCodexでCLAUDE.mdとskillsを二重管理しない設定方法

概要

今回はClaude CodeとCodexで同じプロジェクトのルールとスキルを二重管理せずに共有する方法について紹介していきます。

Claude CodeとCodexはどちらもコーディングを手伝ってくれるAIですが、何も決めずに両方使うと、同じルールをCLAUDE.mdとAGENTS.mdの2つに書くことになりがちです。
例えば「コードを変えたらテストする」というルールを両方に書くと、片方だけ直し忘れる、ということが普通に起きます（- -;

そこで、ルールはCLAUDE.md、スキルは.claude/skills/だけを本体にして、Codexからはそこを読みに行く設定にしました。
コピーを作らないので、直す場所は常に1か所で済みます。
やることは、Codexの設定ファイルへの1行追加と、シンボリックリンク1本の作成の2つだけです。

それではやっていきましょう！

目次

• CLAUDE.md・AGENTS.md・skillsの二重管理が起きる理由
• CLAUDE.mdを共通ルールの本体にする（Codexのfallback設定）
• skillsはシンボリックリンクで共有する
• リポジトリ内にリンクを作れない場合
• 新しいルールやスキルを追加するとき
• よくある失敗
• 設定できたか確認する方法
• まとめ

CLAUDE.md・AGENTS.md・skillsの二重管理が起きる理由

まずは登場するファイルの役割を確認します。

名前	役割	標準で読むツール
CLAUDE.md	毎回守ってほしいプロジェクトのルールを書くメモ	Claude Code
AGENTS.md	同じ役目のメモ	Codex
skill（スキル）	画像作成やリリース作業のような、長めで再利用したい手順書	両方（置き場所が違う）
シンボリックリンク	「本物はあちらにあります」と案内するショートカット	OS・Git

ルールのファイル名もスキルの置き場所もツールごとに違うため、素直に対応すると同じ内容を2か所に置くことになります。
最初は動きますが、後から「どっちを直せばいいんだっけ」となるのが目に見えています。

今回の構成は次の通りです。

Claude CodeとCodexでルールとスキルの本体を1か所にまとめる構成図

プロジェクト構成

project/
├─ CLAUDE.md                ← 共通ルールの本体
├─ .claude/
│  └─ skills/               ← スキルの本体
│     └─ release/
│        └─ SKILL.md
└─ .agents/
   └─ skills -> ../.claude/skills   ← リンクだけ

CLAUDE.mdを共通ルールの本体にする（Codexのfallback設定）

リポジトリのルールは、ルートのCLAUDE.mdに書きます。
Claude Codeはもともとこのファイルを読むので、Claude Code側の設定は不要です。

Codex側は、ユーザー設定ファイル~/.codex/config.tomlに次の1行を追加します。

~/.codex/config.toml

project_doc_fallback_filenames = ["CLAUDE.md"]

これは「AGENTS.mdが見つからなければ、代わりにCLAUDE.mdを読んでください」という設定です。
Codexの公式ドキュメントでは、Gitのルートから作業ディレクトリまでの各階層でAGENTS.override.md→AGENTS.md→fallbackに指定した名前の順にファイルを探す、と説明されています。
なので、同じ文章をAGENTS.mdにコピーする必要はありません。

Codex公式: AGENTS.mdの探索順とproject_doc_fallback_filenames
https://developers.openai.com/codex/guides/agents-mddevelopers.openai.com

ただし、探索順の都合で同じ階層にAGENTS.mdが残っているとそちらが優先され、CLAUDE.mdは読まれません。
以前Codex用に作ったAGENTS.mdがある場合は、中身をCLAUDE.mdに寄せてから削除しておくのがお勧めです。

Codexは指示ファイルを起動時（1回の実行ごと）に読み込み、config.tomlの変更も再起動後に反映されます。 設定を入れたあとは、すでに開いているCodexのセッションを一度終了して、新しいセッションで確認してください。

ちなみに逆方向の選択肢もあります。
Claude Codeの公式ドキュメントによると、v2.1.277以降のClaude CodeはCLAUDE.mdが無いリポジトリならAGENTS.mdを読むようになっていて、CLAUDE.mdの中に@AGENTS.mdと書いて取り込む方法も案内されています。
自分の場合はすでにCLAUDE.mdで運用していたので、Codex側に1行足すだけで済むfallback設定の方が楽でした。

Claude Code公式: CLAUDE.mdとAGENTS.mdの読み込み
https://code.claude.com/docs/en/memorycode.claude.com

skillsはシンボリックリンクで共有する

スキルもコピーはしません。
Claude Codeは.claude/skills/を、Codexはリポジトリ内の.agents/skills/を探すので、後者を前者へのリンクにします。

.agents/skills  ->  ../.claude/skills

Linux/macOSなら、リポジトリのルートで次のコマンドを一度だけ実行します。

コマンド

mkdir -p .agents
ln -s ../.claude/skills .agents/skills
git add .agents/skills .claude/skills

Windowsでリンクを作る場合の注意は、後の「よくある失敗」でまとめています。

Codexの公式ドキュメントには、シンボリックリンクのスキルフォルダに対応していてリンク先をたどって読み込む、と明記されています。
Claude Code側もスキルフォルダのリンクに対応しているので、リンクの向きはどちらでも動きますが、編集する側（本体）を.claude/skills/に決めておくと迷いません。

Codex公式: skillsの配置場所とシンボリックリンク
https://developers.openai.com/codex/skillsdevelopers.openai.com

Gitはリンクそのものを記録できるので、ほかの人がcloneしてもLinux/macOSなら基本的には同じ構成になります。
スキルを更新するときは.claude/skills/<スキル名>/SKILL.mdだけを編集すれば、Claude CodeとCodexの両方に同じ変更が届きます。

なお、SKILL.mdの先頭には両ツールともnameとdescriptionのfrontmatterを書きます。
descriptionはAIが「このスキルを使うべきか」を判断する材料になるので、使う場面と使わない場面を短く具体的に書いておくと呼ばれやすくなります（^^

SKILL.md

---
name: release
description: リリース作業の手順。タグ付けと本番デプロイを頼まれたときに使う
---

リポジトリ内にリンクを作れない場合

サンドボックスの設定などで.agentsフォルダに書き込めず、リポジトリ内にリンクを作れない環境もあります。
その場合は、そのマシンのユーザー用スキルフォルダにリンクを置く方法があります。

Codexの公式ドキュメントでは、ユーザー単位のスキルは$HOME/.agents/skillsから読み込むと説明されています。

コマンド

mkdir -p ~/.agents/skills
ln -s /path/to/project/.claude/skills/release ~/.agents/skills/release

これもコピーではないので、本体のSKILL.mdを直せば両方に反映されます。
ただしこのリンクはそのマシン専用で、ほかのプロジェクトからも見えるユーザー単位のスキルになります。
別のPCで作業するときは、通常どおりリポジトリ内に.agents/skillsのリンクを作るのがお勧めです。

新しいルールやスキルを追加するとき

毎回守ってほしい短いルールは、CLAUDE.mdに追記します。

CLAUDE.md

- 新しい画面を追加したら、スマホサイズでも確認する。

ルールは短く具体的に書くと、AIが守りやすくなります。

手順が長い作業は、.claude/skills/<スキル名>/SKILL.mdを新しく作ります。

.claude/skills/release/SKILL.md

.agents/skillsのリンクがあれば、追加したスキルはCodexからもそのまま見えます。
リポジトリ内にリンクを作れない環境では、前の章のようにユーザー用スキルフォルダへリンクを追加します。

よくある失敗

実際にやりがちな失敗をまとめておきます。

• AGENTS.mdとCLAUDE.mdの両方に同じ内容を書く
  • 片方の更新忘れが起きるので、共通ルールの本体はCLAUDE.mdに決める
• スキルのフォルダをコピーする
  • 最初は動くが、後でどちらを直すべきか分からなくなるので、リンクを使う
• 開いたままのCodexに設定変更を期待する
  • Codexは起動時に指示ファイルを読むので、設定を変えたら新しいセッションを始める
• Windowsでリンクが作れない・cloneするとただのファイルになる
  • 環境によっては管理者権限や開発者モード、Git側のシンボリックリンク設定が必要になる（WSL内で作業すると扱いやすい）

設定できたか確認する方法

最後に、新しいCodexのセッションで次のように聞いてみます。

このプロジェクトで読み込んだ指示書とスキルを教えて

CLAUDE.mdの内容を説明でき、目的のスキルを見つけられれば設定成功です。
Codexで$releaseのように$スキル名で明示的に呼び出せるかも合わせて見ておくと確実です。

Claude CodeとCodexの併用を始めたときの、commands・skillsの対応付けについては以下の記事でも紹介しています。

Claude CodeとCodexを両方使う｜commands・skillsを引き継ぐ設定手順
https://shinpinoshi.com/engineering/claude-code-to-codex-migration/

まとめ

ルールはCLAUDE.md、スキルは.claude/skills/だけを本体にし、Codexからはfallback設定とシンボリックリンクで同じ実体を読ませるのが今回の方法です。
設定はconfig.tomlの1行とリンク1本だけなので、導入の手間もほとんどかかりません。

AIツールを複数使っていると設定ファイルがどんどん増えていくので、「本体はどこか」を最初に決めておくのが一番大事だと感じました。
ツールごとの仕様もまだまだ頻繁に変わっているので、しばらくは公式ドキュメントを追いかけることになりそうですね。

以上となります。
共通の企画とかで、同じmdにまとめてくれれば楽なんですけどね…
それではお疲れさまでした。

この記事をシェア X

« 前の記事 IEはなぜPDFを自動表示できるのか｜ActiveXとレジストリの仕組みを調査した 次の記事 » Codexを確認なし・フルアクセスで使う設定｜sandbox_modeとapproval_policyの書き方

エンジニアリング

Claude Code, AI, エンジニアリング