結論：CLAUDE.mdは1行にして、中身はAGENTS.mdに寄せる
Claude Code と Codex を両方使っていると、指示ファイルが2つになります。Claude Code は CLAUDE.md、Codex は AGENTS.md を読むからです。
同じ内容を2か所に書くことになり、私はこれが面倒で仕方ありませんでした。
私の解決方法は「CLAUDE.md」の中身を1行にするでした。
@AGENTS.mdこれだけです。本文は全部 AGENTS.md に移します。
CLAUDE.md の中で @ファイル名 と書くと、Claude Code はそのファイルの中身を読み込みます。つまり「CLAUDE.md」は「あっちを見て」とだけ言っている状態になります。
以降、更新するのは AGENTS.md だけ。CLAUDE.md はもう触りません。実際、私の作業フォルダの CLAUDE.md は11バイトしかありません。
なぜ指示ファイルが2つになるのか
AIのコーディングエージェントには、そのフォルダでの決まりごとを書いておくファイルがあります。
「このブログはWordPressで、ブロックエディターのコードエディターに貼り付ける運用」「原稿は必ず .md と .html の2本で出す」「文体はブログがです・ます、noteが常体」。こういうことを毎回ゼロから説明しなくて済むようにしておくものです。
問題は、読むファイル名がツールによって違うことです。
| ツール | 読むファイル |
|---|---|
| Claude Code | CLAUDE.md |
| Codex | AGENTS.md |
AGENTS.md のほうは複数のツールが採用している共通の名前で、CLAUDE.md は Claude Code 固有のものです。
片方だけを使っているなら悩む必要はありません。両方使い始めた瞬間に、同じ文章が2つのファイルに並びます。
2か所にあると、必ずズレる
これが本当の問題です。
私の場合、最初は素直に両方に同じ内容を書いていました。そして予想どおり、片方だけ直して、もう片方を直し忘れるということが起きました。
厄介なのは、ズレても何も起こらないことです。
エラーは出ません。警告も出ません。ただ、Claude Code に頼んだときと Codex に頼んだときで答えが微妙に変わるだけです。
「さっきはこうしてくれたのに」と思って調べると、片方のファイルだけ古いままだった。原因にたどり着くまでに時間を使いました。
ポイント
同じ内容を2か所に持つと、いつか必ずズレます。気をつけて運用する、では解決しません。気をつけなくても1か所しかない状態にするのが、唯一の解決です。
やり方は3ステップ
1. AGENTS.md に中身を全部移す
まず AGENTS.md を作って、CLAUDE.md に書いてあったことを丸ごと移します。これが本体になります。
すでに AGENTS.md があって中身が食い違っているなら、先に一本化してください。この作業をしないまま次に進むと、古いほうが残ります。
2. CLAUDE.md を1行にする
CLAUDE.md の中身を全部消して、この1行だけにします。
@AGENTS.mdパスは相対指定です。CLAUDE.md と AGENTS.md が同じ階層にあるなら、これで通ります。別のフォルダにあるなら @../AGENTS.md のように書きます。
3. フォルダごとに同じ形にする
指示ファイルは、サブフォルダごとに置けます。私の作業フォルダはこうなっています。
作業フォルダ/
├ CLAUDE.md ← @AGENTS.md の1行だけ
├ AGENTS.md ← 全体の決まりごと
├ テーマ１/
│ ├ CLAUDE.md ← @AGENTS.md の1行だけ
│ └ AGENTS.md ← ブログ作業の決まりごと
└ テーマ２/
├ CLAUDE.md ← @AGENTS.md の1行だけ
└ AGENTS.md ← このテーマの決まりごとどの階層でも形が同じなので、新しいテーマを始めるときに迷いません。AGENTS.md を書いて、隣に1行の CLAUDE.md を置く。それだけです。
Claude Codeだけに伝えたいことがあるとき
「これは Claude Code にだけ言っておきたい」という場合もあります。そのときは、CLAUDE.md の @AGENTS.md の下に書き足します。
@AGENTS.md
（ここから下は Claude Code 向けの追記）@AGENTS.md で共通部分を読み込んだうえで、続きが追加される形です。共通が上、固有が下。この順番を崩さないほうが分かりやすいと思います。
ただ、私は今のところ追記を使っていません。分ける必要が出てから分ければ十分で、最初から枠だけ作ると、結局そこが二重管理の種になります。
つまずきやすいところ
ファイル名の大文字・小文字。CLAUDE.md も AGENTS.md も全部大文字です。Agents.md では読まれないことがあります。
「@」の書き忘れ。AGENTS.md とだけ書いても、ただの文字列として扱われます。先頭の @ が読み込みの合図です。
移し忘れ。CLAUDE.md を1行にする前に、中身が全部 AGENTS.md に入っているか確認してください。消してから気づくと面倒です。私は一度コピーを取ってから消しました。
動いているかの確認方法。新しいセッションを開いて、AGENTS.md にしか書いていない決まりごとについて質問してみてください。ちゃんと答えが返ってくれば読み込めています。
なお、この方法は私の環境で動いていますが、ツールのバージョンが上がると挙動が変わる可能性があります。うまくいかないときは、まず CLAUDE.md に直接書く形に戻せば元どおりです。
教えてくれたのは、Claude Code本人でした
この方法、実は Claude Code に相談して教わりました。
「CLAUDE.mdとAGENTS.mdの両方を毎回更新するのが面倒だ」と愚痴をこぼしたら、@ で読み込む形を提案してきて、そのまま作業までしてくれました。
自分が読むファイルの整理のしかたを、自分で提案してくる。少し不思議な気分でしたが、困っていることをそのまま言ってみるものだなと思いました。
二重管理をやめる話は、AIに限りません
書いていて気づいたのですが、これはAIの話ではないですね。
同じ情報を2か所に持つと、いつかズレる。
農家の実感
りんご園の作業記録を、ノートとスマホの両方につけていた時期があります。結局どちらも中途半端になって、どちらが正しいのか分からない記録ができあがりました。
帳簿も同じです。手書きの出納帳と会計ソフトを並行させていたころは、数字が合わないたびに「どっちが間違っているのか」から始めていました。
どちらかを正にして、もう片方は見るだけにする。これをやってから、迷う時間がなくなりました。
今回の CLAUDE.md を1行にする話も、形はまったく同じです。本体を1つ決めて、残りは参照にする。それだけのことでした。
📋 まとめ
- Claude Code と Codex を併用すると、
CLAUDE.mdとAGENTS.mdの二重管理が発生する - 本体は AGENTS.md。中身を全部こちらに移す
CLAUDE.mdは @AGENTS.md の1行だけにする- パスは相対指定。同じ階層なら
@AGENTS.md - サブフォルダごとに同じ形にすると、新しいテーマでも迷わない
- Claude Code だけに伝えたいことは、
@AGENTS.mdの下に書き足す - 1行にする前に、中身が移っているか必ず確認する
- 確認は、新しいセッションで AGENTS.md にしかない内容を聞いてみる
同じことを2か所に書かない。気をつけて運用するのではなく、1か所しかない形にする。これはAIに限らず、記録でも帳簿でも同じでした。
※ 本記事は2026年10月時点の私の環境での内容です。ツールの仕様は変わることがありますので、うまくいかない場合は CLAUDE.md に直接書く形に戻してください。