AI コーディングを運用し始めると、かなり早い段階で同じ混乱に当たります。AGENTS.md と CLAUDE.md の両方が出てくるが、何をどちらへ書くべきか分からない。repo のビルド手順、レビュー条件、ブランチ運用、個人の作業メモ、長い調査手順を全部同じ場所へ押し込むと、最初は動いても数週間で破綻します。
特に危ないのは次の状態です。
- repo 全体のルールを
CLAUDE.mdだけに書いて、Codex 側に共有されない - Claude 専用の長い手順を
AGENTS.mdに押し込んで、他エージェントにも毎回読ませる - 例外対応や一時メモを本体ファイルへ足し続けて、重要なルールが埋もれる
この記事は、AGENTS.md と CLAUDE.md を責務で分けたい人向けです。Claude 固有の instruction 設計を深掘りしたいなら CLAUDE.md の書き方と育て方、Codex 側の再利用手順へ広げたいなら Codex Skills 設計入門、複数エージェントと worktree 分離まで含めて設計したいなら Codex cloud / 複数エージェントの使い方、そもそも上位の制御設計から整理したいなら Harness Engineering 入門 が先に繋がります。
先に結論: AGENTS.md は共有ルール、CLAUDE.md は Claude Code の継続文脈
まず、いちばん重要な整理を先に置きます。
AGENTS.md: repo やディレクトリ単位で共有したい、エージェント横断の作業ルールCLAUDE.md: Claude Code に継続的に渡したい、Claude 専用の文脈と運用メモ
この違いを「どちらも instruction file だから同じ」と扱うと外します。OpenAI 側の docs では、Codex は AGENTS.md を階層的に読み、作業前の指示やディレクトリ単位の追加ルールに使います。一方、Anthropic 側の docs では、CLAUDE.md は Claude Code が session ごとに読む memory file で、enterprise / project / user の階層を持ち、@path で追加ファイルを参照できます。
つまり、前者は repo をどう扱うか のファイル、後者は Claude にどう振る舞ってほしいか のファイルです。
比較表: 読む主体と責務が違う
| 観点 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 主な読者 | Codex を含む coding agent | Claude Code |
| 主な目的 | 共有ルール、作業前提、検証手順、禁止事項 | Claude の継続文脈、記憶、補助指示 |
| スコープ | global / project / subdirectory を階層適用 | enterprise / project / user を積み上げ |
| 向いている内容 | build コマンド、branch 運用、レビュー条件、対象ディレクトリの注意点 | Claude 専用の作業メモ、import、home 配下の個人メモ |
| 肥大化時の逃がし先 | 下位ディレクトリの AGENTS.md、skills、docs | @import、subdirectory CLAUDE.md、skills |
ここで大事なのは、両方とも「全部を書く場所」ではないことです。どちらも短く保ち、必要な粒度で分割しないと運用が崩れます。
先に補足: AGENTS.md が必須とは限らない
ここは誤解されやすいので先に補足します。
もしその repo を Claude Code だけで運用するなら、shared instructions を CLAUDE.md に集約しても構いません。Anthropic の docs でも、project memory の CLAUDE.md は team-shared instructions を置く前提です。
私が AGENTS.md を先に置くべきだと言っているのは、Codex も Claude Code も使う repo か、将来ほかの coding agent を足す可能性があるケースです。大事なのは「絶対に AGENTS.md を作ること」ではなく、どの file を shared rule の source of truth にするかを先に固定することです。
AGENTS.md に書くべきもの
私なら AGENTS.md には、Claude 以外の agent が読んでも意味が通るものだけを書きます。
- 使うべきコマンド
- build / test / format の順序
- branch / worktree の運用ルール
- review で必ず見る観点
- そのディレクトリで触ってはいけないもの
たとえば、このブログ repo なら次のような内容は AGENTS.md 向きです。
pnpm run buildとpnpm seo:update-llmsを通す- dirty worktree では
checkout/pull/resetをしない - ブログ記事の slug 規約
- 主戦場テーマと信用用テーマの区別
これらは Claude だけの事情ではありません。Codex でも Claude Code でも、同じ repo を触るなら共通で守らせたいルールです。
OpenAI の Harness Engineering 記事でも、AGENTS.md は「百科事典」ではなく、深い資料への map として扱う方がよいと説明されています。私はこれをかなり重く見ています。AGENTS.md が太ると、どの agent にも毎回長文を読ませることになり、コストも遵守率も悪化するからです。
CLAUDE.md に書くべきもの
逆に CLAUDE.md は、Claude Code の session をまたいで効かせたい文脈を置く場所です。Anthropic の docs では、CLAUDE.md は project root だけでなく、home 配下や子ディレクトリにも置けますし、@path で別ファイルを読む構成も推奨されています。
私なら CLAUDE.md には次を書きます。
- Claude が頻繁に忘れる repo 前提
- Claude 専用の補助的な判断基準
- compact 後も残したい要素
- 長い資料への import
- home 配下へ逃がした個人用メモ
たとえば、次は CLAUDE.md の方が自然です。
- 長時間 session で保持してほしい論点
@README.mdや@docs/architecture.mdへの参照- 自分だけが使うローカル URL や検証メモ
- Claude の出力で繰り返しズレる観点の補正
ここで重要なのは、CLAUDE.md を repo の公式規約集にしないことです。Claude にしか効かない運用ルールを唯一の source of truth にすると、他 agent や人間との整合が崩れます。
一番よくある失敗: repo 共有ルールを CLAUDE.md に閉じ込める
私はこれが一番危険だと思っています。
たとえばチームで次のようなルールを運用しているとします。
- commit 前に build を通す
- PR では SEO 回帰も確認する
- DB schema は別 PR に分ける
これを CLAUDE.md にしか書いていないと、Claude Code は守れても Codex や別の agent には共有されません。結果として、「Claude では通るが、別の自動化では守られない」という半端な状態になります。
共有したい規約は先に AGENTS.md へ置く。 そのうえで Claude 側で補助したい情報だけを CLAUDE.md に重ねる。この順番を逆にしない方がよいです。
逆の失敗: Claude 専用の長文手順を AGENTS.md に押し込む
これもよくあります。Claude の memory 的に効かせたい内容や、Claude 専用の長い調査手順を全部 AGENTS.md に書いてしまうパターンです。
たとえば次のようなものです。
- compact 時に必ず残してほしいメモ
- Claude 独自の import 運用
- session ごとに引き継ぎたい長い作業メモ
- Claude でだけ使う home 配下の personal note
これらは他 agent に読ませても価値が薄いか、むしろノイズになります。AGENTS.md は共有規約の層に留め、Claude 固有の補助線は CLAUDE.md へ逃がした方が運用が軽いです。
実務での分け方: 3 層で固定すると迷いにくい
私なら、instruction 系ファイルを次の 3 層で固定します。
| 置き場 | 役割 |
|---|---|
AGENTS.md | repo 全体で共有する作業ルール |
CLAUDE.md | Claude Code 用の継続文脈と補助記憶 |
| skill | 特定タスクだけで使う再利用手順 |
この切り分けにすると、かなり迷いにくくなります。
- 毎回守るべきルールなら
AGENTS.md - Claude に継続して覚えてほしいなら
CLAUDE.md - 重い手順や定型出力なら skill
OpenAI 側でも、Codex の再利用手順は AGENTS.md に全部積まず、別の repo artifact や skills へ逃がす流れが前提です。Anthropic 側でも、CLAUDE.md から import を使って長い資料を分離できます。両方の docs を合わせて読むと、instruction file は短く、手順は別部品へ分離するのが共通原則だと分かります。
両方を併用するときの設計順
新しい repo を整えるなら、私は次の順で設計します。
- まず
AGENTS.mdに shared rules だけを書く - Claude が追加で必要とする文脈を
CLAUDE.mdに足す - 長い手順は skill へ逃がす
- ディレクトリ固有ルールは下位ファイルへ分割する
この順番にする理由は単純です。最初に CLAUDE.md から書き始めると、共有規約と personal note と task 手順が混ざりやすいからです。
具体例
たとえば「新規ブログ記事 automation」を作るなら、私はこう切ります。
AGENTS.md: テーマ選定ルール、build コマンド、Git 運用、PR 作成条件CLAUDE.md: Claude が忘れやすい現行の主戦場メモ、最近の失敗傾向、local preview URL- skill: 重複チェック、内部リンク候補出し、公開前 checklist
この分け方なら、Codex automation でも Claude Code 手動執筆でも整合が取りやすいです。
path ごとの分割を使わないと、どちらもすぐ太る
OpenAI 側の AGENTS.md docs では、下位ディレクトリに AGENTS.md を置いて追加指示を積めます。Anthropic 側の CLAUDE.md も、project root だけでなくサブディレクトリや home 配下の import に分割できます。
ここはかなり重要です。monorepo や docs-heavy repo で root に全部書くのは無理があります。
たとえば次の切り方が自然です。
- repo root: 共通の build / test / branch 運用
docs/: 文書更新時のレビュー観点src/content/blog/: frontmatter や SEO の注意点~/.claude/...を import: 自分だけの URL、仮説メモ、未共有の検証メモ
「全部 root に書く」より、「その階層で必要なものだけ足す」方が読みやすく、違反時の修正もしやすいです。
何を書かないかも先に決める
どちらのファイルでも、やることより 書かないもの を決めた方が安定します。
AGENTS.md に書かないもの
- Claude 専用の session memory
- 自分だけの temporary memo
- 長い実装手順の全文
CLAUDE.md に書かないもの
- チーム共有の唯一の規約
- Claude 以外にも必須な build / branch ルールの本体
- repo 全体で再利用すべき定型 workflow の全文
この境界が曖昧だと、気づいた人が見つけた場所へ追記し始めて、半年後にメンテ不能になります。
まとめ
AGENTS.md と CLAUDE.md は、似て見えて役割が違います。
AGENTS.mdは共有ルールCLAUDE.mdは Claude 専用の継続文脈- 長い手順はどちらにも積まず skill へ逃がす
一番避けたいのは、共有規約を CLAUDE.md に閉じ込めることと、Claude 専用メモを AGENTS.md に押し込むことです。まず「これは全 agent に効かせたいのか」「Claude の継続文脈なのか」「単なる task 手順なのか」の 3 問で切ると、大きくは外しません。