AGENTS.mdとは｜CLAUDE.mdとの違いと、Codex（コーデックス）のスキルが .agents に置かれる理由

公開日: 2026年7月27日更新日: 2026年7月30日

Claude Codeを一通り触ってからCodexを使い始めると、まず置き場所でつまずきます。同じ「AIに前提を教えるファイル」なのに、片方はCLAUDE.md、もう片方はAGENTS.md。さらにCodexでは、サブエージェントは.codexの下にあるのに、スキル（手順書）だけ.agentsという別のフォルダに置かれます。

みやっち🧑‍💻も2026年7月にCodexのフォルダ構成を調べていて、この分かれ方に引っかかりました。結論から言うと、これは片方の設計が雑なのではなく、何を「ツールの設定」とみなし、何を「持ち運べる資産」とみなすかという線の引き方が違うだけです。

AGENTS.mdとは AGENTS.mdは、AIコーディングエージェントに毎回読ませる前提や指示をまとめるための、オープンな共通フォーマットです。リポジトリのルートに置いておくと、OpenAIのCodexをはじめ多くのツールが作業の前に読み込みます。公式サイト（agents.md）によれば6万件以上のオープンソースプロジェクトで使われており、現在はLinux Foundation傘下のAgentic AI Foundationが管理しています。Claude Codeが読むのはAGENTS.mdではなくCLAUDE.mdです。

この記事では、公式ドキュメントで確認できた置き場所だけを並べたうえで、その裏にある設計思想の違いと、AIエージェントに投資する側にとっての実利を整理します。

AGENTS.mdとCLAUDE.mdは何が違うのか

役割はほぼ同じです。どちらも「セッションの最初にAIが読む前提ファイル」で、事業の前提・書き方のルール・やってほしくないことを書いておく場所です。違うのは、どのツールが読むかと、どこを探しに行くかです。

AGENTS.md: Codexの公式ドキュメントは「Codexは作業を始める前にAGENTS.mdファイルを読む」と明記しています。全プロジェクト共通の~/.codex/AGENTS.mdと、プロジェクト側のAGENTS.mdを、リポジトリのルートから作業中のフォルダへ向かって順に重ねて読みます
CLAUDE.md: Claude Codeの公式ドキュメントは「Claude CodeはCLAUDE.mdを読み、AGENTS.mdは読まない」と明記しています。置き場所はプロジェクトのCLAUDE.mdまたは.claude/CLAUDE.md、個人設定は~/.claude/CLAUDE.mdです

つまり、AGENTS.mdは複数ツールが乗り合う共通の待合室、CLAUDE.mdはClaude Code専用の入口です。CLAUDE.mdそのものの書き方はCLAUDE.mdを社内憲法にするで詳しく書いています。

Codexのスキルが .codex ではなく .agents に置かれる理由

ここが今回いちばん面白かったところです。Codexの公式ドキュメントでは、スキルの探索場所として.agents/skills（作業フォルダからリポジトリのルートまで）と~/.agents/skillsが挙げられています。一方、サブエージェントの定義ファイルは~/.codex/agents/と.codex/agents/にTOML形式で置く、と別のページに書かれています。同じ製品なのに、置き場所が2系統に分かれているわけです。

理由は、スキルがCodex独自の形式ではないからです。Codexの公式ドキュメントは「スキルはオープンなAgent Skills標準の上に成り立っている」と書き、仕様サイト（agentskills.io）を参照しています。そしてその仕様サイト自身が、このフォーマットはもともとAnthropicが開発し、オープン標準として公開されたものだと説明しています。Claude Codeの公式ドキュメントにも「Claude CodeのスキルはAgent Skillsのオープン標準に従う」という記述があります。

Agent Skillsの中身は、SKILL.mdを含むただのフォルダです。名前と説明だけが起動時に読まれ、依頼が説明文と噛み合ったときに初めて本文が読み込まれる——この段階的な読み込みのおかげで、手順書をたくさん持っていても普段の負荷が増えません。どの情報をいつ渡すかというコンテキストエンジニアリングの考え方が、そのまま仕様になっています。手順書そのものの作り方はClaude Code Skillsの作り方を参照してください。

置き場所の一覧（公式ドキュメントで確認できたもの）

	Claude Code	Codex
毎回読む前提ファイル	`CLAUDE.md` または `.claude/CLAUDE.md`（個人設定は `~/.claude/CLAUDE.md`）	`AGENTS.md`（個人設定は `~/.codex/AGENTS.md`）
スキル（手順書）	`.claude/skills/<名前>/SKILL.md`（個人は `~/.claude/skills/`）	`.agents/skills/<名前>/SKILL.md`（個人は `~/.agents/skills/`）
サブエージェント	`.claude/agents/`（個人は `~/.claude/agents/`）	`.codex/agents/`（個人は `~/.codex/agents/`・TOML形式）

なお、個人設定の~/.codex/AGENTS.mdは、ChatGPTデスクトップアプリの設定＞パーソナライズにある「カスタム指示」の欄と同じものを指しています。別々のファイルが同期されるのではなく、同じ設定に入口が2つあるだけです（詳しくはCodexのカスタム指示は「書かない」）。

表を眺めると、分かれ方の規則が見えてきます。Claude Codeは前提ファイル・スキル・サブエージェントを製品の名前がついた場所にまとめています。Codexはスキルだけをツール名の付かない.agentsに出し、実行まわりの設定を.codexに残しています。

設計思想の違い（束ねる設計と、切り離す設計）

この差は、優劣ではなく線引きの違いです。

Claude Codeは製品単位で束ねる設計です。.claudeを開けば、前提もスキルもサブエージェントも揃っている。設定が1か所に集まるので、全体を把握しやすく、持ち出すときもフォルダごと運べます
Codexは資産と設定を切り離す設計です。ツールをまたいで使い回せる能力（スキル）はツール名の付かない.agentsへ、Codexでしか意味を持たない実行設定は.codexへ。名前の時点で「これは共通、これは固有」と宣言しています

言い換えると、.agentsは「エージェントが使う再利用可能な能力」、.codexは「Codex固有の実行設定」です。この一行を頭に入れておくと、新しい機能が増えたときも、どちらに置かれるか予想がつくようになります。

読者にとっての実利は「作った手順書が資産になるかどうか」

ここまでは仕様の話です。事業をやっている側にとっての意味はもっと単純で、自分の業務手順をAIに覚えさせる投資が、ツールを乗り換えても残るかどうかという話になります。

たとえば、請求書チェックの手順、見積書の書き方、顧客への返信トーン。これを一度手順書にしておくと、次からは合図ひとつで同じ品質の作業が返ってきます。困るのは「じゃあ、Claude CodeとCodexのどっちに投資すればいいのか」で止まってしまうことです。ここで手が止まると、半年経っても手順書がゼロのままになります。

分け方が分かると、この迷いが消えます。

手順書（スキル）はツールを乗り換えても持ち運べる資産。Agent Skillsの形式に沿って書いてある限り、対応するツールなら読み込めます
実行設定はツールごとに作り直すもの。サブエージェントの定義のように、書式そのものが違うものは移せません（Claude CodeはMarkdown、CodexはTOML）

つまり、投資すべきはスキルの方です。「どちらのツールに賭けるか」で止まっていた状態から、「手順書は共通の資産として貯める、実行設定は使う方のツールで作る」と決めて動ける状態に変わります。

二重管理を避ける（このサイトでの運用）

置き場所が分かれると、次に起きるのが「同じ内容を2か所にコピーして、片方だけ古くなる」事故です。SSOT（唯一の正典）を守る運用が要ります。

みやっち🧑‍💻は、複数のプロジェクトで共通して使うスキルの正本を1つのリポジトリにまとめ、各パソコンの設定フォルダからはシンボリックリンク（ファイルの実体を持たない参照用のショートカット）で参照する形にしています。過去に、同じスキルをプロジェクトごとにコピーしていて、片方の修正がもう片方に届いていなかったことがありました。正本を1つに決めてリンクで参照する形に変えてからは、その分岐が起きていません。

この方式が使えるのは、両方の公式ドキュメントがシンボリックリンクの追従を明記しているからです。Codexは探索時にリンク先を辿ると書かれており、Claude Codeもスキルのフォルダがリンクの場合はリンク先のSKILL.mdを読むと書かれています。

前提ファイルの方も同じです。Claude Codeの公式ドキュメントは、すでにAGENTS.mdがあるリポジトリでは、CLAUDE.mdの中で@AGENTS.mdと書いて取り込むか、CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする方法を案内しています。内容を二重に書かず、1つの正本を両方から参照する形です。

よくある質問

AGENTS.mdとCLAUDE.mdは両方置くべきですか

内容が同じなら、両方に同じ文章を書く必要はありません。Claude Codeの公式ドキュメントは、CLAUDE.mdの中で@AGENTS.mdと書いて取り込む方法と、CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする方法を案内しています。Claude Codeだけに効かせたい追記があれば、取り込みの下に書き足せます。

Codexのスキルはどのフォルダに作ればいいですか

プロジェクト単位なら、リポジトリの.agents/skills/<名前>/SKILL.mdです。どのプロジェクトでも使いたい個人用のスキルは~/.agents/skills/に置きます。フォルダの中にSKILL.mdがあり、その先頭に名前と説明が書かれていることが条件です。

Claude Codeで作ったスキルをCodexでも使えますか

Agent Skillsの標準に沿ったSKILL.mdであれば、形式としては共通です。ただし置き場所と、各ツールが独自に足している機能（呼び出しの制御など）は同じではないので、そのままフォルダを移せば必ず動く、とまでは言えません。まずは1つのスキルで動作を確かめてから、資産をまとめていくのが安全です。

まず1つ、手順書を作るところから

置き場所の違いは、覚えてしまえば5分で終わる話です。本当に効くのは、その先で「自分の業務手順を、AIが読める形で1つ持っているかどうか」の方です。

同じ仕事を毎回口で説明している——その1つを手順書にすると、AIは同じ品質で再現するようになります。これは、人を雇っても汎用の業務ソフトを買っても手に入りません。あなたの業務のやり方をそのまま覚えた、自分専用の分身だからです。AI CrewはClaude Code・Codexの両方を扱う講座で、こうした手順書づくりを画面を一緒に触りながらお伝えしています。自分の仕事を資産の形にしてみたい方は、まず無料セミナーでお会いしましょう。