AGENTS.md設定ガイド：Codex CLIへの永続的な指示の書き方

この章の要点

AGENTS.md は Codex CLI にセッションをまたいで有効な指示を与えるためのファイルで、Claude Code の CLAUDE.md に相当します。

• グローバル（~/.codex/AGENTS.md）とプロジェクト（リポジトリ内）の 2 スコープ
• リポジトリルートから現在ディレクトリまでの各 AGENTS.md が自動マージされる
• 同ディレクトリに AGENTS.override.md があると同階層の AGENTS.md は読み込まれない
• config.toml の project_doc_fallback_filenames / project_doc_max_bytes でファイル名と最大サイズを変更できる

---

AGENTS.md とは

Codex は起動時に AGENTS.md を読み込み、開発環境のセットアップやコーディング規約・禁止事項などの「永続的な指示」をプロンプト先頭に組み込みます。手作業で毎回貼り付ける必要がなく、リポジトリに置けばチーム全員で共有できます。

---

読み込み優先順位

公式ドキュメントでは 2 段階の検索が定義されています。

段階 1：グローバル

~/.codex/ 配下を 1 ファイルだけ採用します。

1. ~/.codex/AGENTS.override.md（あれば）
2. なければ ~/.codex/AGENTS.md

AGENTS.override.md を置くと、グローバル設定を一時的に丸ごと差し替えできます。

段階 2：プロジェクト

リポジトリルート（通常は Git ルート）から現在ディレクトリへ向かって下降し、ディレクトリごとに次の順で 1 ファイルだけ拾います。

1. そのディレクトリの AGENTS.override.md
2. なければ AGENTS.md
3. なければ project_doc_fallback_filenames で指定した代替ファイル

ルート寄りのファイルが先、現在ディレクトリのファイルが後に連結されるため、下（具体的）が上（一般）を上書きする形になります。空ファイルはスキップされ、合計サイズが上限に達した時点で取り込みが停止します。

読み込み順（上から順に結合）:

1. ~/.codex/AGENTS.override.md または ~/.codex/AGENTS.md（グローバル）
2. リポジトリルートの AGENTS.md
3. 中間サブディレクトリの AGENTS.md（あれば）
4. 現在ディレクトリの AGENTS.md（最優先）

具体例:

プロジェクトルート/
├── AGENTS.md            ← ルートのルール
├── services/
│   ├── AGENTS.md        ← services/ 配下で追加読込
│   └── payments/
│       └── AGENTS.override.md  ← payments/ で上位を打ち消す
└── frontend/
    └── AGENTS.md        ← frontend/ 配下で追加読込

---

使い方

基本的な AGENTS.md

# プロジェクト名 AGENTS.md

## 開発環境のセットアップ
- Node.js 20.x を使用
- パッケージマネージャーは pnpm（npm や yarn は使わない）
- 開発サーバー: `pnpm dev`（port 3000）
- テスト: `pnpm test`
- ビルド: `pnpm build`

## コーディング規約
- TypeScript strict モードを使用
- `any` 型は禁止（`unknown` を使う）
- 空の catch を使わない
- コミットメッセージは Conventional Commits 形式（日本語）

## 重要な制約
- `main` ブランチへの直接コミットは禁止
- テストなしの実装コミットは禁止
- `.env` の内容をコードにハードコードしない

## アーキテクチャの注意点
- `UserService` と `AuthService` は循環依存に注意
- soft delete: `users.deleted_at IS NULL` のレコードのみアクティブ
- キャッシュは Redis（TTL: 300 秒）を使用

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

全プロジェクト共通のスタイルや好みを記述します。

# ~/.codex/AGENTS.md

## 共通の作業スタイル
- 変更前に必ず計画を説明してから実行する
- 大きな変更は小さな単位に分割する
- 不確かな場合は確認を求める

## 出力の好み
- 説明は日本語で行う
- コードとコメントは英語で書く
- 長い説明より短い箇条書きを好む

## セキュリティ
- シークレット・API キーをコードやログに出力しない
- 外部 URL へのリクエストは確認を求める

AGENTS.override.md による置換

通常の AGENTS.md は上位とマージされますが、同ディレクトリに AGENTS.override.md を置くと、そのディレクトリでは AGENTS.md の代わりに AGENTS.override.md が採用されます。グローバルスコープでも同じルールが適用されます。

# services/payments/AGENTS.override.md

## 支払いサービス固有のルール
- テストは `make test-payments` を使う（`pnpm test` ではない）
- DB マイグレーションは DBA レビュー必須。実行前に確認を求める
- 外部 API（Stripe・PayPal）への呼び出しは staging 環境のみ
- PCI DSS 準拠のため、カード情報のメモリ保持を最小化する

注：ここで「上書き」されるのはそのディレクトリの AGENTS.md だけです。上位ディレクトリ（リポジトリルートやグローバル）の AGENTS.md は引き続き読み込まれます。上位スコープを丸ごと無効化する手段は公式ドキュメントには記載がないため、ルール衝突は内容側で吸収するのが安全です。

サブディレクトリ別の例

# frontend/AGENTS.md

## フロントエンド固有のルール
- React 19 を使用。クラスコンポーネントは使わない
- スタイリングは Tailwind CSS のみ（インライン styles は禁止）
- テストは `@testing-library/react`
- E2E は Playwright（Cypress は使わない）

## コンポーネント設計
- ファイル名: PascalCase（例: `UserProfile.tsx`）
- Props は明示的な型引数で渡す
- 再利用可能なコンポーネントは `components/ui/` に置く

# services/notification/AGENTS.md

## 通知サービスのルール
- テストコマンド: `make test-notification`
- メール送信は staging SMTP のみ（本番への誤送信防止）
- Slack 通知は `#notifications-test` チャンネルのみ
- プッシュ通知は FCM sandbox 環境のみ

config.toml での挙動カスタマイズ

# ~/.codex/config.toml

# AGENTS.md が無い場合のフォールバックファイル名（配列で複数指定可）
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# 取り込む合計サイズの上限（バイト、デフォルト 32 KiB）
project_doc_max_bytes = 65536

CODEX_HOME 環境変数でグローバル設定の場所を変更できます。

CODEX_HOME=$(pwd)/.codex codex exec "現在の指示ソースを列挙して"

どのファイルが効いているか確認する

Codex に直接尋ねると要約して返してくれます。

codex --ask-for-approval never "Summarize the current instructions."
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

---

ベストプラクティス

テストコマンドを明記する Codex は「テストを実行して確認する」挙動をとりやすく、コマンドが誤っていると誤った合格レポートが出ます。

## テストの実行方法
- ユニットテスト: `pnpm test:unit`（全テスト: `pnpm test`）
- E2E（ローカル）: `pnpm test:e2e`（Playwright）
- 型チェック: `pnpm typecheck`

「やらないこと」を明示する

## 禁止事項
- `console.log` をコミットに含めない
- `TODO:` コメントを残さない（Issue を作って削除する）
- 動作するコードを理由なくリファクタしない
- テストなしで機能追加をコミットしない

CI 環境向けの差分を書く

## CI 環境での注意
- CI では `pnpm install --frozen-lockfile`
- テスト前に `make db:reset:test` でリセット
- E2E は `pnpm test:e2e:ci`（headless モード）

openai/codex 自身の AGENTS.md も参考になる 公式リポジトリの AGENTS.md には Rust/TUI コーディング規約・テスト方針・スナップショット必須化・特定環境変数の改変禁止など、踏み込んだ運用例が記載されています。

---

AGENTS.md vs CLAUDE.md の比較

観点	AGENTS.md（Codex）	CLAUDE.md（Claude Code）
フォーマット	プレーン Markdown	Markdown + frontmatter（path-scoped rules）
階層構造	リポジトリルートから現在ディレクトリまで自動マージ	個人/プロジェクト/ローカルの複数スコープ
上書き機能	同ディレクトリの AGENTS.override.md で AGENTS.md を差し替え	下位スコープが上位を上書き
インポート	なし	@path/to/file でファイルインポート可能
代替ファイル名	project_doc_fallback_filenames で指定可能	変更不可（CLAUDE.md 固定）
自動学習	なし	Auto Memory（MEMORY.md）で蓄積
スコープ制限	ディレクトリベース	paths frontmatter でファイルパターン指定

---

注意点・セキュリティ観点

取り込みサイズの上限を超えると後続が無視される デフォルトの 32 KiB を超えると以降の AGENTS.md は読み込まれません。サブディレクトリのルールが反映されない場合は project_doc_max_bytes を引き上げるか、ファイルを軽量化してください。

AGENTS.override.md は「同階層 AGENTS.md の代替」 上位スコープを丸ごと無効化するわけではありません。誤解を防ぐため、挙動をチーム内で共有しておくと安全です。

機密情報を AGENTS.md に書かない AGENTS.md はリポジトリにコミットされることを前提としています。API キーや本番接続情報は .env などに分離し、AGENTS.md には参照ルールのみ記述してください。

他ツール互換ファイル名は自動採用されない CLAUDE.md や .cursorrules など他ツール由来のファイルは、明示的に project_doc_fallback_filenames へ追加しない限り Codex は読み込みません。

---

一次ソース

• Custom instructions with AGENTS.md — Codex Docs
• Configuration reference — Codex Docs
• openai/codex リポジトリの AGENTS.md（実例）