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

公開: 2026年8月3日

AGENTS.mdは、AIコーディングエージェントに毎回説明し直している前提知識を書いておくためのファイルです。ビルドコマンドや規約をチャットで都度伝える手間がなくなり、Codexが一貫した挙動でコードを書いてくれるようになります。この記事では、AGENTS.mdの役割とCodexが読み込む配置場所・優先順位、書くべき内容の実例、避けるべきアンチパターンまでを整理します。

前提・動作環境

この記事はCodexがAGENTS.mdを読み込む挙動を前提に解説します。起動方法や承認モードは「Codex CLIの使い方」で解説しているので、あわせてご覧ください。仕様は今後もアップデートされる可能性があるため、手元の挙動と異なる場合は公式サイト(agents.md、developers.openai.com/codex)で最新情報を確認してください。

AGENTS.mdとは何か

AGENTS.mdは、特定のベンダーに縛られないオープンな標準フォーマットです。公式サイトでは「エージェント向けのREADME」と説明されており、人間向けのREADMEを簡潔に保ちながら、AIエージェントが作業に必要な文脈を専用の場所にまとめておく役割を担います。プロジェクト概要、ビルド・テストコマンド、コードスタイル、セキュリティ上の注意点などを書いておくのが基本的な使い方です。

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

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

グローバルスコープ: 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以上のツールが対応しており、60,000以上のオープンソースプロジェクトで採用されています。1つのAGENTS.mdを用意しておけば、複数のAIエージェントで指示ファイルを使い回せる点が大きなメリットです。

CLAUDE.mdとの対比

Claude CodeにはAGENTS.mdに相当する独自の指示ファイル CLAUDE.md があります。役割や連結の考え方はよく似ていますが、CLAUDE.mdは@path/to/fileによるimport構文や、組織全体・ユーザー単位のスコープなどClaude Code独自の仕様を持つ点が異なります。両方のツールを使うプロジェクトでは、CLAUDE.mdの先頭に @AGENTS.md と書いて内容を取り込む運用も可能です。CLAUDE.mdの配置場所や書き方の詳細は「CLAUDE.mdの書き方」で解説しています。

アンチパターン

長すぎる指示: 長文化するほどトークンを消費し、指示への追従精度も下がります。詳細な資料は本文に埋め込まず、サブディレクトリのAGENTS.mdに分割しましょう。
曖昧な表現: 「きれいなコードを書く」ではなく「インデントは2スペース」のように検証可能な表現で書きましょう。
階層間で矛盾する指示: ルートとサブディレクトリで逆のルールを書くと、どちらに従うか一貫しなくなります。
絶対に守らせたいルールをAGENTS.mdだけに書く: AGENTS.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に任せると、連結後のファイルサイズも抑えられます。

まとめ

AGENTS.mdは、Codexをはじめ20以上のツールが対応するオープンな指示ファイル標準です。Codexはグローバル(~/.codex/AGENTS.md)とプロジェクト内各階層のAGENTS.mdをルートから作業ディレクトリの順に連結して読み込み、作業ディレクトリに近いファイルほど優先されます。ビルド・テストコマンドや規約、禁止事項を具体的かつ簡潔に書き、長すぎる指示や曖昧な表現を避けるのがコツです。Codex全体の使い方は「Codexの使い方完全ガイド」、CLIの操作方法は「Codex CLIの使い方」もあわせてご覧ください。