CLAUDE.md と AGENTS.md の書き方完全比較 — AIコーディングツールの「設定ファイル」を正しく使い分ける
Claude CodeとCodex CLI、どちらもプロジェクトに「設定ファイル」を置いて、AIの振る舞いをカスタマイズできます。
Claude Codeなら `CLAUDE.md`、Codex CLIなら `AGENTS.md`。
名前は違いますが、やろうとしていることは同じです。
「このプロジェクトではこういうルールで書いてね」とAIに伝えるための指示書。
ただ、似ているようで中身のルールが微妙に違います。
片方で覚えた書き方をそのままもう片方に持っていくと、意図通りに動かないことがある。
この記事では、CLAUDE.mdとAGENTS.mdの「どこが同じでどこが違うのか」を整理し、それぞれのスキルファイルの作り方まで含めて比較します。
記事の最後に、そのままコピペして使えるテンプレートも用意しました。
そもそも何のための設定ファイルか
どちらも目的は1つです。
「AIがコードを読んだだけでは分からない情報」を伝えるためのファイルです。
具体的には、こういうことを書きます。
ビルド・テストの実行コマンド
コーディング規約（インデント、命名規則など）
プロジェクト固有のアーキテクチャ上の決定事項
「やってはいけないこと」の明示
よくあるハマりポイントの注意書き
逆に、書かなくていいものもあります。
コードを見れば分かること（使っている言語、フレームワーク等）や、言語の一般的な慣習（Pythonのインデントは4スペース等）は、AIが既に知っているので書く必要はありません。
この「何を書いて何を書かないか」の判断は、CLAUDE.mdでもAGENTS.mdでも共通です。
ファイルの置き場所 — 階層構造の比較
どちらも「複数の場所にファイルを置ける」仕組みを持っています。
ただし、階層の名前や読み込みの挙動が違います。
Claude Code（CLAUDE.md）
グローバル（個人）: `~/.claude/CLAUDE.md` — 全プロジェクト共通の指示
プロジェクト: `./CLAUDE.md` — チーム全員に適用（Git管理）
個人×プロジェクト: `./CLAUDE.local.md` — 自分だけに適用（.gitignoreに追加推奨）
サブディレクトリ: `./src/CLAUDE.md` — そのフォルダの中でだけ適用
重要なポイントは、CLAUDE.mdは全ファイルが連結されて読み込まれることです。
上書きではなく追加。ルートのCLAUDE.mdもサブディレクトリのCLAUDE.mdも、両方が有効になります。
サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリのファイルを実際に読んだときにオンデマンドで読み込まれるという特徴もあります。
起動時に全部読むわけではありません。
さらに、`@path/to/file` でファイルのインポートが可能です（最大5階層まで）。
設定が長くなったら、別ファイルに分けてインポートする方が管理しやすくなります。
Codex CLI（AGENTS.md）
グローバル（個人）: `~/.codex/AGENTS.md` — 全プロジェクト共通の指示
プロジェクト: `./AGENTS.md` — チーム全員に適用（Git管理）
一時オーバーライド: `./AGENTS.override.md` — ベースを変えずに上書き
サブディレクトリ: `./src/AGENTS.md` — そのフォルダ以下で適用
大きな違いが2つあります。
1つ目: 各ディレクトリにつき「最大1ファイル」しか読まれない。
AGENTS.mdとAGENTS.override.mdが同じフォルダにある場合、override.mdだけが読まれます。
Claude Codeは全部連結するのに対し、Codexは優先度の高い1つだけを選びます。
2つ目: 他ツールの設定ファイルをフォールバックとして読める。
`config.toml` の設定で、AGENTS.mdが見つからないときにCLAUDE.mdを代わりに読むことができます。
つまり、CLAUDE.mdしか置いていないプロジェクトでも、Codex CLIがそれを拾ってくれる可能性があります。
書くべき内容 — 共通点と違い
基本的に書く内容は同じです。
ただし、AIに対する「効き方」に少し違いがあります。
両方で共通して効果が高い内容
ビルド/テストコマンド: `npm run build`, `pytest tests/` など
コーディング規約: インデント、命名規則、importの書き方
やってはいけないこと: 「mainブランチに直接pushするな」「このフォルダは触るな」
プロジェクト固有の注意: 環境変数の説明、特殊なディレクトリ構成
CLAUDE.md固有のポイント
推奨サイズは200行以内。
CLAUDE.mdは毎ターン、コンテキストに全文が注入されます。
長すぎると「指示が埋もれて無視される」（lost in the middle現象）リスクがあります。
200行を超えそうなら、`@import` や `.claude/rules/` に分割しましょう。
HTMLコメントは無視される。
`<!-- -->` で囲んだ部分はClaude Codeに渡される前にストリップされます。
人間向けのメモを書く場所として使えます。
「IMPORTANT」「YOU MUST」が効く。
強調したいルールにはこれらのキーワードを使うと、Claudeがより忠実に従う傾向があります。
AGENTS.md固有のポイント
サイズ制限は `config.toml` で設定。
`project_doc_max_bytes` で各AGENTS.mdの読み込みバイト上限を指定できます。
明示的にサイズを制御できるのはCodex側の特徴です。
プロファイルで設定を切り替えられる。
`config.toml` に `[profile.careful]` のような名前付きプリセットを定義し、`codex --profile careful` で切り替えることができます。
モデルや承認ポリシーをプロファイルごとに変えられるので、「コードレビュー用」「自由に書かせる用」のように使い分けられます。
AGENTS.override.mdで一時的な上書きができる。
実験的にルールを変えたいとき、ベースのAGENTS.mdを触らずにoverride.mdで上書きできます。
実験が終わったら削除するだけ。
スキルファイルの比較 — ここが一番違う
「スキル」はどちらのツールにもあります。
特定のタスクをパターン化して、再利用可能なテンプレートにする仕組みです。
ただし、ファイル構造がかなり違います。
Claude Code のスキル（.claude/skills/）
.claude/skills/
└── my-skill/
└── SKILL.md ← これだけでOK最小構成は SKILL.md 1ファイルだけ。
フロントマター（ファイル冒頭の `---` で囲んだ設定ブロック）は任意です。なくても動きます。
フロントマターに書けること:
`name`: スキル名（省略時はフォルダ名がそのまま使われる）
`description`: いつ使うべきかの説明
`effort`: 実行時のエフォートレベル（low / medium / high / max）
`model`: 使用モデルの指定
`allowed-tools`: 使えるツールの制限
`context: fork`: サブエージェントとして別コンテキストで実行
呼び出し方は `/my-skill` のスラッシュコマンド。
あるいは、descriptionの内容に基づいてClaudeが自動的にスキルを呼び出すこともあります。
スキル内で `$ARGUMENTS` を使うと、呼び出し時に渡した引数を受け取れます。
`!`backtick command`` でシェルコマンドの出力を埋め込む動的コンテキストも使えます。
Claude Codeの基本的な使い方はこちらの記事にまとめています:
Codex CLI のスキル（.agents/skills/）
.agents/skills/
└── my-skill/
├── SKILL.md ← 必須
├── scripts/ ← スクリプト同梱可能
├── references/ ← 参照資料を同梱可能
├── assets/ ← テンプレ等を同梱可能
└── agents/
└── openai.yaml ← UIメタデータこちらはフォルダ構造がリッチです。
YAML front matter（ファイル冒頭の `---` で囲んだ設定ブロック）が必須で、最低限 `name` と `description` を書く必要があります。
特徴的なのは:
`scripts/`: スキルが使うスクリプトを同梱できる
`references/`: 参照資料を入れておける
`agents/openai.yaml`: UIへの表示方法やツール依存を宣言できる
`allow_implicit_invocation: false`: 自動呼び出しを明示的にオフにできる
呼び出しは `/skills` メニューか `$skill-name`。
Codexの方が「スキルのパッケージ」としての完成度が高い設計になっています。
スキルの違いまとめ
Claude Code: ミニマル。SKILL.md 1ファイルで始められる。フロントマター任意。手軽さ重視。
Codex CLI: 構造化。フォルダごとスクリプトや資料を同梱できる。YAML必須。パッケージとしての完成度重視。
どちらが良いかは用途次第です。
個人で素早くスキルを作りたいならClaude Codeのシンプルさが楽。
チームで共有する本格的なスキルを作るなら、Codexの構造化された仕組みが向いています。
両方のツールを使うプロジェクトでの共存
「Claude CodeもCodex CLIも両方使っている」というプロジェクトは実際にあります。
その場合、CLAUDE.mdとAGENTS.mdを両方置いても問題ありません。
それぞれのツールは自分用のファイルだけを読むので、競合しません。
さらに、Codex CLIは `config.toml` の `project_doc_fallback_filenames` にCLAUDE.mdを追加しておけば、AGENTS.mdが見つからないときにCLAUDE.mdをフォールバックとして読んでくれます。
CLAUDE.mdだけ書いておけば両方のツールに指示が通る、という運用も可能です。
おすすめの運用方法:
1. 共通部分はCLAUDE.mdに書く
ビルドコマンド、コーディング規約、ディレクトリ構成など、ツールに依存しない情報はCLAUDE.mdに集約。
CodexのフォールバックでCLAUDE.mdを拾わせる。
2. ツール固有の指示だけ個別ファイルに書く
Claude Code特有の指示（hooksの使い方、MCP連携の注意等）はCLAUDE.mdに。
Codex特有の指示（承認ポリシー、プロファイル設定等）はAGENTS.mdに。
3. スキルファイルは完全に分ける
`.claude/skills/` と `.agents/skills/` はフォーマットが違うので、無理に共通化せず、それぞれのルールで作りましょう。
コピペで使えるテンプレート
CLAUDE.md テンプレート
# プロジェクト概要
{プロジェクト名}: {一行で説明}
## 技術スタック
- 言語: {TypeScript / Python / etc.}
- フレームワーク: {Next.js / FastAPI / etc.}
- パッケージマネージャ: {npm / pnpm / pip / etc.}
## コマンド
- ビルド: `{npm run build}`
- テスト（全体）: `{npm test}`
- テスト（単体）: `{npm test -- --grep "テスト名"}`
- lint: `{npm run lint}`
## コーディング規約
- インデント: {2スペース / 4スペース / タブ}
- 命名規則: {変数はcamelCase、定数はSCREAM_CASE}
- import: {ES modules (import/export) を使う。require は使わない}
## やってはいけないこと
- mainブランチに直接pushしない
- {.env ファイルをコミットしない}
- {/src/legacy/ 配下のファイルを変更しない（非推奨コード、触らない）}
## プロジェクト固有の注意
- {データベースの接続先は環境変数 DATABASE_URL で指定}
- {APIキーは .env.local に置く（.gitignoreに追加済み）}AGENTS.md テンプレート
# プロジェクト概要
{プロジェクト名}: {一行で説明}
## 技術スタック
- 言語: {TypeScript / Python / etc.}
- フレームワーク: {Next.js / FastAPI / etc.}
- パッケージマネージャ: {npm / pnpm / pip / etc.}
## コマンド
- ビルド: `{npm run build}`
- テスト（全体）: `{npm test}`
- テスト（単体）: `{npm test -- --grep "テスト名"}`
- lint: `{npm run lint}`
## コーディング規約
- インデント: {2スペース / 4スペース / タブ}
- 命名規則: {変数はcamelCase、定数はSCREAM_CASE}
- import: {ES modules (import/export) を使う}
## レビュー基準
- PRは必ず1人以上のレビューを通す
- テストカバレッジが下がるPRはマージしない
- {パフォーマンスに影響する変更は、ベンチマーク結果を添付}
## やってはいけないこと
- mainブランチに直接pushしない
- {.env ファイルをコミットしない}
- {外部APIのレスポンスをそのまま返さない（必ずバリデーション）}スキルファイル テンプレート（Claude Code用）
---
name: review-code
description: コードレビューを実行する。PRの差分を読んで、問題点と改善案を提示する。
effort: high
---
# コードレビュー
以下の手順でレビューを実行してください:
1. $ARGUMENTS で指定されたファイルまたはPRの差分を読む
2. 以下の観点でチェック:
- バグの可能性がある箇所
- パフォーマンス上の問題
- セキュリティリスク
- コーディング規約からの逸脱
3. 問題があれば具体的な修正案を提示
4. 問題がなければ「LGTM」と報告スキルファイル テンプレート（Codex CLI用）
---
name: review-code
description: コードレビューを実行する。PRの差分を読んで、問題点と改善案を提示する。
---
# コードレビュー
以下の手順でレビューを実行してください:
1. 指定されたファイルまたはPRの差分を読む
2. 以下の観点でチェック:
- バグの可能性がある箇所
- パフォーマンス上の問題
- セキュリティリスク
- コーディング規約からの逸脱
3. 問題があれば具体的な修正案を提示
4. 問題がなければ「LGTM」と報告まとめ
CLAUDE.mdとAGENTS.md、やっていることは同じ「AIへの指示書」です。
ただし、設計思想が違います。
Claude Codeは「シンプルに始めて、必要に応じて拡張する」アプローチ。
Codex CLIは「最初から構造化して、チームでの運用を想定する」アプローチ。
どちらが優れているという話ではありません。
自分が使っているツールに合わせて、適切なファイルを適切な場所に置く。
それだけでAIの出力品質は確実に上がります。
まだ設定ファイルを作っていないなら、テンプレートをコピペして、プロジェクトのルートに置くところから始めてみてください。
5分で終わりますが、効果は毎回のAI利用で実感できるはずです。
この記事が参考になったら、ぜひ「スキ」をお願いします！
