AGENTS.mdとCLAUDE.mdを1本にまとめる2つの書き方

Last updated at 2026-09-14Posted at 2026-09-14

プロジェクトの直下に AGENTS.md を置いて、Claude Code を起動した。中身の指示は効かなかった。同じファイルを Codex に渡すと、そちらは効いた。

逆に CLAUDE.md を置くと、今度は Claude Code だけが効いて、Codex は無視した。

「同じことを2つのファイルに書いて、片方を更新し忘れる」という、いちばん退屈な事故が起こる形だ。この記事は、置き方を4通り測った記録と、そこから出てきた解である。解は1行で書ける。しかも書き方が2つあって、片方は環境を選ぶ。

測ったのは 2026-08-28、Claude Code 2.1.246（native build）と Codex CLI 0.147.0、WSL2 の Ubuntu。

公開の直前に測り直した（2026-09-14・Claude Code 2.1.259 / Codex CLI 0.153.4）。13版ぶん進んでいるが、下の4通りは8つのセルとも結果が変わっていない。AGENTS.md だけでは届かず、CLAUDE.md だけなら届き、両方置くと CLAUDE.md の側が出て、symlink は効く。

測り方

どちらのファイルが読まれたかを、感覚ではなく出力で判定したい。そこで指示そのものを目印にした。置くファイルの中身はこれだけ。

# Project instructions

When you reply, the FIRST line of your reply must be exactly this and nothing else:

MARKER=AGENTS_ONLY

Then answer the question normally in one short sentence.

MARKER= の値だけを変えて、4つのディレクトリに置き分ける。そこへ、指示と何の関係もない質問を投げる。

printf 'What is 2+2?' | claude -p --model haiku
codex exec -s read-only --skip-git-repo-check "What is 2+2?"

返事の1行目に目印が出れば、そのファイルの指示は届いている。出なければ届いていない。

結果

置いたファイル	Claude Code 2.1.246	Codex CLI 0.147.0
`AGENTS.md` だけ	目印なし（届かない）	`MARKER=AGENTS_ONLY`
`CLAUDE.md` だけ	`MARKER=CLAUDE_ONLY`	目印なし（届かない）
両方置く	`MARKER=BOTH_CLAUDE`	`MARKER=BOTH_AGENTS`
`CLAUDE.md` を `AGENTS.md` への symlink にする	`MARKER=SYMLINK_AGENTS`	（実体を読むので当然届く）

きれいに裏返しだった。**両方置いた場合も、互いに相手のファイルを見に行かない。**それぞれが自分の名前のファイルだけを読んで、もう一方が存在することに気づいていない。

そして4行目。CLAUDE.md を実ファイルではなく AGENTS.md への symlink にすると、Claude Code はその先を読む。

ln -s AGENTS.md CLAUDE.md

実体は AGENTS.md の1本だけ。更新箇所も1つ。この4通りで唯一「1つのファイルで両方に効いた」形がこれだった。

公開の直前に、5通り目が見つかった

この記事を出す前にもう一度見直していて、symlink を使わない形があることに気づいた。CLAUDE.md を普通のファイルにして、中身を1行だけにする。

@AGENTS.md

これだけだ。Claude Code の指示ファイルは、@ で別のファイルを取り込める。手元で測った（2026-09-14・Claude Code 2.1.259 / Codex CLI 0.153.4）ところ、この形も両方に届いた。目印は MARKER=IMPORT_AGENTS で、Claude Code 側も Codex 側も1行目に出した。

symlink との違いは、壊れ方だ。symlink は git のクローンの設定しだいでただのテキストになるが、この形は最初からただのテキストなので、どこへクローンしても同じものが届く。Windows の人がチームにいるなら、こちらのほうが安全だと思う。

「対応済み」で閉じているのに、なぜ届かないのか

ここが引っかかるところだ。anthropics/claude-code の issue #6235 "Feature Request: Support AGENTS.md." は、2026-08-17 に completed（完了）として閉じられている。2026-09-14 に API で見た時点で、リアクション 6,621、コメント 394 件。反応の数で並べると、このリポジトリの起票の中で1位だった（2位は 3,286 なので、倍の開きがある）。

閉じているのに、置いても読まれない。ここで「自分の環境が変なのでは」と疑って、3か所を見た。

1つめ。公式の CHANGELOG

curl -sL https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md -o CHANGELOG.md
grep -c -i "agents\.md" CHANGELOG.md   # → 0
grep -c -i "hook"       CHANGELOG.md   # → 220

先頭は 2.1.270。AGENTS.md は1回も出てこない。対照に置いた hook は 220 回出るので、探し方が壊れているわけではない。

なお、私の手元は 2.1.259 で、公式の最新はこの時点で 2.1.270 だった。11版ぶん古い状態で測っている。その11版を含めた CHANGELOG 全体を見ても AGENTS.md は0件だが、これで「入っていない」と言い切れるわけではない。後で出てくる claude import という仕組みは CHANGELOG に1行も載っていないのに実在する。つまり、載らないまま入るものはある。CHANGELOG から言えるのは「告知の側からは確かめられない」までだ。

2つめ。配られている実体

B=$(readlink -f "$(which claude)")   # ← 実際に動いている版を指すこと
grep -a -o -F "AGENTS.md" "$B" | wc -l   # → 10
grep -a -o -F "CLAUDE.md" "$B" | wc -l   # → 268

10回、出てくる。知らないわけではない。ここは私も二度読み違えた。一度目は -a を付けずに grep して「0件」と読み、「実装が存在しない」と結論しかけた。バイナリなので grep が黙っていただけだった。二度目は、nvm の下に古い版が残っていて、そちらを数えて違う数を出した。だから上のコマンドは、パスを直に書かずに which claude から引いている。数える前に、それが本当にいま動いている実体かを確かめたほうがいい。

前後を見ると、10回の内訳は3種類。ひとつは、プロジェクトを調べるときに見るファイルの一覧（README, Makefile, existing CLAUDE.md, .claude/rules/, AGENTS.md, .cursor/rules ...）。ふたつめが本命で、Codex の設定を Claude Code へ取り込む仕組み。みっつめは、その取り込みで「移せないもの」を並べた理由の文だった。

{ id: "codex:project:instructions", src: AGENTS.md,          target: CLAUDE.md      }
{ id: "codex:project:override",     src: AGENTS.override.md, target: CLAUDE.local.md }

AGENTS.md を読むのではなく、CLAUDE.md へ写すという向きだ。同じ場所に、こういう説明文も入っていた。

Claude Code hardcodes CLAUDE.md / AGENTS.md discovery.

字面だけ見ると「AGENTS.md も探索している」と読めるが、逆だ。これは取り込みの機能が「Codex 側の project_doc_* の設定は移せません」と断る理由として書いている文で、読み込みの仕様の説明ではない。実際に読み込みの分岐をたどると、出てくるのは CLAUDE.md と CLAUDE.local.md だけだった。

case "Project": return Ke(n, "CLAUDE.md");
case "Local":   return Ke(n, "CLAUDE.local.md");

3つめ。その仕組みを実際に呼んでみる

claude --help に口がある。

$ claude import --help
Usage: claude import [options] [source]

Import config from another AI coding agent into Claude Code

Arguments:
  source      Which agent to import from (codex, gemini)

隔離した HOME で叩いた。

$ claude import codex --dry-run
`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

まだ有効になっていない。

だから、いまの状態はこう読むのが正確だ

AGENTS.md を置いただけでは、指示は届かない（2.1.246 で実測。2.1.259 でも同じ）
要望の起票は「完了」で閉じているが、CHANGELOG に記載はなく、対応するらしき仕組みはこのビルドでは無効
しかもその仕組みは「読む」ではなく「写す」。一度取り込んだら、以後は2つのファイルが別々に育つ

私が知りたかったのは「実装が存在するか」ではなく「いま自分の環境で効くか」だった。閉じた起票は前者の答えにはなるが、後者の答えにはならない。

正直な限界

測ったのは2つの道具だけだ。手元にあるのがこの2つだからで、Cursor・Copilot・Gemini CLI・Cline については測っていない。書いていないものは、確かめていないという意味だ
版とOSが1つずつだ（初回は Claude Code 2.1.246 native build / Codex 0.147.0 / WSL2 上の Ubuntu）。次の版で変わりうる。というより、変わってほしいところだ。公開の直前に Claude Code 2.1.259 と Codex 0.153.4 で測り直したが、8つのセルとも同じだった
この試験が示すのは「指示が効いたかどうか」であって、内部でどう読まれたかではない。目印が出なかったのは「文脈に載らなかった」と読めるが、字面だけでは「載ったのに従わなかった」を排除できない。逆に、道具を使ってファイルを自分で開きに行って従う、という挙動もありうる。そこは1段深く測れる。--output-format stream-json --verbose を付けて道具の呼び出しを数えると、AGENTS.md だけを置いた側は0件だった（CLAUDE.md 側も0件で、そちらは目印が出ている）。探しにも行っていない、ということになる。この測り方は別の記事に書いた
symlink は環境を選ぶ。Windows のネイティブなファイルシステムや、core.symlinks=false の git のクローンでは、リンクではなくパスが書かれたただのテキストファイルになる。私が確かめたのは WSL2 上の Linux ファイルシステムだけだ。この罠が実際にどう見えるかは別の記事で再現の手順まで書いた。チームに Windows の人がいるなら、symlink を選ぶ前にそちらを見てほしい

まとめ

AGENTS.md と CLAUDE.md は、互いを見ない。両方置いても、それぞれが自分のぶんだけ読む
1つのファイルで両方に効かせたいなら、ln -s AGENTS.md CLAUDE.md が最短。ただしチームに Windows の人がいるなら、CLAUDE.md に @AGENTS.md の1行を書く形のほうが壊れにくい。どちらも手元では両方の道具に届いた
**「要望が完了で閉じた」は、自分の環境で効くことの証明ではない。**5分で測れるので、測ってから前提にしてほしい

再現に必要なものは全部この記事の中にある。目印を書いたファイルを1つ置いて、関係のない質問を1つ投げるだけだ。