AGENTS.mdとは？Codex向けの書き方・置き場所・CLAUDE.mdとの違い

AIが作業前に読む、プロジェクトの案内

AGENTS.mdは普通のMarkdown文書です。先頭へ特別な設定データを置くことは必須ではありません。対応するツールが読んで、作業の前提に使います。READMEにある情報を全部複製するより、実行時に迷う点への入口をまとめるのが使いやすい形です。

たとえば「ソースはsrc」「検査はnpm test」「自動生成物は元ファイルを直す」「公開は指示された範囲で行う」と書けば、毎回同じ説明を繰り返す量を減らせます。人が読んでも意味が分かる言葉で書きましょう。

• 出典：AGENTS.md（新しいタブ）
• 出典：Claude Code / memory（新しいタブ）

Codexでは、共通から作業場所へ向かって読む

2026年9月14日に確認した公式資料では、Codexは共通の設定場所と、プロジェクトのルートから現在の作業場所へ至る経路の指示を扱います。近い場所の指示が先の指示を上書きする関係があります。AGENTS.override.mdがある場合や、設定した別名がある場合も扱いが変わります。

このため、どこから作業を始めるかが重要です。「下のフォルダーに書けば、どこで起動しても全部読まれる」と考えないでください。初めはプロジェクトの一番上へ一枚置き、個別ルールが必要になったときだけ分けます。

まず書くのは、構成・検査・完了条件

下の例は、npm testとnpm run lintが存在する架空のプロジェクト向けです。実際には設定ファイルを確認し、使っているパッケージ管理ツールと一致させてください。コマンドを推測で書かないことが大切です。

「最高の品質で」という指示より、「変更した動作のテストを実行し、失敗したら理由と未確認範囲を報告する」の方が結果を確認できます。外部サービスの名前や秘密の値を列挙せず、必要なら設定方法を記した資料へ案内します。

適用されているか、作業の前に確かめる

新しく作業を始める際に、「読み込んだ指示ファイルと、このプロジェクトのテストコマンドを挙げて」と依頼します。想定したAGENTS.mdが含まれるか、コマンドがファイルの内容と一致するかを確認します。必要な場合は、ツールが表示する指示の読み込み記録も見ます。

公式の読み込みにはサイズ上限などの設定もあります。ファイルが長すぎるときは、同じ内容を別の場所へ重複して書くのではなく、入口を短くして詳細を参照資料へ分けます。古い運用手順へリンクし続けていないかも確認してください。

この記事のテンプレートは説明用です。別のCodexプロセスへこの例を実行させた検証ではありません。実際の適用は自分の作業環境で、表示と結果を照合してください。

CLAUDE.md・SKILL.mdとは役割が違う

CLAUDE.mdはClaude Codeで使われる指示ファイルです。AGENTS.mdをどのように扱うかはツールによって違い、名前を置き換えれば必ず動くとは限りません。共通のルールを一つの文書にまとめる場合も、各ツールからの参照方法を確認します。

SKILL.mdは、繰り返し使う手順をまとめるためのファイルです。名前と説明などのメタデータを持ち、必要な作業で読み込む形に向きます。「このプロジェクト全体の約束」と「記事監査をするときの具体的手順」を分けると、いつも長い説明を読む必要を減らせます。

一枚を保ち、失敗例から育てる

更新する理由は、文章量を増やすことではありません。「いつも違う検査を走らせる」「公開先を取り違えやすい」といった繰り返す問題を、短い指示と確認方法へ変えます。古いルールを残したまま新しいルールを追加しないことも大切です。

詳細な手順を切り出すならSKILL.mdの作り方へ。Claude Code側の運用はCLAUDE.mdの読み込み確認で、ファイルごとの違いを確認できます。

• 出典：Codex AGENTS.mdの読み込み（新しいタブ）