AGENTS.mdの書き方｜Codexへの指示ファイル設定

Q: 既存のCLAUDE.mdをAGENTS.mdとして使い回せますか?

内容が近ければ流用可能です。CLAUDE.md側の先頭に@AGENTS.mdと書いて取り込む方法や、逆にAGENTS.mdを主として書きCLAUDE.mdから参照する方法があります。 import構文などツール固有の記法はAGENTS.md側では解釈されない点に注意してください。

公開: 2026年8月3日 / 更新: 2026年9月5日・読了目安9分

#AGENTS.md #設定

先に結論: AGENTS.mdは、ビルドコマンドや規約など毎回説明し直す前提知識をまとめておく指示ファイルです。Codexはグローバルとプロジェクト内の各階層を連結して読み込み、作業ディレクトリに近いファイルほど優先されます。

AGENTS.mdは、AIコーディングエージェントに毎回説明し直している前提知識を書いておくためのファイルです。ビルドコマンドや規約をチャットで都度伝える手間がなくなり、Codexが一貫した挙動でコードを書いてくれるようになります。

この記事では、AGENTS.mdの役割とCodexが読み込む配置場所・優先順位、書くべき内容の実例、避けるべきアンチパターンまでを整理します。

この記事の要点

AGENTS.mdは特定ベンダーに縛られないオープンな標準フォーマットで、20以上のツールが対応しています。

Codexはグローバル(~/.codex/AGENTS.md)とプロジェクト内各階層のAGENTS.mdを、ルートから作業ディレクトリの順に連結して読み込みます。

作業ディレクトリに近いファイルほど優先され、AGENTS.override.mdがあればそちらが優先されます。

連結後のファイルサイズには既定で32 KiB程度の上限があり、超えた分は読み込まれません。

Claude CodeのCLAUDE.mdとは役割が似ていますが、import構文などClaude Code独自の仕様がある点が異なります。

前提・動作環境

この記事はCodexがAGENTS.mdを読み込む挙動を前提に解説します。起動方法や承認モードは「Codex CLIの使い方」で解説しているので、あわせてご覧ください。

仕様は今後もアップデートされる可能性があるため、手元の挙動と異なる場合は公式サイト(agents.md、developers.openai.com/codex)で最新情報を確認してください。

AGENTS.mdとは何か

AGENTS.mdは、特定のベンダーに縛られないオープンな標準フォーマットです。

公式サイトでは「エージェント向けのREADME」と説明されており、人間向けのREADMEを簡潔に保ちながら、AIエージェントが作業に必要な文脈を専用の場所にまとめておく役割を担います。

プロジェクト概要、ビルド・テストコマンド、コードスタイル、セキュリティ上の注意点などを書いておくのが基本的な使い方です。

Codexが読み込む場所と優先順位

Codexは起動時にAGENTS.mdを2つのスコープで探索します。

AGENTS.mdの連結順序: グローバル→リポジトリルート→サブディレクトリ→作業ディレクトリの順に読み込まれ、あとに連結されるファイルほど優先度が高いことを示す図解

グローバルスコープ: Codexのホームディレクトリ(既定は ~/.codex、環境変数 CODEX_HOME で変更可能)にある AGENTS.md を読み込みます。AGENTS.override.md が存在する場合はそちらが優先され、このスコープでは最初に見つかった1ファイルのみが使われます。
プロジェクトスコープ: Gitリポジトリのルートから、現在の作業ディレクトリまでを階層順にたどり、各ディレクトリで AGENTS.override.md → AGENTS.md の順に確認します。1ディレクトリにつき最大1ファイルが対象です。

見つかったファイルは上書きではなく連結され、ルートに近いファイルが先、作業ディレクトリに近いファイルが後ろに配置されます。あとから連結された指示ほど優先されるため、階層の深いAGENTS.mdでルートの指示を上書き・補足できます。

なお結合後のファイルサイズには既定で32 KiB程度の上限があり、超えた分は読み込まれません。大きくなりすぎた場合はサブディレクトリごとに分割しましょう。

書くべき内容(サンプル)

書くべきなのは、ビルド・テストのコマンド、コーディング規約、やってはいけない操作です。以下はNode.js製APIを想定したサンプルAGENTS.mdの全文です。

# プロジェクト概要

社内向け在庫管理APIです。Node.js + TypeScript + Fastifyで構築しています。

## セットアップ・ビルドコマンド

- 依存関係のインストール: `npm install`
- テスト実行: `npm test`
- 型チェック: `npm run typecheck`
- Lint: `npm run lint`

## コーディング規約

- インデントは2スペース、APIレスポンスは `{ data, error }` の形式で統一する
- 新規APIエンドポイントを追加した場合は必ずE2Eテストを追加し、`npm test` を通してからコミットする

## 禁止事項

- `src/db/schema.sql` は直接編集しない(マイグレーションコマンド経由で変更する)
- `main` ブランチへの直接pushは禁止。必ずPR経由にする
- APIキーやトークンをログに出力しない

Codex CLIでは /init で、リポジトリを解析したAGENTS.mdのたたき台を自動生成できます。まずは自動生成させ、チーム独自のルールを手動で書き足す流れが効率的です。

Codex以外のツールでも使われる標準

AGENTS.mdはCodex専用の仕様ではありません。

公式サイトによると、Cursor、GitHub Copilot、Google Jules、Devin、Aider、Zed、Gemini CLIなど20以上のツールが対応しており、2026年8月時点で60,000以上のオープンソースプロジェクトで採用されています。

1つのAGENTS.mdを用意しておけば、複数のAIエージェントで指示ファイルを使い回せる点が大きなメリットです。

CLAUDE.mdとの対比

Claude CodeにはAGENTS.mdに相当する独自の指示ファイル CLAUDE.md があります。

AGENTS.mdとCLAUDE.mdを比較する図解。AGENTS.mdはオープンな標準フォーマットで20以上のツールが対応しimport構文を持たないのに対し、CLAUDE.mdはClaude Code専用の仕様でimport構文や組織・ユーザー単位のスコープを持つことを示す

役割や連結の考え方はよく似ていますが、CLAUDE.mdは@path/to/fileによるimport構文や、組織全体・ユーザー単位のスコープなどClaude Code独自の仕様を持つ点が異なります。

両方のツールを使うプロジェクトでは、CLAUDE.mdの先頭に @AGENTS.md と書いて内容を取り込む運用も可能です。CLAUDE.mdの配置場所や書き方の詳細は「CLAUDE.mdの書き方」で解説しています。

モデルを切り替えたらAGENTS.mdを見直す

意外と見落とされがちなのが、使うモデルを変えたタイミングでAGENTS.mdを点検するという運用です。ChatGPTアカウントでサインインしたCodexでは2026年8月31日にGPT-5.4/5.4 miniの提供が終了し、多くの人がGPT-5.6系(Sol・Terra・Luna)へ移りました。移行手順そのものは「Codex GPT-5.6移行ガイド」にまとめていますが、モデル名を書き換えただけでは出力の傾向まで前と同じになるわけではありません。

海外の開発者コミュニティ(Redditのr/GithubCopilotなど)でも、モデル世代が変わったあとに「勝手にリファクタリングの範囲を広げる」「コメントやテストの書き方が前と変わった」といった声が出て、AGENTS.md側のルールを書き足して落ち着かせた、という議論が交わされています(2026年9月時点の掲示板の書き込みで、性能や仕様が公式に確認されたものではありません)。前提として、モデルの挙動の細部はベンダーが公表していない部分が多く、体感の差を数値で比較することはできません。だからこそ、期待する振る舞いを自分の言葉でファイルに固定しておく意味があります。

具体的には、次の3点を見直すと差が埋まりやすくなります。

コーディング規約: 命名・インデント・エラー処理の書き方など、「前のモデルは暗黙に合わせてくれていた」ものを明文化します。
テスト方針: テストを追加する条件、実行するコマンド、通してからコミットするというルールを具体的に書きます。
出力形式と作業範囲: 「指示された範囲外のファイルは変更しない」「差分は小さく分ける」など、やってほしくないことを禁止事項として書くのが効きます。

なお、AGENTS.mdはあくまで文脈情報で強制力はありません。確実に止めたい操作は承認モードやサンドボックスと組み合わせてください。

アンチパターン

長すぎる指示: 長文化するほどトークンを消費し、指示への追従精度も下がります。詳細な資料は本文に埋め込まず、サブディレクトリのAGENTS.mdに分割しましょう。
曖昧な表現: 「きれいなコードを書く」ではなく「インデントは2スペース」のように検証可能な表現で書きましょう。
階層間で矛盾する指示: ルートとサブディレクトリで逆のルールを書くと、どちらに従うか一貫しなくなります。
絶対に守らせたいルールをAGENTS.mdだけに書く: AGENTS.mdは文脈情報であり強制力のある設定ではありません。確実に阻止したい操作は承認モードやサンドボックスの設定と組み合わせましょう。

つまずきポイント/よくあるエラー

バグイヌ

同じフォルダにAGENTS.mdとAGENTS.override.mdを両方置いたら、AGENTS.mdに書いたルールが全然守られなくて焦りました…。

ハブネコ

同じディレクトリにAGENTS.override.mdがあると、そちらだけが読み込まれる仕様です。共存させたい内容はAGENTS.override.md側に統合してください。

AGENTS.mdを置いたのに反映されない: グローバルスコープでは1ファイルしか読まれません。~/.codex配下のパスが正しいか確認してください。
サブディレクトリの指示が効かない: プロジェクトスコープはGitリポジトリのルートから作業ディレクトリまでの経路しか探索しません。無関係な階層に置いても読み込まれません。
ファイルサイズの上限で一部が反映されない: 連結後のサイズが上限(既定32 KiB程度)を超えると、それ以降は読み込まれません。不要な記述を削るか、ファイルを分割してください。
AGENTS.override.mdとの優先順位を誤解する: 同じディレクトリに両方置いても、AGENTS.override.mdがあればそちらだけが使われます。

よくある質問

AGENTS.mdとREADME.mdは何が違いますか?

README.mdは人間の読者向けにプロジェクトを紹介するファイルです。AGENTS.mdはAIエージェント向けに特化しており、ビルドコマンドや規約などエージェントが作業する上で必要な情報に絞って書きます。

両方を用意し役割を分けるのが基本です。

既存のCLAUDE.mdをAGENTS.mdとして使い回せますか?

内容が近ければ流用可能です。CLAUDE.md側の先頭に@AGENTS.mdと書いて取り込む方法や、逆にAGENTS.mdを主として書きCLAUDE.mdから参照する方法があります。

import構文などツール固有の記法はAGENTS.md側では解釈されない点に注意してください。

AGENTS.mdはどのくらいの粒度で分割すべきですか?

モノレポやディレクトリごとに規約が大きく異なる場合は、サブディレクトリごとに分割するのがおすすめです。ルート直下には共通ルールのみを書き、専門的なルールは該当ディレクトリのAGENTS.mdに任せると、連結後のファイルサイズも抑えられます。

ハブネコのひとこと

32 KiBの上限は連結後のサイズなので、複数階層に書き足しているとある日突然一部が読み込まれなくなります。長くなってきたらサブディレクトリへの分割を早めに検討すると安心です。

まとめ

AGENTS.mdは、Codexをはじめ20以上のツールが対応するオープンな指示ファイル標準です。

Codexはグローバル(~/.codex/AGENTS.md)とプロジェクト内各階層のAGENTS.mdをルートから作業ディレクトリの順に連結して読み込み、作業ディレクトリに近いファイルほど優先されます。

ビルド・テストコマンドや規約、禁止事項を具体的かつ簡潔に書き、長すぎる指示や曖昧な表現を避けるのがコツです。

Codex全体の使い方は「Codexの使い方完全ガイド」、CLIの操作方法は「Codex CLIの使い方」もあわせてご覧ください。