「CLAUDE.mdとAGENTS.mdって、結局どっちに書けばいいの?」
これ、Claude Codeを真面目に運用し始めて2週間目くらいに必ず通る道だと思います。私もそうでした。最初は片方だけに書いていて、Codexに切り替えた瞬間に「あれ、これ全然読んでないじゃん」となりました。
結論から書くと、両方必要です。そして手で同期するのは無理です。
何がどう違うのか
ざっくり言うと、
CLAUDE.md→ Claude Code(Anthropic製CLI)が起動時に自動で読み込む指示書AGENTS.md→ Codex CLI(OpenAI製)が起動時に自動で読み込む指示書
ファイル名が違うだけで、書いてある内容は基本同じです。「あなたは誰で、このプロジェクトのルールは何で、こういう時はこう動いて」を書く場所。
問題は、それぞれのCLIが自分の名前のファイルしか読まないこと。CLAUDE.mdに「絵文字使うな」と書いてあっても、Codexは知りません。逆も同じ。
片方だけで運用していた頃の事故
最初の数日、私はCLAUDE.mdだけ書いていました。Codex CLIを触ったのはトークン代を節約したかったから。
で、Codexに「コミットメッセージを生成して」と頼んだら、絵文字バリバリのメッセージが返ってきました。CLAUDE.mdには「絵文字禁止」と20回くらい書いていたのに。
理由は単純で、CodexはAGENTS.mdしか見ないから。空のAGENTS.mdしかない状態だったので、何の制約もない「素のCodex」が出力していたわけです。
「同じ内容を両方に書く」で運用してみた結果
最初に思いつくのは「コピペすればいいじゃん」です。私もやりました。
3日でやめました。
- CLAUDE.mdに新しいルールを足す
- AGENTS.mdに反映し忘れる
- 翌日、Codexだけが古いルールで動く
- 「あれ?なんで?」となって30分溶ける
これを週3回やりました。手動同期は破綻します。
自動同期の最小構成
私が今使っているのは、CLAUDE.mdを「真実のソース(single source of truth)」にして、コミット前のpre-commitフックでAGENTS.mdを自動再生成する方式です。
# tools/sync_for_codex.py(超ざっくり版)
from pathlib import Path
def main():
base = Path(__file__).resolve().parent.parent
claude_md = (base / "CLAUDE.md").read_text(encoding="utf-8")
rules_dir = base / ".claude" / "rules"
rules = ""
if rules_dir.exists():
for f in sorted(rules_dir.glob("*.md")):
rules += f"\n\n## {f.stem}\n\n" + f.read_text(encoding="utf-8")
header = "# AGENTS.md (auto-generated from CLAUDE.md - DO NOT EDIT)\n\n"
(base / "AGENTS.md").write_text(header + claude_md + rules, encoding="utf-8")
if __name__ == "__main__":
main()
これを.git/hooks/pre-commitから呼ぶようにして、CLAUDE.mdを変更してコミットすると勝手にAGENTS.mdが更新されてステージングに乗ります。
ポイントは、AGENTS.mdの冒頭に「DO NOT EDIT」と書くことです。書かないと、Codex自身がAGENTS.mdを直接書き換えに来て、次にCLAUDE.md側を変えた瞬間に上書きされて泣きます(これも私が実際にやらかしました)。
中身は「同じ」じゃなくて「同等」にする
もうひとつ重要な点。CLAUDE.mdとAGENTS.mdは同じ内容にする必要はないんです。
例えば私の場合、Claude Codeはhooks機能やSkillsがあるので、それを前提にしたルールを書けます。Codexは持っていないので、その部分は「該当機能なし」と明記しておく方が安全。
逆に、CodexはOpenAI製なので、OpenAIのモデル名やレート制限の事情を細かく書いた方が動きやすい。
つまり「両CLIで人格・データ・判断軸は同じ。ただし機能差は明示する」が正解だと思います。
今日からやれること
- まず
CLAUDE.mdを真面目に書く(誰で、何を任せたいか、禁止事項) - 同じディレクトリに
AGENTS.mdを作って、最低限のリダイレクトだけ書く(See CLAUDE.md for full instructionsでも可) - 真面目に運用するなら、上の最小スクリプトをpre-commitに入れる
- どちらのCLIを起動しても、最初に「自分が何者で、何を守るべきか」を3秒で把握できる状態にする
これだけで、Claude CodeとCodexを気分で切り替えても挙動がブレなくなります。私の場合、これを整備したあとは「今日はCodexで」「明日はClaude Codeで」と完全に気分で選べるようになって、コスト効率も品質も両立できるようになりました。
両方の良いとこ取りをしたい人ほど、最初に同期の仕組みを作っておくのをおすすめします。
コメント