Claude CodeとCodexを併用するなら CLAUDE.mdは1行でいい

同じリポジトリをClaude CodeとCodexの両方で触ると、AI向けの指示書が2つになります。CLAUDE.md と AGENTS.md です。

どちらにも同じことが書きたい。でも中身が同じなら二度書くのは無駄で、片方を直し忘れれば古い指示が残る。

自分の環境を数えてみました。8プロジェクトあって、3つのパターンに分かれていました。 意図して分けたわけではありません。気づいたらそうなっていた、という状態です。

この記事は、Claude CodeとCodexを併用している方向けです。結論から書くと、CLAUDE.mdは1行で足ります。

CLAUDE.mdは1行でいい 中身はAGENTS.mdに寄せる

まず答えです。CLAUDE.md の中身を、これだけにします。

@AGENTS.md

11バイト。1行です。@ はClaude Codeがファイルを読み込む記法なので、これで AGENTS.mdの本文がそのままCLAUDE.mdの中身として展開されます。 実体はAGENTS.md1本、CLAUDE.mdは入口だけ、という形になります。

そして面白いのは、これが自分で考えた工夫ではなかったことです。

このサイトのリポジトリでgit履歴を見たら、CLAUDE.mdは初回コミットから1度も変更されていませんでした。 初回コミットは create-next-app が作ったもので、その時点の中身がすでに @AGENTS.md の1行でした。

Next.jsの同梱ドキュメントに、そのまま書かれています。手元の node_modules/next/dist/docs/01-app/02-guides/ai-agents.md でも読めます。

create-next-app generates AGENTS.md and CLAUDE.md automatically.

CLAUDE.md側の理由も明記されています。

CLAUDE.md uses the @ import syntax to include AGENTS.md, so Claude Code users get the same instructions without duplicating content

「内容を重複させずに済むから」。最初からそういう設計でした。

Anthropic側の公式ドキュメントにも、同じ形が例示されています。

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.

つまり、Anthropicが公式にこの形を案内し、Next.jsも create-next-app の標準構成として採用しているわけです。それなのに私は、別のプロジェクトで違うことをやっていました。

二重管理は、名前を書き換えたいだけで始まる

8プロジェクトの内訳がこうでした。

パターン	件数	CLAUDE.mdの大きさ
@AGENTS.md の1行	2	11バイト
全文コピー	1	約24KB
それぞれ別内容	5	5〜9KB

問題は真ん中です。あるプロジェクトでは、CLAUDE.mdとAGENTS.mdがどちらも551行ありました。同じサイズ、同じ構成。差分を取ってみると、違っていたのは3行だけでした。

その3行がこれです。

行	CLAUDE.md	AGENTS.md
154	ChatGPT / Gemini / Claude の使い分け	ChatGPT / Gemini / Codex の使い分け
446	Claude Code が全ファイルに反映できる	Codex が全ファイルに反映できる
543	Claude Code に依頼する際の推奨順序	Codex に依頼する際の推奨順序

呼び名を書き換えただけです。内容が違ったわけではありません。

しかも、この3行は書き分ける必要すらなかった。「ChatGPT / Gemini / Claude の使い分け」という記述は、読んでいるのがCodexでも意味が変わりません。読み手を名指ししている445行目以降も、「担当するエージェント」と書けば1つで足ります。

結果どうなったか。呼び名を3箇所そろえるために、548行分の同期リスクを背負った状態です。いまどちらかを直したら、もう片方は古い指示を持ったまま動きます。ファイルの更新時刻は16分差でした。同じ日に、それぞれのAI向けにコピーを2本置いた履歴です。

ここが今回いちばん共有したかったことです。二重管理は「内容が違うから」始まるのではなく、「呼び名を変えたいから」始まります。 分けたい理由を言葉にしてみて、それが呼び名の話だったなら、分ける必要はありません。

@は指示ではなく取り込み 効きは同じでも載り方が違う

@AGENTS.md と書く代わりに、「AGENTS.mdに準拠すること」と書いてもいいのでは、と考えるかもしれません。私も一度そう思いました。

結論としては、@ のほうが確実です。 ただし理由は「強制力が強いから」ではありません。

AIへの指示は、効き方で3つの層に分かれます。

層	例	効き方
1. フック・権限設定	.claude/settings.json	強制される。 AIの判断に関係なく実行・ブロックされる
2. CLAUDE.md / AGENTS.md	@AGENTS.md、直接書いた文章	必ず読まれる。 ただし従うかは確率の問題
3. 「〜を読んで」という指示	「AGENTS.mdに準拠すること」	読みに行くかどうかも確率の問題

@ は2、「準拠すること」は3。1段違います。

@ の場合、公式ドキュメントによれば、インポートされたファイルは起動時に展開されてコンテキストに載ります。AIがファイルを読みに行く動作は要りません。 対して「準拠すること」は、AIが「読みに行こう」と判断して初めて中身が載ります。判断してくれれば同じ状態になりますが、しなければルールを知らないまま作業が始まります。

一方で、2の中では差がありません。 CLAUDE.mdに直接書くのと @ で取り込むのは、載ったあとの扱いが同じです。公式にも、インポートされたファイルは参照元のCLAUDE.mdと並べて展開される、とあります。

だから統合を選ぶ理由は、効きが良くなるからではなく、ズレなくなるからです。ここを取り違えると、二重管理をやめる動機を見失います。

なお、守らせたいことがあるなら1の層を使う必要があります。公式もこう書いています。

If the instruction is something that must run at a specific point, such as before every commit or after each file edit, write it as a hook instead.

instead です。CLAUDE.mdに「必ずlintしろ」と書いてもフックにはなりません。ただしフックで強制できるのは動作だけで、「一次情報で裏取りする」のような判断は書けません。判断が要るものは、結局2の層で渡すしかない。この線引きは覚えておく価値があります。

役割を変えたいなら、ファイルではなく渡し方を変える

ここでよく出てくるのが、こういう発想です。

「Codexはレビュー専用にするから、AGENTS.mdは別内容にしたい」

自然な考えですが、これは分ける理由になりません。理由を分解すると見えてきます。

レビューをさせるときにCodexが知っておくべきことは、「このプロジェクトで何がバグとみなされるか」「どの規約に照らすか」です。そしてそれは、Claudeが実装するときに必要な知識とまったく同じものです。違うのは「今回はレビューだけしてね」という一言だけ。

つまり、こう切ると整理できます。

種類	例	置き場所
プロジェクトの事実	何のリポジトリか、命名規則、禁止事項、画像の保存先とサイズ	AGENTS.md
その回の役割	今回はレビューだけ、今回は実装、今回は画像1枚	呼び出し時の指示やスキル

前者はファイルに、後者は渡し方に。同じ作業か違う作業かではなく、事実か役割かで切ります。

実際の渡し方は、こんな形です。

codex exec "このコードをレビューして"

codex exec はCodex CLIを非対話で1回動かすコマンドで、Claude Codeからも呼べます(前回の記事で環境の整え方を書きました)。役割はここに書けば済みます。

レビュー基準が長くなったら、Skillsに切り出せます。Skillsは SKILL.md に手順を書いておく仕組みで、必要なときだけ読み込まれます。 作り方はClaude Skillsで業務を覚えさせるに書きました。

ここでひとつ、つまずきやすい点があります。書式は共通化されていますが、自動で探しに行くフォルダが違います。

Skills自体はオープン標準で、標準的な SKILL.md はClaude CodeとCodexの両方で再利用できます(OpenAIも公式に、Codex Skillsはこのオープン標準の上に作られていると書いています)。ところが探索先が別です。

ツール	プロジェクト内で自動探索するフォルダ
Claude Code	.claude/skills/<名前>/SKILL.md
Codex	.agents/skills/<名前>/SKILL.md

つまり .claude/skills/ に置いただけでは、Codexのスキルとして認識されません。 これも二重管理が生まれるポイントです。

幸い、両方ともシンボリックリンクされたスキルフォルダに対応しています。Codexの公式ドキュメントには、シンボリックリンクをたどって参照先を読む、と明記されています。だから実体を片方に置いて、もう片方から参照させれば1本で済みます。

# 実体を .agents/skills/ 側に置き、Claude Code からは参照させる
ln -s ../../.agents/skills/ai-blog .claude/skills/ai-blog

このサイトのリポジトリでもSkillsを使っています。記事制作のワークフローと、執筆ルールを別ファイルに切ったもの。毎回のブログ制作でだけ読まれます。 ファイルの置き場所については、上のとおり両方から参照できる形にしておくのが無駄がありません。

Claude固有のことを書きたい場合も、分ける必要はありません。公式が例示しているとおり、@ の下に足せます。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

長くなったらSkillsへ 分割しても軽くはならない

もう1つ、知っておくと得な仕様があります。

Claude Codeでは、@AGENTS.md で取り込んだ内容も毎セッションのコンテキストに載ります。 だから長くなると効きが落ちます。Anthropicは目安まで書いています。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

CLAUDE.mdは200行以下。ここで多くの人がやりたくなるのが分割ですが、それでは軽くなりません。

Splitting into @path imports helps organization but doesn't reduce context, since imported files load at launch.

@ で複数ファイルに分けても、全部読み込むならコンテキスト消費は減りません。整理にはなりますが、量は同じです。

Codex側にも別の制限があります。AGENTS.mdなどプロジェクト指示の合計読み込み量は、既定で32 KiBまでです。公式ドキュメントによれば、合計サイズがこの上限に達した時点でそれ以上のファイルは追加されません。設定キーは project_doc_max_bytes なので、必要なら引き上げられます。

数字は違いますが、どちらも無限に書けるわけではないという点は同じです。

軽くしたいなら、選択肢は2つです。

• .claude/rules/ に置いて、paths を指定する。該当ファイルを触ったときだけ読まれる
• Skills に切り出す。呼び出したとき、または関連すると判断されたときだけ読まれる

このサイトのAGENTS.mdは、いま74行です。Next.js管理のブロックが5行、その下に画像生成ガイドが約70行。まだ分ける必要はありません。

ちなみにNext.js管理のブロックは、こういうマーカーで囲まれています。

<!-- BEGIN:nextjs-agent-rules -->
...
<!-- END:nextjs-agent-rules -->

このマーカーの外側に書いたものは、将来のNext.js更新で上書きされません。 公式にそう書かれています。自分のルールはマーカーの外に足す、と覚えておけば安全です。

指示を減らす設計そのものについては、システムプロンプトを8割削除した話にも書きました。長く書けば守られるわけではない、というのは共通しています。

まとめ 触る場所を1つに決める

要点です。

• CLAUDE.mdは @AGENTS.md の1行でいい。 Next.jsもAnthropicも、公式にその形を勧めている
• CLAUDE.mdに直接書くのと @ で取り込むのは、効き方は同じ。得られるのは保守性だけ
• ただし「AGENTS.mdに準拠すること」という文章とは1段違う。@ は必ず載り、文章は読みに行くかがAI任せ
• 二重管理は「呼び名を変えたいから」始まる。 分けたい理由が呼び名なら、分けなくていい
• 役割を変えたいなら、ファイルではなく渡し方を変える。codex exec やSkills
• Claude Codeに毎回読ませる共通指示は200行以下を一つの目安に。 @ で分割しても消費は減らないので、軽くしたいならSkillsか .claude/rules/。Codex側は合計32 KiBの上限が別にある
• Skillsは書式が共通でも、自動探索するフォルダが違う(Claude Codeは .claude/skills/、Codexは .agents/skills/)。シンボリックリンクで1本にできる
• 強制したいものはフックへ。ただしフックで書けるのは動作だけ

この構成のいちばんの価値は、触る場所が1つに決まることです。ルールを足したくなったらAGENTS.md、CLAUDE.mdは1行のまま触らない。それだけで、片方だけ古くなる事故が起きなくなります。

すぐ試すなら、いま開いているプロジェクトで diff CLAUDE.md AGENTS.md を打ってみてください。差分が数行しかないなら、その数行は本当に書き分ける必要があるか確かめる。呼び名だけだったなら、統合できます。

読み込まれているかは /context で確認できます。Memory files の一覧に出ていれば通っています。