AGENTS.md for OpenAI Codex 完全ガイド — セットアップから実践例まで【2026年版】

AGENTS.mdは、OpenAI Codexがコードに触れる前に読み込む指示ファイルです。このファイルを正しく設定すれば、Codexは最初のプロンプトから正確なコンテキストで動作します。設定が甘いと、本来必要のなかった修正作業が増え続けます。

本記事では、AGENTS.mdの基本概念から実際の設定方法、プロダクション環境での運用パターンまで解説します。

AGENTS.mdとは

AGENTS.mdは、AIコーディングエージェントにプロジェクトの扱い方を伝えるMarkdownファイルです。OpenAIのCodex CLIで普及し、現在はAgentic AI Foundation（Linux Foundation傘下）によってオープン標準として管理されています。Codex、Cursor、Gemini CLI、Windsurf、GitHub Copilotなど多数のツールが対応しています。

人間向けのREADMEがプロジェクトの「概要」を説明するのに対し、AGENTS.mdはエージェント向けにプロジェクトの「作業方法」を説明します。どのコマンドを実行するか、どの規約に従うか、何には触れてはいけないか、が主な内容です。

Codexにおいては、AGENTS.mdの内容はセッション開始時にコンテキストウィンドウへ直接挿入されます。つまり、プロンプトより前にCodexが読む最初の情報です。

CodexがAGENTS.mdを探す仕組み

Codexは単一のAGENTS.mdを読むのではなく、ファイルシステムを走査してインストラクションチェーンを構築します。この階層を理解することが、AGENTS.mdを使いこなすうえで最も重要です。

セッション開始時、Codexは以下の順で検索を実行します。

グローバルスコープ

Codexのホームディレクトリ（デフォルトは~/.codex/）で以下の順に探します。

~/.codex/AGENTS.override.md — 存在する場合はこちらを読み、同レベルの通常AGENTS.mdはスキップ
~/.codex/AGENTS.md — 個人の共通設定

プロジェクトスコープ

Gitリポジトリのルートから現在の作業ディレクトリへ向かって、各ディレクトリで以下の順に探します。

AGENTS.override.md — 存在する場合はこちらを読み、同レベルの通常AGENTS.mdはスキップ
AGENTS.md — 標準ファイル
config.tomlのproject_doc_fallback_filenamesに指定したファイル名

マージ動作

発見したファイルはルートから現在ディレクトリの順に連結されます。後から読み込まれるファイル（作業ディレクトリに近いファイル）ほどプロンプト後半に配置され、実質的に優先度が高くなります。

モノレポでの例：

~/.codex/AGENTS.md          ← 最初に読み込み（グローバル）
repo-root/AGENTS.md         ← 次に読み込み
repo-root/packages/api/AGENTS.md  ← packages/api/で作業中なら読み込み

packages/api/で作業中なら3ファイルすべてが読み込まれます。リポジトリルートで作業中なら最初の2ファイルのみです。

32KiB制限

Codexはデフォルトでproject_doc_max_bytes（32KiB）に達したところでファイル読み込みを停止します。複数のAGENTS.mdファイルの合計がこの上限を超えると、後から読み込まれるプロジェクト固有の指示が切り捨てられます。

「プロジェクトの指示が無視される」という問題の最も多い原因がこれです。グローバルのAGENTS.mdは2〜3KB以内に抑えるのが賢明です。

AGENTS.override.mdの役割

AGENTS.override.mdは、通常のAGENTS.mdと連結するのではなく同レベルのAGENTS.mdを置き換えます。使い分けのポイントは次の2つです。

一時的な上書き

~/.codex/にAGENTS.override.mdを置くと、永続的なAGENTS.mdを変更せずにセッション固有の指示を上書きできます。作業後は削除するだけです。

パッケージレベルの置き換え

モノレポで、特定のパッケージがルートの規約と根本的に異なる要件を持つ場合、AGENTS.override.mdでルートファイルの内容を拡張ではなく置き換えられます。

注意点として、AGENTS.override.mdは「拡張」ではなく「置き換え」です。変更したい行だけ書いて他は引き継がれると思っていると動作しません。

config.tomlでの設定

AGENTS.mdの探索動作は~/.codex/config.tomlで設定できます。

# ~/.codex/config.toml

# 大規模プロジェクト向けに制限を増やす
project_doc_max_bytes = 65536  # 64KiB

# AGENTS.mdが存在しない場合の代替ファイル名
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".codex/instructions.md"]

# Codexホームディレクトリの変更（環境変数でも設定可能）
# CODEX_HOME=/custom/path でも指定できる

project_doc_fallback_filenamesは、AGENTS.md導入前にすでにCONTRIBUTING.mdなどに有用な情報が書かれているプロジェクトで特に役立ちます。内容を重複させずにそのまま参照できます。

AGENTS.mdに書くべき内容

コマンドブロック（最優先）

最も重要な項目です。ビルド・テスト・リント・起動のコマンドを先頭に置きます。

## Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- 型チェック: `npm run typecheck`
- 開発サーバー起動: `npm run dev`

モノレポの場合は実行場所も明示します。

## Commands

特に指定がない限りリポジトリルートから実行。

- 全パッケージビルド: `pnpm build --recursive`
- 単一パッケージビルド: `cd packages/api && pnpm build`
- 全テスト: `pnpm test --recursive`
- Lint: `pnpm lint`

このリポジトリはpnpmワークスペースを使用。npmコマンドは使わないこと。

最後の1行が意外に重要です。明示しないとCodexはnpmを使おうとします。

プロジェクト構造

ファイルの配置場所と理由を説明します。これがないとCodexは間違ったディレクトリにファイルを作ります。

## Project Structure

src/
  api/          # Expressルートハンドラ（リソースごとに1ファイル）
  services/     # ビジネスロジック（DBアクセスなし）
  repositories/ # DBクエリはすべてここ
  models/       # TypeScriptインターフェースとZodスキーマ

ルートハンドラにビジネスロジックを書かない。servicesに置く。

コードから読み取れない規約

「このプロジェクトはpnpmを使う」「テストはco-locatedではなくtests/に置く」といった情報はコードを読んでも分かりません。AGENTS.mdに書く意味のある情報の典型例です。

## Conventions

- TypeScript strictモード有効 — testファイル以外でanyは禁止
- エラー処理は`Result<T, E>`パターンを使用。throwしない
- DBアクセスはrepository経由のみ。servicesから直接クエリしない
- 環境変数は`config.ts`経由でアクセス。`process.env`を直接参照しない
- インポートはパスエイリアス（@/services等）を使用

書かない方がいいもの

「クリーンなコードを書く」といった抽象的な指針（Codexに何も伝わらない）
認証情報・シークレット（バージョン管理されるファイルに書いてはいけない）
READMEに書くべき説明的な文章
「ベストプラクティスに従う」のような指示（具体的に何をすべきか書く）

ギャラリーから見る実際のAGENTS.md例

The Prompt Shelfでは実際のリポジトリから収集したAGENTS.mdをルールギャラリーに掲載しています。以下は代表的な例です。

1. オープンソースプロジェクトの最小構成

AGENTS.md仕様書リポジトリ自体のAGENTS.mdは、必要最低限に絞った構成です。

# AGENTS.md

## Dev environment tips
- Node.js 20以上を使用
- `npm install`で依存関係をインストール

## Testing instructions
- `npm test`でテスト実行
- すべてのPRはテスト通過必須

## PR instructions
- PRは1つの変更に集中させる
- 動作変更時はテストも更新する

多くの企業のコントリビューターが関わるオープン標準では、詳細より明快さが優先されます。

2. Codex向けの個人グローバル設定

OpenAI Codex AGENTS.md ガイドは、グローバルファイルの設計指針を示しています。

# ~/.codex/AGENTS.md（グローバル）

## 個人スタンダード

- TypeScript strictモードをすべての新規プロジェクトに適用
- エクスポートする関数には必ず戻り値の型を明示
- エラー処理: 例外よりExplicitエラーを優先
- パッケージマネージャー: プロジェクトのlockfileに合わせる

## テスト

- パブリック関数はすべてテストを書く
- プロジェクト既存のテストランナーを使う。新規導入しない
- テスト名: "should [動作] when [条件]"

ポイントは、グローバルファイルには「個人の好み」を、プロジェクト固有の情報はリポジトリ側に置くという分離です。

3. TypeScriptモノレポ（Eコマース）

YourNextStore AGENTS.mdはNext.js App Router + SDK構成の書き方を示しています。

# AGENTS.md

Your Next Store -- Next.js App Router + Commerce Kit SDKで構築したECアプリ。

## Commands

bun dev           # 開発サーバー（ポート3000）
bun run build     # 本番ビルド
bun run lint      # Biome lint（--writeで自動修正）
bun test          # テスト実行（bun:test）
tsgo --noEmit     # 型チェック

## 重要ファイル

app/              # ページ・レイアウト・Server Actions
components/ui/    # Shadcnコンポーネント（50+）
lib/commerce.ts   # Commerce APIクライアント（API呼び出しは必ずここ経由）

## ルール

- `bun`を使用。npmやyarnは使わない
- デフォルトはServer Components。クライアント操作が必要な場合のみ'use client'

4. Turborepoモノレポ

Turborepo AGENTS.mdはクロスパッケージルールの書き方の参考になります。

# AGENTS.md

## モノレポ構造

apps/
  web/          # Next.jsフロントエンド
  api/          # Express APIサーバー
packages/
  ui/           # 共有Reactコンポーネント
  config/       # 共有ESLint・TypeScript設定

## ルール

- apps/からpackages/へのインポート禁止
- 共有コードはすべてpackages/に置く
- 内部パッケージはworkspaceプロトコルで参照: `"@repo/ui": "workspace:*"`
- packages/の変更はすべてのappのテストを通過すること

## コマンド

turbo dev     # 全アプリを並列起動
turbo build   # 全パッケージ・アプリをビルド
turbo test    # 全テスト実行

5. 28エージェント構成のマルチエージェント設定

Everything Claude Code AGENTS.mdはエンタープライズ級のマルチエージェント設定です。

# AGENTS.md

## コアプリンシプル

1. エージェントファースト — ドメインタスクは専門エージェントに委譲
2. テストファースト — 実装前にテスト、カバレッジ80%以上
3. セキュリティファースト — セキュリティは絶対に妥協しない
4. 計画してから実行 — 複雑な機能は先にアーキテクチャレビューを実施

## エージェント委譲ルール

- セキュリティタスク → security-auditorエージェントを呼び出す
- テスト生成 → test-generatorエージェントを呼び出す
- デプロイ前 → 必ずpre-deploy-checkerの後にdeployerを実行

AGENTS.md vs CLAUDE.md vs .cursorrules の使い分け

	AGENTS.md	CLAUDE.md	.cursorrules
主な対応ツール	Codex、マルチツール	Claude Code	Cursor
性質	ユニバーサルオープン標準	Claude専用	Cursor専用
ファイル階層	マルチレベル	マルチレベル（インポートあり）	単一ファイル
上書き機構	AGENTS.override.md	ローカルファイル	なし
サイズ制限	32KiB（設定変更可）	制限なし	コンテキスト依存
サブエージェント定義	対応	対応	非対応

AGENTS.mdを選ぶとき: Codexを使っている、または複数のAIツールで共通の指示ファイルを使いたい場合。今後チームが採用するツールが何であれ読まれる可能性が最も高いフォーマットです。

CLAUDE.mdを選ぶとき: Claude Codeを専用で使い、フック統合・ツール制限・インポートシステムなどClaude固有の機能を使いたい場合。

両方使う: CodexとClaude Codeを併用するチームでは、AGENTS.mdが共通レイヤー（コマンド・規約・構造）、CLAUDE.mdがClaude固有の設定（フック・メモリ・ツール制限）を担うパターンが一般的です。2つのファイル間に重複があるのは想定内で、問題ありません。

詳細はAGENTS.md vs CLAUDE.md 比較ガイドで解説しています。

よくある間違い

グローバルファイルにすべてを書いてしまう

~/.codex/AGENTS.mdはすべてのプロジェクトに適用される個人設定を置く場所です。プロジェクト固有のコマンドやディレクトリ構造を書いてはいけません。全プロジェクトでノイズになり、プロジェクト側のAGENTS.mdと競合する原因になります。

グローバルファイルが大きすぎて32KiB制限に引っかかる

グローバルの~/.codex/AGENTS.mdの1バイトは、プロジェクトレベルのファイルが使える容量の1バイト減です。グローバルファイルが20KBあると、深いネストにあるプロジェクトファイルが切り捨てられます。グローバルファイルは100行以内を目安にします。

AGENTS.override.mdが「追加」ではなく「置き換え」だと知らない

変更したい行だけAGENTS.override.mdに書いて残りは引き継がれると思っているケースが多いですが、動作しません。同レベルのAGENTS.mdを丸ごと置き換えます。部分的な変更をしたいなら通常のAGENTS.md（上位ファイルと連結される）を使います。

曖昧な制約しか書かない

# 悪い例
既存の機能を壊さないこと。

# 良い例
lib/auth.tsを変更する前に`npm run test:auth`を実行し、
すべてのテストが通過していることを確認すること。
認証テストの失敗はすべてのマージをブロックする。

悪い例はCodexがすでに知っていることしか言っていません。良い例は具体的なアクション、対象ファイル、明確な条件を示しています。

Codexが実際に読んでいる内容を確認していない

AGENTS.mdの設定後、Codexに現在のインストラクションのサマリーを求めて動作確認できます。

codex --ask-for-approval never "Summarize the instructions you have loaded for this session"

重要な指示が含まれていなければ、サイズ制限かパスの問題です。

モノレポでの構成方法

モノレポは階層型AGENTS.mdの恩恵が最も大きいケースですが、設定ミスも起きやすいです。

ルートAGENTS.md: 全パッケージ共通のコマンドと規約

# AGENTS.md（ルート）

## ワークスペースルール

- パッケージマネージャー: pnpmワークスペース（npmやyarnは使わない）
- 内部パッケージはworkspaceプロトコルで参照: `"@acme/utils": "workspace:*"`
- アプリ間のインポート禁止
- すべてのPRは影響パッケージのテスト通過が必須

## コマンド（リポジトリルートから）

- インストール: `pnpm install`
- 全ビルド: `pnpm build --recursive`
- 全テスト: `pnpm test --recursive`
- Lint: `pnpm lint`

パッケージ固有のAGENTS.md: ルートを拡張する形でパッケージ特有の情報を追記

# packages/api/AGENTS.md

## APIパッケージ

Express + TypeScript REST API。PrismaでPostgreSQLに接続。

## コマンド（packages/api/から実行）

- 起動: `pnpm dev`
- テスト: `pnpm test`
- マイグレーション: `pnpm prisma migrate dev`
- 型生成: `pnpm prisma generate`

## 規約

- ルートはsrc/routes/（リソースごとに1ファイル）
- ビジネスロジックはsrc/services/（ルートに書かない）
- DBアクセスはsrc/repositories/のみ
- 環境変数はsrc/config.tsを通じてアクセス

パッケージ固有のAGENTS.override.md: ルートの規約を拡張ではなく置き換えたい場合のみ使用

# packages/mobile/AGENTS.override.md

## モバイルパッケージ（React Native）

このパッケージはモノレポの他のパッケージと異なる規約を持つ。
ルートのAGENTS.mdのWeb向けルールはここでは適用しない。

## コマンド

- 起動: `pnpm react-native start`
- iOS: `pnpm react-native run-ios`
- Android: `pnpm react-native run-android`

セットアップのクイックスタート

新規プロジェクトにAGENTS.mdを初めて追加する際の最小テンプレートです。

# AGENTS.md

## Project

[このプロジェクトが何をするものか、1文で]

## Commands

- Install: [コマンド]
- Build: [コマンド]
- Test: [コマンド]
- Lint: [コマンド]
- Start: [コマンド]

## Project Structure

[主要ディレクトリの一覧と各1行の説明]

## Conventions

- [最重要な規約1]
- [最重要な規約2]
- [最重要な規約3]

## Boundaries

- [明示的な指示なしにCodexが変更してはいけないもの]
- [保護すべきファイルやディレクトリ]

このテンプレートから始め、Codexが間違いを犯した際に「適切な指示があれば防げた」と感じた内容を都度追記する形が最適です。最良のAGENTS.mdは一度に書かれたものではなく、実際の失敗から学んで育っていきます。

ルールギャラリーでは実際のリポジトリから収集したAGENTS.mdを随時更新しています。特定のプロジェクト構成でどのようなAGENTS.mdが書かれているか確認したい場合はギャラリーをご覧ください。