Codex AGENTS.md｜書き方・置き場所と優先順位【2026年9月】

結論: Codex の AGENTS.md は「1 ディレクトリにつき最大 1 ファイル」を、リポジトリのルートから今いるディレクトリへ向かって順に連結して読み込みます。あとから連結された下層のファイルが上層を上書きし、合計が 32 KiB（project_doc_max_bytes の既定値）に達した時点で打ち切られます。つまり「どこに置くか」で効き方が決まるファイルです。

2026年9月28日時点のスナップショット: Codex CLI の最新は 0.157.1（2026年9月26日公開）。公式ドキュメントの URL は developers.openai.com/codex/guides/agents-md から learn.chatgpt.com/docs/agent-configuration/agents-md へ HTTP 308 で転送されます（2026年9月28日に curl で確認）。AGENTS.md 自体は Linux Foundation 傘下の Agentic AI Foundation が管理するオープン仕様で、公式サイトによると 6万を超えるオープンソースリポジトリが採用しています。

この記事の要点:

• 読み込み順は「グローバル（~/.codex）→ プロジェクトルート → 下層ディレクトリ」。同じ階層では AGENTS.override.md が AGENTS.md より先に選ばれ、1 ディレクトリにつき 1 ファイルだけが採用されます（参照: Custom instructions with AGENTS.md｜ChatGPT Learn、参照日: 2026-09-28）
• 目的別に 7 パターンへ分けて書くと、何を書けばいいか迷わなくなる。コピペできる完成形テンプレも 5 種そのまま置いています
• 「このコマンドを実行してよいか」は AGENTS.md では決まりません。サンドボックス外で動かすコマンドの許可・確認・禁止は、2026年9月28日時点で .rules（Starlark の prefix_rule()・実験的機能）の担当です

対象読者: Codex CLI・Codex IDE 拡張・ChatGPT デスクトップアプリで開発しているエンジニア、テックリード、社内でAIコーディングのルールを決める立場の方

今日やること: リポジトリのルートで /init を実行して AGENTS.md の雛形を作り、テスト実行コマンドと禁止事項だけ先に埋めてコミットする

「AIに毎回同じ説明をしている」——AGENTS.md が話題になる理由は、だいたいこれに集約されます。

コーディング規約、テストの走らせ方、コミットメッセージの形式。セッションを開くたびに同じ前提を貼り直していると、本題に入る前に毎回コンテキストを食われます。AGENTS.md は、その繰り返しを「プロジェクトの指示書」としてファイルに固定しておくためのものです。Codex は作業を始める前に必ずこのファイルを読むので、初対面のAIではなく「うちのルールを知っているAI」として動き出します。

ただし 2026年後半の Codex は、AGENTS.md だけで完結する構成ではなくなりました。.rules（コマンド許可）、SKILL.md（条件付き手順書）、~/.codex/agents/（カスタムサブエージェント）が別ファイルとして分離し、AGENTS.md は「常時読まれる文脈と規約」に役割が絞られています。ここを混ぜて書くと「書いたのに効かない」が起きます。

この記事では、2026年9月28日にCodex CLIの公式ドキュメントから当日取得した仕様をもとに、置き場所と優先順位、7パターンの書き方、コピペ用テンプレ5種、単数形 AGENT.md からの移行、そして「AGENTS.md に書いても効かないこと」までを整理します。旧 URL の資料しか見つからず困っている方向けに、公式ページの現在地もまとめました。

なお、AGENTS.md がどのツールで読まれるのか（Claude Code が読まない理由を含む）はAGENTS.mdとは｜対応23ツールとClaude Codeが読む条件、標準としての位置づけはAAIF完全解説記事にまとめています。この記事は「Codex での実際の書き方と運用」に絞ります。

Codex AGENTS.mdとは｜公式の定義と3つの役割

AGENTS.md は Git リポジトリに置く Markdown ファイルで、公式サイトの言葉を借りれば「エージェントのための README」です。README.md が人間の貢献者向けなら、AGENTS.md はコーディングエージェント向け。ビルド手順、テストコマンド、規約といった「README に書くとうるさいが、エージェントには毎回必要な情報」を置く場所として、意図的に別ファイルに分けられています。

📊 Codex完全リファレンス: 機能網羅マトリクス・利用形態の判断フローはCodex完全リファレンス（ピラー版）へ。

まず、Codex 周辺で役割が近い 6 つのファイルを整理しておきます。これを分けておかないと、AGENTS.md に何を書くべきかが決まりません。

そのうえで、AGENTS.md が実務で効くのは次の 3 つの役割です。

役割1: コーディング規約の自動適用

インデント、命名規則、型ヒントの有無、コメントの書式を AGENTS.md に書いておくと、エージェントは最初から「このプロジェクトの文法」で書き始めます。レビューがスタイル指摘で埋まらなくなるぶん、差分の中身の議論に時間を回せます。公式サイトの FAQ でも「必須フィールドはない。標準的な Markdown なので好きな見出しを使ってよい」と明記されているので、書式より中身を優先して構いません。

役割2: テスト・CIコマンドの共有

「どのコマンドでテストが走るか」を書いておくと、エージェントはコードを書いたあとに自分で検証まで進めます。公式 FAQ には「AGENTS.md に列挙したテストコマンドは、エージェントが関連するプログラム的チェックとして実行を試み、失敗を直してからタスクを終える」と書かれています。逆に言えば、書いていないコマンドは走りません。ここを空欄にしたまま「テストして」と頼むのが、いちばんもったいない使い方です。

役割3: 禁止事項とチーム慣習の明文化

「このライブラリは使わない」「マイグレーションは手で書かない」といったチーム固有の約束は、口頭伝承になりがちです。AGENTS.md に落としておくと、エージェントへの制約であると同時に、新しく入ったメンバーへの説明資料としても機能します。ただし後述のとおり、「本番へ push させない」のようなコマンドレベルの禁止は AGENTS.md では強制できません。そこは .rules の担当です。

AGENTS.mdの置き場所と優先順位｜ルートから現在地へ下る3層

AGENTS.md でいちばん誤解が多いのが探索の向きです。公式ドキュメント（2026-09-28 取得）は「Codex は起動時に instruction chain を組み立てる。実行ごとに 1 回、TUI ではセッション起動ごとに 1 回」と書いたうえで、プロジェクトルートから現在の作業ディレクトリへ向かって「下る」と明記しています。現在地から親へ遡るのではありません。

公式の precedence order を、そのまま順番に並べるとこうなります。

「下層が優先される」のは、下層が後ろに連結されるからです。公式ドキュメントの表現は “Files closer to your current directory override earlier guidance because they appear later in the combined prompt.”。上書きの仕組みが特別に実装されているわけではなく、単に後勝ちです。だから「差分だけ書く」のが正しい書き方になります。

グローバル（~/.codex/AGENTS.md）に書くもの

mkdir -p ~/.codex

# ~/.codex/AGENTS.md
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

全プロジェクトに効かせたい個人の作法（使うパッケージマネージャ、確認を取ってほしい操作など）を置きます。チームの決まりではなく、自分のデフォルトです。一時的に丸ごと差し替えたいときだけ ~/.codex/AGENTS.override.md を作り、戻すときは削除します。

プロジェクトルートに書くもの

# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

いちばんよく使う置き場所です。README.md と同じ階層に置き、チーム全員に効かせたい規約・テスト方針・PR 手順を書きます。

サブディレクトリに書くもの

# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

モノレポで、サービスごとにルールが違うときに使います。AGENTS.override.md を置くと、同じディレクトリの AGENTS.md は読まれません（上の階層の内容は残ります）。公式ドキュメントのサンプルツリーでも services/payments/AGENTS.md は “Ignored because an override exists” と注記されています。

読み込み順を自分の目で確かめる

推測で運用しないための確認コマンドが公式に用意されています。

# ルートで、いま効いている指示を列挙させる
codex --ask-for-approval never "Summarize the current instructions."

# サブディレクトリ側の上書きが効いているか確認する
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

# 読み込んだファイルをログで監査する
codex -c log_dir=./.codex-log
# → ./.codex-log/codex-tui.log を確認

公式ドキュメントは「指示が古いままに見えたら、対象ディレクトリで Codex を再起動する。instruction chain は実行のたびに組み直されるので、手で消すキャッシュはない」と書いています。キャッシュ削除の手順を探す必要はありません。

上限（32 KiB）と別名ファイルの設定

合計サイズの上限と、AGENTS.md 以外の名前を読ませる設定は ~/.codex/config.toml で変えられます。2026年9月28日時点の公式 Config Reference に実在するキーは次のとおりです。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

この設定を入れると、各ディレクトリの探索順は AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md になります。この一覧に無いファイル名は、指示探索の対象になりません。config.toml の書き方そのものはCodex MCPの設定と使い方｜config.tomlの例でも実例を載せています。

Codexの公式ドキュメント（project instructions）は今どこにある？

「codex agents.md instructions」で検索して developers.openai.com の記事にたどり着き、リンクが転送されて迷う——という相談が増えています。結論から言うと、2026年9月28日時点で Codex のドキュメントは learn.chatgpt.com 配下に移っており、旧 URL は HTTP 308（恒久的リダイレクト）で転送されます。内容が消えたわけではありません。移転日については、2026年9月28日時点で公式に記載が見つかりませんでした。

移転後のドキュメントで、原文を読みに行く価値がある箇所を 4 つだけ挙げておきます。

1. Custom instructions with AGENTS.md — 探索順（instruction chain）とトラブルシュート 5 項目が載っている本体。AGENTS.override.md の扱いと “at most one file per directory” の原文はここです
2. Advanced Config の「Project instructions discovery」 — project_doc_max_bytes と project_doc_fallback_filenames の 2 つが「指示の読み込みを制御する 2 つのつまみ」だと説明されている節
3. Config Reference — 設定キーの正典。ここに載っていないキーは書いても効きません
4. Rules — サンドボックス外のコマンド可否を決める .rules の仕様（実験的機能）。AGENTS.md と混同されやすい部分です

なお、ドキュメントは末尾に .md を付けると Markdown 版が取得できます（例: https://learn.chatgpt.com/docs/agent-configuration/agents-md.md）。AGENTS.md の原文を社内Wikiへ引用したいときは、この形が扱いやすいです。全体の索引は llms.txt に置かれています。

AGENTS.mdの書き方｜目的別7パターンのテンプレ

AGENTS.md は自由書式です。公式サイトの FAQ も「必須フィールドはない」と明言しています。ただし自由すぎると手が止まるので、目的別に 7 パターンへ分けて考えるのが早道です。全部を最初から埋める必要はありません。パターン1・3・5 の 3 つだけ書けば、実用上の効果はほぼ出ます。

パターン1: 基本情報セクション（すべてのAGENTS.mdに必須）

プロジェクトの概要、主要技術スタック、ディレクトリ構造を伝えるセクション。「どんなプロジェクトか」を最初に宣言します。バージョン番号は自分のリポジトリの実値に置き換えてください。

# プロジェクト概要

## 基本情報
- プロジェクト名: [プロジェクト名]
- 主要言語: Python / TypeScript
- フレームワーク: FastAPI / Next.js (App Router)
- パッケージマネージャ: uv (Python) / pnpm (Node)

## ディレクトリ構造
```
src/
  api/       # FastAPI エンドポイント
  services/  # ビジネスロジック
  models/    # Pydanticモデル
tests/       # pytest テスト
frontend/    # Next.js アプリ
```

## このプロジェクトで絶対にやらないこと
- 本番DBへのdirect SQL実行
- `.env` ファイルのGitコミット
- `main` ブランチへの直接push

パターン2: コーディング規約セクション

命名規則、インデント、コメントのスタイルを明文化します。これがあると、エージェントが書くコードのスタイルが既存コードと揃います。ここをサボると、レビューがスタイル指摘だけで埋まります。

## コーディング規約

### Python
- スタイル: PEP 8 準拠、フォーマッタは ruff format
- 型ヒント: すべての関数に必須（戻り値含む）
- docstring: Google スタイル
- 変数名: snake_case、定数は UPPER_SNAKE_CASE

### TypeScript
- スタイル: Prettier 設定に従う
- 型: any は使わない。unknown か具体的な型を使う
- import: named import を優先、default export は避ける
- コンポーネント: 関数コンポーネントのみ

### 共通
- ハードコードされたシークレット・URLは禁止
- TODO コメントには必ず担当者と期限を書く
  例: `# TODO(yamada): 2026-12-01までにリファクタ`

パターン3: テスト規約セクション

どのテストフレームワークを使うか、実行コマンド、カバレッジ目標を書きます。公式 FAQ の「列挙したテストコマンドはエージェントが実行を試みる」という挙動を引き出すのが、このセクションの役目です。

## テスト

### 実行コマンド
```bash
# バックエンド
uv run pytest tests/ -v --cov=src --cov-report=term-missing

# フロントエンド
pnpm test --coverage
```

### テストの原則
- 新機能には必ず単体テストを書く
- テストファイルは `test_` プレフィックスで命名
- モックは `pytest-mock` を使う（`unittest.mock` 直接は避ける）
- カバレッジ目標: 80%以上
- E2Eテストは `tests/e2e/` ディレクトリに分離

### CIが見ていること
- lintエラーが0件であること
- テストが全件パスすること
- カバレッジが80%を下回らないこと

パターン4: PR・コードレビュー規約セクション

PR のタイトル規則、説明文のテンプレ、レビュー観点を伝えます。2026年9月28日時点の公式ドキュメントには、GitHub 上の Codex コードレビュー向けに ## Code Review Rules という決まった見出しが用意されています。リポジトリ全体の観点はルートの AGENTS.md に、サービス固有の観点は下層の AGENTS.md に置くのが公式の推奨です。書式や lint の指摘は CI に任せ、この節には「振る舞いとして止めたいこと」だけを書きます。

## PRルール

### コミットメッセージ
Angular Commit Convention に従う:
- `feat:` 新機能
- `fix:` バグ修正
- `refactor:` リファクタリング
- `docs:` ドキュメント
- `test:` テスト追加・修正
- `chore:` ビルド・設定変更

例: `feat(auth): JWTトークンの有効期限を設定可能にする`

### PR説明文のフォーマット
```
## 変更内容
（何を変えたか、なぜ変えたかを3行以内で）

## テスト方法
（どうテストしたか）
```

## Code Review Rules

### 実験の集計
- 処置群の比較を、露出後の行動（コンバージョンや継続率）で絞り込まない。
  安全な書き方: 割付または露出でコホートを作り、コンバージョンは結果として報告する。

PR レビューを自動化するところまで進めるなら、Codex GitHub Actionの使い方｜PRレビュー自動化もあわせて設計してください。

パターン5: セキュリティ・禁止事項セクション

触られたくない領域を明示します。ただし後述のとおり、これは「お願い」であって強制ではありません。実行そのものを止めたいコマンドは .rules 側に書きます。

## セキュリティと禁止事項

### 絶対禁止
- API キー・パスワード・トークンのハードコード
- `eval()` / `exec()` の使用（動的コード実行）
- SQLの文字列連結（必ずパラメータ化クエリを使う）
- ユーザー入力をそのままログに出力（個人情報の漏洩リスク）
- 本番環境のシークレットをローカルの `.env` にコピー

### 機密情報の扱い
- シークレットは必ず環境変数経由
- `.env` ファイルは `.gitignore` に含める
- ログには個人情報（メール、電話番号、IPアドレス）を出力しない

### 依存関係の追加
- 新しいライブラリを追加する前に `SECURITY.md` を確認
- 既知の脆弱性があるバージョンは使わない

パターン6: 外部サービス・API連携セクション

外部APIやサードパーティサービスとの接続方法を伝えます。「APIの呼び方が違う」という手戻りを防げます。

## 外部サービス連携

### 使用サービス
- データベース: PostgreSQL（接続: `DATABASE_URL` 環境変数）
- キャッシュ: Redis（接続: `REDIS_URL` 環境変数）
- ファイルストレージ: AWS S3（`boto3` 経由）
- メール送信: SendGrid（`sendgrid-python` 経由）

### 開発環境での注意
- ローカルでは Docker Compose で PostgreSQL と Redis を起動
- S3の操作は `MinIO` で代替（`AWS_ENDPOINT_URL=http://localhost:9000`）
- メール送信は SendGrid の sandbox モードを使う

### テスト時
- 外部APIは必ずモックする（`responses` または `httpx.MockTransport`）
- 実際のAPIを叩くテストは `@pytest.mark.integration` でマークし、CIでは除外

パターン7: モノレポ・サブディレクトリ用セクション

サブディレクトリの AGENTS.md には、上位との差分だけを書きます。上位の内容は連結されて残っているので、全部書き直す必要はありません。

# 決済サービス固有ルール（services/payments/AGENTS.md）
# ルートの AGENTS.md に対する差分だけを書く

## セキュリティ強化ルール（決済サービス固有）
- カード番号は絶対にアプリ内で保持しない（決済代行へ直接送信）
- 金額計算は必ず `Decimal` 型（浮動小数点NG）
- 決済ログには必ず transaction_id を含める

## テスト要件（ルートの80%を上書き）
- 単体テストカバレッジ: 95%以上
- 境界値テスト必須: 金額0円、上限額、マイナス値

## 使用禁止ライブラリ
- 未監査の決済ライブラリ全般（必ずPCI DSS準拠を確認）

コピペ用AGENTS.mdテンプレ5種

「書き方はわかったけど、ゼロから書くのは面倒」という場合のために、用途別の完成形を置いておきます。[] 内を自分のプロジェクトの値に書き換えてください。バージョン番号も同様です。

テンプレ1: フルスタックWebアプリ（汎用・最もよく使う）

# AGENTS.md — [プロジェクト名]

## プロジェクト概要
[プロジェクトの1行説明]

## 技術スタック
- バックエンド: Python + FastAPI
- フロントエンド: TypeScript + Next.js (App Router) + Tailwind CSS
- DB: PostgreSQL
- インフラ: AWS (ECS + RDS)

## 作業の進め方
1. 何を変えるか、なぜ変えるかを最初に短く説明する
2. 変更はできるだけ小さな単位に分ける
3. テストが通ることを確認してから次に進む
4. 不明な点があれば作業前に確認する

## コーディング規約
- Python: PEP 8 + ruff format + ruff check
- TypeScript: Prettier + ESLint（設定ファイル参照）
- 型ヒント必須（Python/TypeScript共通）
- 変数名: 意味のある名前、略語は最小限に

## テスト
```bash
# バックエンド
uv run pytest tests/ -v
# フロントエンド
pnpm test
```
新機能には必ず単体テストを書く。カバレッジ目標: 80%以上。

## 禁止事項
- シークレットのハードコード
- `main` への直接push
- `any` 型の使用（TypeScript）
- SQLの文字列連結

## コミットメッセージ
Angular Convention: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`

テンプレ2: Python専用バックエンド（データ分析・API開発向け）

# AGENTS.md — [プロジェクト名] (Python Backend)

## 環境
- Python（バージョンは pyproject.toml の requires-python に従う）
- パッケージ管理: uv (`uv sync` で依存関係インストール)
- テスト: pytest + pytest-cov + pytest-mock

## テスト実行
```bash
uv run pytest tests/ -v --cov=src --cov-report=term-missing
uv run ruff check .
uv run mypy src/
```
CI でこれらが全て通ることがマージの条件。

## コーディングスタイル
- フォーマッタ: ruff format
- リンタ: ruff check
- 型チェック: mypy（strict モード）
- import 順: ruff の isort ルールに従う

## 型ヒント必須ルール
- すべての関数に引数と戻り値の型を書く
- `Optional[str]` より `str | None` を使う
- `Any` は原則禁止（どうしても必要な場合はコメントで理由を書く）

## NG パターン
- `print()` デバッグ（`logging` モジュールを使う）
- Bare `except:` 句（必ず例外クラスを指定）
- 可変デフォルト引数（`def f(x: list = []):` はNG）

テンプレ3: フロントエンド専用（React/Next.js向け）

# AGENTS.md — [プロジェクト名] (Frontend)

## 環境
- Node.js（バージョンは .nvmrc に従う）
- パッケージマネージャ: pnpm
- フレームワーク: Next.js (App Router)
- スタイリング: Tailwind CSS + shadcn/ui

## コマンド
```bash
pnpm dev           # 開発サーバー
pnpm build         # 本番ビルド
pnpm test          # テスト
pnpm lint          # ESLint
pnpm type-check    # TypeScript型チェック
```

## コンポーネント規約
- 関数コンポーネントのみ
- Props の型は `interface` で定義、`type` は型エイリアスに使う
- `use client` は最小限に（Server Component を優先）
- ファイル名: PascalCase（コンポーネント）、camelCase（ユーティリティ）

## 状態管理
- ローカル状態: `useState` / `useReducer`
- グローバル状態: Zustand（`/stores/` ディレクトリ）
- サーバー状態: React Query（`/hooks/` ディレクトリ）
- フォーム: React Hook Form + Zod

## 禁止
- `useEffect` での API 直接呼び出し（React Query を使う）
- `style={{}}` 直書き（Tailwind クラスを使う）
- `any` 型（ESLint でエラーになるよう設定済み）

テンプレ4: モノレポ向け（ルートレベル）

# AGENTS.md — [モノレポ名]（ルート）

## リポジトリ構造
```
packages/
  api/        # バックエンド（→ packages/api/AGENTS.md 参照）
  web/        # フロントエンド（→ packages/web/AGENTS.md 参照）
  shared/     # 共通型・ユーティリティ
tools/
  scripts/    # ビルド・デプロイスクリプト
```

## 共通ルール（全パッケージ適用）
- TypeScript strict モード
- パッケージマネージャ: pnpm workspaces
- 各パッケージ固有のルールは、そのディレクトリの AGENTS.md に差分だけ書く

## 共通コマンド
```bash
pnpm -F @project/api test    # APIのみテスト
pnpm -F @project/web build   # フロントエンドのみビルド
pnpm test                    # 全パッケージテスト
```

## 変更時の注意
- `shared/` を変更したら依存するすべてのパッケージのテストを確認
- パッケージ間の循環依存は禁止
- 新しいパッケージを追加する場合は `pnpm-workspace.yaml` を更新

## CI/CD
- mainへのマージ → 自動デプロイ（dev環境）
- タグpush（v*.*.* 形式）→ 本番デプロイ

テンプレ5: セキュリティ重視プロジェクト向け

# AGENTS.md — [プロジェクト名]（セキュリティ重視）

## このプロジェクトについて
金融・医療・個人情報を扱うプロジェクト。セキュリティ要件が通常より厳格です。

## セキュリティ必須要件

### データ取り扱い
- 個人情報はマスクしてからログ出力（メール: `***@***.com`）
- 暗号化必須: 保存時 AES-256、通信時 TLS 1.3 以上
- DB接続は必ずSSL使用（`sslmode=require`）

### 認証・認可
- JWT の有効期限: アクセストークン15分、リフレッシュ7日
- 管理者機能へのアクセスには IP 制限と多要素認証を必須にする
- Rate limiting: エンドポイントごとに設定

### コードレビュー必須項目
1. SQLインジェクション対策（パラメータ化クエリ確認）
2. XSS対策（テンプレートエスケープ確認）
3. CSRF対策（トークン検証確認）
4. 入力バリデーション（Pydantic/Zod で必ず実施）

### テスト要件
- セキュリティテスト必須（`bandit` で静的解析）
- カバレッジ: 90%以上

### 絶対禁止
- デバッグモードでの本番起動
- エラーメッセージへのスタックトレース露出
- ユーザー入力を SQL に直接埋め込む
- パスワードの平文保存または MD5/SHA1 ハッシュ

agent.mdの書き方｜単数形AGENT.mdからAGENTS.mdへ移す手順

「agent.md 書き方」で検索して来る方が一定数います。結論は明快で、Codex が指示ファイルとして探すのは複数形の AGENTS.md です。単数形の AGENT.md は、そのままでは指示探索の対象になりません。既存の AGENT.md を使っている場合、公式サイトが案内している移行手順は 1 行です。

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

改名したうえで、旧ファイル名からシンボリックリンクを張って後方互換を残す、という形です。「他のツールが AGENT.md を見に来る」「社内の手順書が旧名で書かれている」といった事情がある場合に有効です。

シンボリックリンクを使わずに済ませたいなら、config.toml の project_doc_fallback_filenames に旧名を足す方法もあります。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENT.md"]

ただしこれは自分の Codex にしか効きません。チーム全員に効かせたいなら、リポジトリ側で複数形へ改名するほうが確実です。どちらを選ぶかは「そのリポジトリを他の人も Codex で触るか」で決めてください。

codex agents md・codex.md・AGENTS.override.md｜表記ゆれ早見表

ドットの有無、大文字小文字、旧ツールの名残。AGENTS.md 周辺はファイル名の表記ゆれが多く、「書いたのに読まれない」の相当数がここに起因します。2026年9月28日時点の公式仕様で読まれる・読まれないを整理します。

公式ドキュメントの原文は “Filenames not on this list are ignored for instruction discovery.”。つまり「それっぽい名前だから読んでくれるだろう」は成立しません。大文字小文字の扱いについては、2026年9月28日時点で公式に記載がないため、リポジトリでは公式の表記どおり AGENTS.md に揃えておくのが安全です。

なお、検索でよく見る「codex agents md」「codex agents.md」「codex.md」はいずれも同じファイルを指した表記ゆれで、実体は AGENTS.md 1 つです。Codex 全体のコマンドやファイル構成はCodexの使い方 完全ガイド｜CLI・アプリ・Cloudにまとめています。

AGENTS.mdに書いても効かないこと｜.rulesとの役割分担

ここが 2026年後半にいちばん変わった部分です。AGENTS.md に「本番へ push しない」「rm -rf を実行しない」と書いても、それはモデルへのお願いであって、実行を止める仕組みではありません。サンドボックス外で動かすコマンドの可否は、2026年9月28日時点で .rules ファイル（実験的機能）が担当します。

.rules は ~/.codex/rules/default.rules のように、有効な設定レイヤーの隣の rules/ フォルダに置きます。書式は Starlark（Python に似た構文）で、prefix_rule() でコマンドの接頭辞ごとに判定を決めます。

# ~/.codex/rules/default.rules
prefix_rule(
  pattern = ["gh", "pr", "view"],
  decision = "prompt",
  justification = "Viewing PRs is allowed with approval",
  match = [
    "gh pr view 7888",
    "gh pr view --repo openai/codex",
  ],
  not_match = [
    "gh pr --repo openai/codex view 7888",
  ],
)

decision に指定できる値と意味は次の 3 つです。複数のルールが当たった場合はいちばん厳しい判定が勝ちます（forbidden > prompt > allow）。

法人運用で効いてくるのが、bash -lc のような複合コマンドの扱いです。公式ドキュメントによると、スクリプトが「変数展開やワイルドカードを含まない素の単語」を && || ; | でつないだだけの直線的な連鎖なら、Codex は tree-sitter で分解し、1 コマンドずつルールを当てます。git add . を許可していても、git add . && rm -rf / は後半が別途評価されるので自動許可されません。逆に、リダイレクトやコマンド置換、環境変数の代入、ワイルドカードが入っているスクリプトは分解されず、["bash","-lc","<スクリプト全文>"] という 1 つの呼び出しとして判定されます。

書いたルールが意図どおりか確かめるコマンドも用意されています。

codex execpolicy check --pretty 
  --rules ~/.codex/rules/default.rules 
  -- gh pr view 7888 --json title,body,comments

運用上の注意を 3 点。(1) プロジェクト直下の <repo>/.codex/rules/ は、そのプロジェクトの .codex/ レイヤーが trusted のときだけ読まれます（projects.<path>.trust_level）。(2) TUI で「許可」を選ぶと、Codex は ~/.codex/rules/default.rules に追記します。個人の許可が静かに増えていないか、定期的に開いて確認してください。(3) 管理者は requirements.toml から制限的な prefix_rule を強制できます。全社導入では、AGENTS.md（規約）と .rules（実行可否）をセットで設計してください。

AGENTS.md 側には「なぜそれを禁止しているか」を書き、.rules 側で実際に止める。この二段構えが、2026年9月時点の Codex で現実的な形です。

Codex SkillsとSubagentsの連携｜AGENTS.mdから委譲を指示する

AGENTS.md と混同されやすいのが SKILL.md です。役割は明確に違います。

• AGENTS.md: 毎回すべてのセッションに読み込まれる「常時適用の指示」
• SKILL.md: 特定のタスクが来たときだけ起動する「条件付き手順書」

Skills の有効・無効は config.toml で切り替えられます。ここで注意したいのが path の指し先です。公式 Config Reference の定義は「SKILL.md を含むスキルフォルダへのパス」であって、SKILL.md ファイル自体ではありません。

# ~/.codex/config.toml
[[skills.config]]
path = "~/.codex/skills/code-review"   # SKILL.md を含むフォルダ
enabled = true

[[skills.config]]
path = "~/.codex/skills/security-audit"
enabled = false  # 一時的に無効化

もうひとつ、2026年版で押さえておきたいのがサブエージェントとの関係です。公式の Subagents ドキュメントには「現行のローカル Codex は、直接頼まれたとき、または該当する AGENTS.md やスキルの指示が委譲を求めているときに委譲する」と書かれています。つまり AGENTS.md に委譲の方針を書けば、毎回「並列で調べて」と打たなくても済みます。

## 調査タスクの進め方
- 3ファイル以上を横断して読む調査は、サブエージェントに分けて並列で行う
- 調査系（探索・ログ確認・テスト実行）は並列でよい
- 同じファイルを複数のエージェントが同時に編集しない
- 各サブエージェントは生ログではなく要約を返す

カスタムサブエージェント自体は AGENTS.md ではなく、~/.codex/agents/（個人用）または .codex/agents/（プロジェクト用）に TOML ファイルで定義します。必須フィールドは name / description / developer_instructions の 3 つです。設計の具体例はCodex CLIのSub-agents・自動レビューの使い方にまとめています。

AGENTS.mdとCLAUDE.mdの違い — 対比表

「AGENTS.mdとCLAUDE.mdはどっちを使えばいいのか」は定番の疑問です。答えは「役割が違うので、併用するなら分担を決める」になります。

実務的な判断基準はシンプルです。チームで Codex と Claude Code を併用しているなら、規約の本体は AGENTS.md に置き、CLAUDE.md はそれを読み込んで Claude 固有の設定だけ足す薄い層にする。二重管理を始めると、片方だけ更新されて矛盾します。Claude Code が AGENTS.md を読む条件はAGENTS.mdとは｜対応23ツールとClaude Codeが読む条件で公式ドキュメントを根拠に整理しています。

Codex CLI と Claude Code の料金・機能比較はCodex CLI vs Claude Code 料金比較ガイドをご覧ください。

5ステップ AGENTS.md 作成フロー

初めて作る場合の手順です。この順で進めると、最小限の時間で効くファイルになります。

1. /init で雛形を作る
   Codex CLI でもデスクトップアプリのコンポーザーでも、指示を置きたいディレクトリで /init を実行すると AGENTS.md の雛形が生成されます。公式ドキュメントの手順は「(1) 指示を置きたいディレクトリで /init を実行 (2) 生成された AGENTS.md を読んでリポジトリの慣習に合わせて直す」の 2 手です
2. テスト実行コマンドを最初に埋める
   最優先はここです。テストコマンドが書いてあると、エージェントは書いたコードを自分で検証してから終わります。書いていないと検証されません
3. 禁止事項リストを作る
   「してはいけないこと」を先に書くのがコツです。ポジティブな指示より、禁止事項のほうが制約として効きます。ただしコマンド実行そのものを止めたいものは .rules へ回します
4. 読み込まれているか確認する
   codex --ask-for-approval never "Summarize the current instructions." を実行し、書いた内容が引用されるか見ます。ここを飛ばすと「書いたつもり」のまま数週間過ぎます
5. 1週間使って削る
   最初から完璧を目指さないでください。1週間運用して「まだこれをやる」「この指示は効いていない」を記録し、足すより削る方向で直します

【要注意】よくある失敗パターンと回避策

AGENTS.md を入れたのに効果が薄い、というケースには共通の型があります。代表的な 4 つを挙げます。

失敗1: 長すぎて要点が埋もれる

❌ よくある間違い: 全社のコーディング規約ドキュメントをそのまま貼り付けて、1万字の AGENTS.md を作る

⭕ 正しいアプローチ: 「毎回守ってほしいこと」に絞る。網羅性より「最重要の20項目」

なぜ重要か: 上限は 32 KiB ですが、問題は上限に当たる前に起きます。長い文書のなかでは、どれが強い制約なのかが伝わりにくくなります。公式ドキュメントも、上限に達したときの対処として「project_doc_max_bytes を上げる」と並べて「ネストしたディレクトリに分割する」を挙げています。増やすのではなく、置き場所で分けるほうが素直です。

失敗2: 下層で全文を書き直してしまう

❌ よくある間違い: ルートの AGENTS.md で「型ヒントは省略可」と書き、サブディレクトリの AGENTS.override.md で規約を丸ごと書き直す

⭕ 正しいアプローチ: サブディレクトリには上位との差分だけを書き、「ルートの◯◯ルールをここでは以下に変更する」と明示する

なぜ重要か: AGENTS.override.md が無効化するのは「同じディレクトリの AGENTS.md」だけで、上位階層の内容は連結されたまま残ります。全文を書き直すと、上位の古い記述と新しい記述が両方プロンプトに乗ります。矛盾したときは後ろ（＝下層）が勝ちますが、読み手にとっては何が生きているか追えなくなります。

失敗3: シークレットや本番URLを書いてしまう

❌ よくある間違い: 「本番のDB接続URLは postgresql://user:password@prod-db.example.com/app」と書く

⭕ 正しいアプローチ: 「DB接続URLは DATABASE_URL 環境変数から読む。ローカルは docker-compose.yml を参照」と書く

なぜ重要か: AGENTS.md は Git にコミットするファイルです。接続情報や内部システムのURLを書くと、リポジトリが外に出た瞬間にそのまま漏れます。エージェントに渡したいのは「どこから読むか」であって、値そのものではありません。

失敗4: 古い指示を放置する

❌ よくある間違い: 「パッケージマネージャは npm」と書いたまま、実際は pnpm に移行済みで誰も更新していない

⭕ 正しいアプローチ: AGENTS.md を「生きているドキュメント」として扱い、レビュー日をカレンダーに入れる

なぜ重要か: 古い指示は、無いより悪い結果になります。エージェントは書かれたとおりに従うので、移行済みのツールを使い続けたコードが生まれ、既存コードと衝突します。公式サイトの FAQ も「Treat AGENTS.md as living documentation.（生きたドキュメントとして扱え）」と明記しています。

チームでAGENTS.mdを共有・運用する5つのポイント

個人プロジェクトなら1ファイルで終わりますが、チームで回すには設計が要ります。法人導入でつまずきやすいところから5つ挙げます。

ポイント1: AGENTS.mdをPRレビュー対象にする

コードと同じように、AGENTS.md の変更も PR を通します。エージェントの振る舞いを決めるファイルが、誰にも気づかれずに変わっている状態をなくすためです。

ポイント2: 変更履歴をファイル内に残す

## 変更履歴
# 2026-04-15: テストカバレッジを70%→80%に変更（@yamada）
# 2026-05-01: ESLintルールを追加、no-unused-vars を error に（@tanaka）

Git の履歴でも追えますが、ファイル内に置くとエージェントへの文脈としても機能します。「なぜこのルールがあるのか」が残っていると、削除の判断もしやすくなります。

ポイント3: 新メンバーへの説明にも使う

AGENTS.md が整っていると、新しく入ったエンジニアへのオンボーディング資料としてもそのまま使えます。エージェント向けに書いた説明は、だいたい人間にもちょうどいい粒度になっています。

ポイント4: AGENTS.md・SKILL.md・.rules で分担する

「毎回のコードに適用する基本ルール」は AGENTS.md、「特定タスクのときだけ使う詳細手順」は SKILL.md、「実行してよいコマンド」は .rules。この3分割を最初に決めておくと、どのファイルが膨らんでも整理できます。

ポイント5: 月次で「矛盾していないか」を点検する

月に一度、現在の AGENTS.md を Codex に読ませて「このルールに矛盾はあるか。冗長な部分はあるか。最近のコードと合わなくなっている箇所はあるか」と聞くと、指示書そのものの点検ができます。エージェントの挙動を決めるファイルを、エージェント自身に読み直させる形です。

AGENTS.mdの点検｜公式のトラブルシュートと自作チェック

「書いたのに効いていない気がする」ときの切り分けは、公式ドキュメントのトラブルシュート5項目をそのまま使うのが早いです。

そのうえで、CI に入れておくと事故が減る簡易チェックを置いておきます。必須セクションの有無、機密情報らしき文字列、サイズ上限の3点だけを見るものです。

#!/usr/bin/env python3
"""AGENTS.md の簡易チェック"""

import re
import sys

MAX_BYTES = 32 * 1024  # project_doc_max_bytes の既定値

def check_agents_md(filepath: str) -> list[str]:
    issues: list[str] = []
    with open(filepath, encoding="utf-8") as f:
        content = f.read()

    # 必須セクションの確認
    for section in ("テスト", "禁止", "コーディング"):
        if section not in content:
            issues.append(f"必須セクション「{section}」が見つかりません")

    # 機密情報の簡易チェック
    danger_patterns = [r"passwords*=s*S+", r"://S+:S+@"]
    for pattern in danger_patterns:
        if re.search(pattern, content, re.IGNORECASE):
            issues.append("機密情報が含まれている可能性があります")

    # サイズチェック
    size = len(content.encode("utf-8"))
    if size > MAX_BYTES:
        issues.append(f"サイズ {size} バイトが上限 {MAX_BYTES} バイトを超えています")

    return issues

if __name__ == "__main__":
    path = sys.argv[1] if len(sys.argv) > 1 else "AGENTS.md"
    found = check_agents_md(path)
    for issue in found:
        print(f"NG: {issue}")
    sys.exit(1 if found else 0)

空ファイルが無視される仕様と、サイズ超過で後ろから落ちる仕様は、どちらも「静かに効かなくなる」タイプの失敗です。CI で数値として見えるようにしておくと、気づくのが早くなります。

よくある質問

Q1. AGENTS.md はどこに置くのが正解ですか？

まずリポジトリのルート（README.md と同じ階層）です。Codex はプロジェクトルートから現在の作業ディレクトリへ下りながら探索し、各ディレクトリで最大1ファイルを採用します。サービスごとにルールが違うモノレポでは、そのディレクトリに差分だけの AGENTS.md を追加してください。個人の作法は ~/.codex/AGENTS.md に置きます。

Q2. AGENTS.md と AGENT.md（単数形）はどちらが正しいですか？

複数形の AGENTS.md です。単数形はそのままでは読まれません。既存の AGENT.md がある場合、公式サイトは mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md での移行を案内しています。

Q3. 複数の AGENTS.md が矛盾したら、どちらが勝ちますか？

編集対象のファイルに近い側（下層）が勝ちます。Codex はルート側から順に連結するため、下層の記述が後ろに来て上書きになるからです。公式サイトの FAQ は「最も近い AGENTS.md が勝つ。ユーザーがチャットで明示した指示はすべてに優先する」と説明しています。

Q4. サイズの上限はありますか？超えるとどうなりますか？

既定で合計 32 KiB です（project_doc_max_bytes）。上限に達すると、そこから先のファイルは追加されません。公式の対処は「上限を引き上げる」か「ネストしたディレクトリに分割する」の2つです。

Q5. AGENTS.md に書いたテストコマンドは自動で実行されますか？

公式サイトの FAQ は「Yes — if you list them.（列挙すれば実行する）」としています。エージェントは関連するプログラム的チェックの実行を試み、失敗を直してからタスクを終えます。逆に、書いていないコマンドは実行されません。

Q6. AGENTS.md は日本語で書いてもいいですか？

公式サイトは「必須フィールドはない。標準的な Markdown で、好きな見出しを使ってよい」としており、記述言語の制限は示していません。日本語の可否そのものについては、2026年9月28日時点で公式に記載がありません。日本語で運用する場合は、コマンド名・パス・設定キーだけは原文表記のまま書くのが安全です。

Q7. AGENTS.md は Git にコミットすべきですか？

チームで共有するプロジェクトルートの AGENTS.md はコミットします。だからこそ、接続情報や認証情報を書いてはいけません。一時的に自分だけ設定を差し替えたい場合は、コミットしない AGENTS.override.md を使い、用が済んだら削除します。

Q8. Claude Code は AGENTS.md を読みますか？

Claude Code は既定では CLAUDE.md を読みます。AGENTS.md 公式サイトの対応エージェント一覧にも Claude Code は含まれていません（Cursor・Gemini CLI・GitHub Copilot のコーディングエージェント・Devin・Jules などは掲載）。併用する場合の橋渡しの方法はAGENTS.mdとは｜対応23ツールとClaude Codeが読む条件にまとめています。

Q9. AGENTS.md が実際に読み込まれたか確認する方法はありますか？

3つあります。(1) codex --ask-for-approval never "Summarize the current instructions." で内容を列挙させる。(2) codex --cd <サブディレクトリ> --ask-for-approval never "List the instruction sources you loaded." で下層の上書きを確認する。(3) codex -c log_dir=./.codex-log を付けて起動し、./.codex-log/codex-tui.log を読む。内容が古いままに見えるときは、そのディレクトリで Codex を再起動してください。instruction chain は実行のたびに組み直されるため、消すべきキャッシュはありません。

まとめ：今日から始める3つのアクション

AGENTS.md は「書いたら終わり」ではなく「使いながら削っていくもの」です。小さく始めて、効いているか確認しながら広げるのが長続きします。

1. 今日やること: リポジトリのルートで /init を実行し、生成された雛形にテスト実行コマンドと禁止事項だけ書いてコミットする。そのあと codex --ask-for-approval never "Summarize the current instructions." で読み込まれているか確認する
2. 今週中: チームの「エージェントに毎回説明していること」を3つ集めて、規約セクションと禁止事項セクションに足す。PR を立ててレビューしてもらう
3. 今月中: コマンドの実行可否を .rules へ切り出し、モノレポならサービス単位の差分を下層の AGENTS.md へ移す。ここまで来ると「書いたのに効かない」がほぼ消えます

あわせて読みたい:

• AGENTS.mdとは｜対応23ツールとClaude Codeが読む条件 — どのツールがこのファイルを読むのか
• Codex CLIのSub-agents・自動レビューの使い方 — AGENTS.md から委譲を指示する先の設計
• Codex CLI vs Claude Code 料金比較ガイド — どちらを選ぶべきか用途別に解説
• OpenAI Codex 大型アップデート完全解説 — 最新の機能追加をまとめて確認
• AI導入戦略完全ガイド — 企業全体でのAI活用の設計方針

参考・出典

• Custom instructions with AGENTS.md – ChatGPT Learn — OpenAI（参照日: 2026-09-28。旧URL developers.openai.com/codex/guides/agents-md から308転送）
• Config Reference – ChatGPT Learn — OpenAI（参照日: 2026-09-28）
• Advanced Config（Project instructions discovery） – ChatGPT Learn — OpenAI（参照日: 2026-09-28）
• Rules – ChatGPT Learn — OpenAI（参照日: 2026-09-28）
• Subagents – ChatGPT Learn — OpenAI（参照日: 2026-09-28）
• Developer commands（/init） – ChatGPT Learn — OpenAI（参照日: 2026-09-28）
• ChatGPT & Codex changelog – ChatGPT Learn — OpenAI（参照日: 2026-09-28。Codex CLI 0.157.1 / 2026-09-26）
• AGENTS.md 公式サイト — Agentic AI Foundation / Linux Foundation（参照日: 2026-09-28）
• codex/AGENTS.md at main · openai/codex — OpenAI GitHub（参照日: 2026-09-28）

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。

なお本記事はCodexに特化した内容です。AGENTS.mdがどのツールで読まれるのか、そしてClaude Codeだけが読まない理由と橋渡しの方法は、AGENTS.mdとは｜対応23ツールとClaude Codeの例外で公式ドキュメントを根拠に整理しています。