# AGENTS.md 設定ガイド

`AGENTS.md` は Codex にとって、`CLAUDE.md` が Claude Code にとって果たす役割と同じものです。プロジェクトに置く Markdown ファイルで、AI コーディングアシスタントに「このプロジェクトはどんな規約に従うか、コードをどう書くべきか、何を避けるべきか」を伝えます。

すでに Claude Code の `CLAUDE.md` を使っているなら、`AGENTS.md` の考え方はすぐに馴染むはずです。思想は共通ですが、書式の細部が少し異なります。本ガイドでは `AGENTS.md` の設定を詳しく扱い、両ツールでプロジェクト規約を効率よく使い回す方法を紹介します。

---

> **もはや Codex だけのファイルではありません。** 2026 年 3 月、Anthropic・OpenAI・Google・AWS・Microsoft・
> Salesforce が **Agentic AI Foundation（AAIF）** を設立し、3 つのオープン仕様を共通基盤として採用しました：
> **MCP**（ツールとコンテキストの層）、**AGENTS.md**（エージェントの振る舞いの仕様）、
> **Goose**（リファレンス実装）。実務上これは、1 つの `AGENTS.md` を Codex 以外の
> 増え続けるツール群が読むようになった、ということです。

## AGENTS.md vs CLAUDE.md

`AGENTS.md` に入る前に、`CLAUDE.md` との比較を見ておきましょう：

| 観点 | AGENTS.md（Codex） | CLAUDE.md（Claude Code） |
|--------|---------------------|--------------------------|
| ツール | OpenAI Codex CLI | Anthropic Claude Code |
| ファイル形式 | Markdown | Markdown |
| 読み込み階層 | グローバル / リポジトリルート / サブディレクトリ（3 段） | グローバル / プロジェクトルート / サブディレクトリ（3 段） |
| グローバルの場所 | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| 上書きの仕組み | サブディレクトリが親のルールを上書きできる | サブディレクトリがルールを追加・上書きできる |
| 書き方の傾向 | 簡潔なリスト、指示的な文体 | 詳しい説明も可、会話的な文体も通る |
| コミュニティでの採用 | 急速に拡大中。多くの OSS がすでに採用 | 広く普及、成熟したエコシステム |
| バージョン管理 | リポジトリにコミットすることを推奨 | リポジトリにコミットすることを推奨 |
| 相互認識 | CLAUDE.md は読まない | AGENTS.md は読まない |

> **重要**：2 つのファイルは互いに見えません。両方のツールを使うなら `AGENTS.md` と `CLAUDE.md` を別々に保守する必要があります。ただし中核部分の内容は共有できます。

---

## 基本設定

### ファイルの置き場所

プロジェクトのルートに `AGENTS.md` を作ります：

```
your-project/
  AGENTS.md          <- リポジトリレベルの設定
  src/
  tests/
  package.json
```

### 基本の書き方

`AGENTS.md` は標準的な Markdown ファイルです。Codex は起動時にこれを読み、書かれた指示に従います。最もよく使われるのは **箇条書き** です：

```markdown
# AGENTS.md

- コードはすべて TypeScript の strict モードで書くこと
- 整形は Prettier、静的解析は ESLint を使う
- テストは Vitest を使い、`__tests__/` ディレクトリに置く
- タスク完了前に `npm run lint && npm test` を実行する
- `vendor/` ディレクトリのファイルは変更しない
- API レスポンスは標準のエンベロープ形式に従う：`{ code, data, message }`
```

見出しでカテゴリ分けすることもできます：

```markdown
# AGENTS.md

## コード規約
- TypeScript の strict モードを使う
- 変数は camelCase、型は PascalCase
- 1 つの関数は 50 行以内に収める

## テスト要件
- 単体テストのカバレッジ目標は 80%
- テストファイルはソースと同名 + `.test.ts`
- 外部依存はモックする。テスト内で実ネットワークへ出ない

## 禁止事項
- `any` 型を使わない
- DOM を直接操作しない（React の状態管理を使う）
- ループ内で `await` しない（`Promise.all` を使う）
```

### 記述言語の選択

`AGENTS.md` の内容は **日本語** でも **英語** でも書けます。Codex はどちらも正しく理解します。チーム開発の観点では：

- **個人プロジェクト**：使いやすい言語で
- **チームプロジェクト**：英語を推奨（コードと揃う）
- **日本語話者のチーム**：日本語でまったく問題ありません

---

## 階層設定

`AGENTS.md` は 3 段階の設定レベルに対応し、グローバルから特定ディレクトリへとルールを絞り込めます：

### レベル 1：グローバル設定

場所：`~/.codex/AGENTS.md`

自分のすべてのプロジェクトに適用される共通規約：

```markdown
# グローバル AGENTS.md

## 共通規約
- コードコメントは英語で書く
- Git のコミットメッセージは Conventional Commits に従う
- パスワード・キー・トークンをソースに直接書かない
- 新しいコードを書く前に既存の関連コードを読み、一貫性を保つ
- 変更の影響が不明なときは、憶測せずコメントで説明を残す

## 出力の好み
- 既存の依存関係を優先し、不要な新規依存は入れない
- エラーハンドリングは徹底する。例外を黙って握り潰さない
- ログメッセージは意味のあるものにし、文脈を含める
```

### レベル 2：リポジトリレベル設定

場所：プロジェクトルートの `AGENTS.md`

特定のプロジェクト固有の規約：

```markdown
# AGENTS.md

## プロジェクト概要
TypeScript で作られた React + Node.js のフルスタック EC プロジェクト。

## 技術スタック
- フロントエンド：React 19 + TailwindCSS + Zustand
- バックエンド：Node.js + Fastify + Prisma
- データベース：PostgreSQL 16
- テスト：Vitest + Playwright

## コード規約
- コンポーネントファイルは PascalCase：`UserProfile.tsx`
- ユーティリティ関数は camelCase：`formatDate.ts`
- API ルートは kebab-case：`/api/user-orders`
- データベースのフィールドは snake_case：`created_at`

## ディレクトリ構成
- `src/components/` - React コンポーネント
- `src/pages/` - ページコンポーネント
- `src/api/` - バックエンドの API ルート
- `src/lib/` - 共有ユーティリティ
- `prisma/` - データベーススキーマとマイグレーション

## コマンド
- `npm run dev` - 開発サーバーを起動
- `npm run build` - 本番ビルド
- `npm test` - すべてのテストを実行
- `npm run lint` - 静的解析
- `npx prisma migrate dev` - データベースマイグレーション
```

### レベル 3：サブディレクトリ設定

場所：任意のサブディレクトリの `AGENTS.md`

特定モジュール向けの追加ルールで、**親レベルのルールに重ねて適用** されます：

```
your-project/
  AGENTS.md                  <- プロジェクトレベルのルール
  src/
    components/
      AGENTS.md              <- コンポーネントディレクトリのルール
    api/
      AGENTS.md              <- API ディレクトリのルール
```

`src/components/AGENTS.md` の例：

```markdown
# コンポーネント規約

- すべて関数コンポーネントにする（クラスコンポーネント禁止）
- Props は TypeScript の interface で定義する
- すべてのコンポーネントに displayName を付ける
- スタイルは TailwindCSS を使い、インラインスタイルは書かない
- 複雑なコンポーネントは分割し、1 ファイル 200 行以内に収める
- 再利用可能なコンポーネントは `ui/` サブディレクトリに置く
```

`src/api/AGENTS.md` の例：

```markdown
# API 規約

- すべてのエンドポイントでリクエストパラメータを検証する（Zod スキーマ）
- エラー形式を統一する：`{ code: number, message: string, details?: any }`
- データベース操作はトランザクション内で行う
- 重要な操作は監査ログに残す
- ページネーションはカーソル方式を使う
```

### 上書きの優先順位

複数の `AGENTS.md` でルールが衝突した場合、**近いものが勝ちます**：

```
グローバル（~/.codex/AGENTS.md）
  | リポジトリレベルが上書き
リポジトリルート（project/AGENTS.md）
  | サブディレクトリが上書き
サブディレクトリ（project/src/api/AGENTS.md） <- 最優先
```

実際の挙動：

- サブディレクトリの `AGENTS.md` のルールが親より優先される
- 上書きされていない親のルールはそのまま有効
- 複数レベルのルールは **加算的** であり、丸ごと置き換えではない

---

## 実践テンプレート

そのままプロジェクトにコピーできる、実戦で使われているテンプレートをいくつか挙げます。

### フロントエンド React プロジェクト

```markdown
# AGENTS.md

## プロジェクト情報
React 19 + TypeScript + TailwindCSS のフロントエンドプロジェクト。

## コード規約
- 関数コンポーネント + Hooks を使う。クラスコンポーネントは禁止
- 状態管理は Zustand。Redux は導入しない
- スタイルは TailwindCSS。CSS ファイルは作らない
- src 配下の参照には `@/` のパスエイリアスを使う
- コンポーネントの Props は `{ComponentName}Props` という interface で定義する

## ファイル命名
- コンポーネント：PascalCase（`UserAvatar.tsx`）
- Hook：camelCase + use プレフィックス（`useAuth.ts`）
- ユーティリティ：camelCase（`formatDate.ts`）
- 定数：camelCase（`apiEndpoints.ts`）

## コンポーネントのルール
- Props の型とコンポーネント本体の両方をエクスポートする
- 純粋な表示コンポーネントは `React.memo` で包む
- イベントハンドラーは `handle{EventName}` と命名する
- render 内で新しいオブジェクトや関数を作らない

## テスト
- フレームワーク：Vitest + React Testing Library
- テストファイルは `__tests__/` ディレクトリに置く
- 実装詳細ではなくユーザーの振る舞いをテストする
- 実行コマンド：`npm test`

## 依存関係の管理
- 新しい依存を追加する前に、既存で足りないか確認する
- 軽量なライブラリを優先する
- すべての依存に TypeScript の型定義があること
```

### バックエンド Python/FastAPI プロジェクト

```markdown
# AGENTS.md

## プロジェクト情報
Python 3.12 + FastAPI + SQLAlchemy のバックエンドサービス。

## コード規約
- 型注釈：すべての引数と戻り値に型注釈を付ける
- 非同期優先：すべての IO は async/await で書く
- Docstring：公開関数はすべて Google スタイルの docstring を書く
- import 順：標準ライブラリ → サードパーティ → ローカル（isort で管理）

## ディレクトリ構成
- `app/api/` - API ルート（機能ごとの router に分ける）
- `app/models/` - SQLAlchemy のデータモデル
- `app/schemas/` - Pydantic のリクエスト / レスポンスモデル
- `app/services/` - ビジネスロジック層
- `app/core/` - 設定、セキュリティ、依存性注入
- `tests/` - テスト。app のディレクトリ構成を鏡写しにする
- `alembic/` - データベースマイグレーション

## コーディング規約
- ルート関数の命名：`get_users`、`create_order`（動詞_名詞）
- Service 層のメソッドはルート関数に対応させる
- データモデルのフィールドは snake_case
- データベース操作はすべて Service 層を通す。ルートから ORM を直接触らない
- 機密データ（パスワード、トークン）はログやレスポンスに絶対に出さない

## エラーハンドリング
- 業務例外はカスタム Exception クラスにする
- 例外ハンドラーを統一し、標準形式で返す：`{"code": int, "message": str}`
- データベース操作は try/except で IntegrityError などを捕捉する
- 裸の except は使わない

## テスト
- フレームワーク：pytest + pytest-asyncio + httpx
- fixture でテスト用データベースとクライアントを管理する
- 実行コマンド：`pytest -v --cov=app`
- カバレッジ目標：80% 以上

## 環境管理
- 設定は .env ファイルに置き、pydantic-settings で読み込む
- 環境ごとの差分は環境変数の上書きで扱う
- データベース接続文字列やシークレットをコードに直接書かない
```

### フルスタックプロジェクト

```markdown
# AGENTS.md

## プロジェクト情報
フルスタック Web アプリ：Next.js 15 フロントエンド + API Routes + PostgreSQL。
Turborepo で管理する monorepo 構成。

## ディレクトリ構成
- `apps/web/` - Next.js フロントエンド
- `apps/api/` - 独立した API サービス（Node.js + Fastify）
- `packages/ui/` - 共有 UI コンポーネントライブラリ
- `packages/types/` - 共有 TypeScript 型
- `packages/utils/` - 共有ユーティリティ関数
- `packages/db/` - データベーススキーマ（Drizzle ORM）

## 共通規約
- 言語：TypeScript strict モード
- 整形：Prettier（ルートで設定）
- Lint：ESLint（ルートで設定）
- コミット前に実行：`turbo lint test`

## フロントエンド規約（apps/web/）
- Pages Router ではなく App Router を使う
- Server Components を優先し、必要なときだけ Client Components にする
- データ取得は Server Actions か Route Handlers 経由
- スタイルは TailwindCSS
- 画像は next/image コンポーネントを使う

## API 規約（apps/api/）
- RESTful 設計。URL は kebab-case
- リクエスト検証は Zod
- レスポンス形式：`{ success: boolean, data?: T, error?: string }`
- 認証は JWT。ミドルウェアで検証する
- レート制限のルールはルートのデコレーターに書く

## データベース規約（packages/db/）
- Drizzle ORM を使い、スキーマは `schema/` ディレクトリに定義する
- マイグレーションコマンド：`pnpm db:migrate`
- 命名：テーブル名は複数形（`users`）、フィールドは snake_case
- すべてのテーブルに `created_at` と `updated_at` を持たせる
- 論理削除は `deleted_at` フィールドで表す

## 共有パッケージの規約
- パッケージ間は workspace 経由で参照する
- 共有の型定義は `packages/types/` に置く
- パッケージから apps を import しない
```

---

## 高度なテクニック

### CLAUDE.md との共存

プロジェクトで Codex と Claude Code の両方を使う場合、2 つの設定ファイルを並べて保守できます：

```
your-project/
  AGENTS.md          <- Codex が読む
  CLAUDE.md          <- Claude Code が読む
  src/
  ...
```

**中核の規約は共有できます**。両ファイルの内容の大半（技術スタック、命名規約、ディレクトリ構成など）は同じになり、違うのはツール固有の指示だけです。

おすすめの進め方：

1. 中核の規約を 1 セットだけ書く
2. `AGENTS.md` と `CLAUDE.md` の両方にコピーする
3. それぞれのツールの慣習に合わせて書式を調整する

もう少しスマートなやり方として、各ファイルの冒頭で相互参照させる方法もあります：

```markdown
# AGENTS.md

> このプロジェクトは Codex と Claude Code の両方を使います。中核の規約は以下です。
> Claude Code のユーザーは CLAUDE.md も参照してください。

## 中核の規約
（共有する内容）
```

### チーム運用のベストプラクティス

#### バージョン管理にコミットする

`AGENTS.md` は Git リポジトリにコミットし、チーム全員が同じ AI コーディング規約を共有できるようにします：

```bash
git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"
```

#### AGENTS.md をコードレビューの対象に含める

`AGENTS.md` の変更は、コーディング規約の変更と同じようにレビューを通すべきです：

```markdown
<!-- PR の説明 -->
## 変更概要
AGENTS.md の更新：
- API のページネーション規約を追加（カーソル方式）
- コンポーネント内での直接の fetch 呼び出しを明示的に禁止
- ログ形式の要件を追加
```

#### 少しずつ育てる

最初からすべてを書く必要はありません。おすすめの進め方：

1. **初日**：技術スタックと命名規約の基本を書く（10〜20 行）
2. **最初の 1 週間**：Codex の実際の振る舞いを見てルールを足す
3. **その後**：Codex が望まない動きをするたびに `AGENTS.md` にルールを 1 行足す

### 効果の高い指示の書き方

`AGENTS.md` では、次のような指示がよく効きます：

```markdown
## 効果の高い指示（Codex が確実に従う）

- 明確な形式指定：コンポーネントのファイル名は PascalCase にする
- 明確な禁止：any 型を使わない
- 実行コマンド：タスク完了後に npm test を実行する
- ファイル配置のルール：テストファイルは __tests__ ディレクトリに置く
- 依存関係の制約：新しい npm パッケージを入れず、既存の依存を使う
```

```markdown
## 効果の低い指示（避けたほうがよい）

- 曖昧すぎる：良いコードを書く
- 主観的：ベストプラクティスに従う
- 範囲外：ユーザー体験を考慮する（AI は UI を動かせない）
- 矛盾：性能を優先 + 可読性を優先（優先順位を明示する必要がある）
```

### 条件付きルール

ファイル種別やディレクトリごとに異なるルールを設定できます：

```markdown
## ファイル種別ごとのルール

### *.test.ts ファイル
- 1 つの describe ブロックにテストは 10 個まで
- テストデータはファクトリー関数で作る。ハードコードしない
- 非同期テストにはタイムアウトを設定する

### *.api.ts ファイル
- リクエストパラメータを必ず検証する
- エラーハンドリングを必ず入れる
- 戻り値に型注釈を付ける

### migrations/*.sql ファイル
- 直接編集しない。ORM のマイグレーションツールで生成する
```

---

## CLAUDE.md からの移行

すでに `CLAUDE.md` があるなら、`AGENTS.md` への変換は簡単です。どちらも Markdown で、中核の内容はそのまま移せます。

### 移行の手順

**ステップ 1：ベースの内容をコピーする**

```bash
cp CLAUDE.md AGENTS.md
```

**ステップ 2：Claude Code 固有の記述を置き換える**

Claude Code 固有の概念を Codex の対応するものに置き換えます：

| CLAUDE.md では | AGENTS.md では |
|--------------|--------------|
| 「Claude がファイルを変更するときは…」 | 「ファイルを変更するときは…」 |
| 「`/compact` でコンテキストを圧縮する」 | （削除 — Codex にこのコマンドはない） |
| 「`@` でファイルを参照する」 | （削除 — Codex は別の参照方式） |
| 「Hook: PostToolUse…」 | 「タスク完了後に…を実行する」 |
| 「サブエージェントが処理する…」 | 「Cloud Exec を使う…」 |

**ステップ 3：書式を整理する**

Codex は簡潔なリスト形式の指示を好みます。`CLAUDE.md` に長い説明段落があるなら、箇条書きに圧縮しましょう：

移行前（`CLAUDE.md` スタイル）：

```markdown
## コードスタイル

このプロジェクトでは Google の TypeScript スタイルガイドに従います。変数名は
すべて camelCase、クラス名は PascalCase を使います。列挙型の値は
SCREAMING_SNAKE_CASE を使う点に注意してください。import 文の順序は、まず
Node.js の組み込みモジュール、次にサードパーティのパッケージ、最後にローカル
モジュールとし、それぞれのグループの間に空行を入れます。
```

移行後（`AGENTS.md` スタイル）：

```markdown
## コードスタイル
- Google の TypeScript スタイルガイドに従う
- 変数：camelCase
- クラス：PascalCase
- 列挙型の値：SCREAMING_SNAKE_CASE
- import 順：組み込みモジュール → サードパーティ → ローカル（グループ間は空行）
```

**ステップ 4：Codex 固有の指示を足す**

```markdown
## Codex 固有の設定
- ファイル変更がすべて終わったら `npm run lint && npm test` を実行して検証する
- テストが失敗したら自動で修正し、再実行する
- .env と .env.local は変更しない
```

### 移行の対応表

| 概念 | CLAUDE.md スタイル | AGENTS.md スタイル |
|---------|-----------------|-----------------|
| プロジェクト説明 | 自由な段落 | 短いリストまたは段落 |
| コード規約 | Markdown のリスト | Markdown のリスト（同じ） |
| 禁止事項 | 「X をしないでください」 | 「X は禁止」または「X をしない」 |
| 実行コマンド | 「`npm test` を実行してください」 | 「`npm test` を実行する」または列挙するだけ |
| ファイル構成 | ディレクトリツリーのコードブロック | ディレクトリツリーのコードブロック（同じ） |
| ツール設定 | settings.json の参照 | config.toml の参照 |

### 両方のファイルを保守する場合

`AGENTS.md` と `CLAUDE.md` を長期的に両方保守する場合：

1. **どちらかを「主」に決める**：よく使うツールのファイルを主にするのが普通です
2. **主を編集したら同期する**：簡単なスクリプトで自動化できます
3. **ツール固有のルールは分けて置く**：共有規約を前半に、ツール固有を末尾に

---

## デバッグと検証

### AGENTS.md が効いているか確認する

最も簡単な確認方法は、ルールが働くはずのタスクを Codex に投げてみることです：

```bash
# AGENTS.md が TypeScript を要求している前提
codex "hello world 関数を作って"

# AGENTS.md が効いていれば、Codex は .js ではなく .ts ファイルを生成します
```

### ルールが効かないときの切り分け

1. **ファイルの場所**：`AGENTS.md` がプロジェクトルートか該当サブディレクトリにあるか
2. **ファイル名**：`AGENTS.md`（大文字。`agents.md` は不可）になっているか
3. **書式の問題**：Markdown として正しいか（リストの前に空行、など）
4. **ルールの衝突**：複数階層の `AGENTS.md` に矛盾する指示がないか
5. **曖昧すぎる**：もっと具体的な表現に置き換えてみる

---

## CLAUDE.md と AGENTS.md のどちらを使うか

設定ファイルを両方保守するのは自然に思えますが、**2 つのコピーは必ず食い違っていきます**。`AGENTS.md` にルールを足して `CLAUDE.md` に反映し忘れると、2 つのツールの挙動がずれ始めます。以下はその罠を避けるための指針です。

### まず「使うツールの数」から考える

- **Claude Code だけ（単一ツール）**：`CLAUDE.md` だけで十分です。Claude Code は `CLAUDE.md` をネイティブに読み、グローバルメモリとパススコープのルール（入れ子の `CLAUDE.md` / `.claude/rules`）を重ねます。`AGENTS.md` を併せて保守する必要はありません。
- **複数ツールのチーム（Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed など）**：`AGENTS.md` を **単一の真実の源** にしてください。Claude Code 以外の多くのツールは `AGENTS.md` を読み、Claude Code は既定では `CLAUDE.md` しか読みません。

### 複数ツールのチームへの推奨：AGENTS.md を取り込む薄い CLAUDE.md

食い違っていく 2 つの完全なコピーを持つのはやめましょう。共有規約は `AGENTS.md` に置き、**薄い `CLAUDE.md`** でそれを取り込めば、Claude Code はチーム共有のルールと Claude 固有の追加分の両方を得られます：

```markdown
# CLAUDE.md

@AGENTS.md

## Claude Code 固有の追加
- タスクに応じて `/model` で Sonnet 4.6 / Opus 4.8 を切り替える
- 大きな変更の前には `/plan` を実行する
- 無関係なタスクの間は `/clear`、長いセッションの区切りでは `/compact` を使う
```

こうすれば共有規約の源は `AGENTS.md` 一箇所になり、`CLAUDE.md` には Claude Code 固有の指示だけが残ります — ルート直下に食い違う重複を作らずに済みます。

### 判断早見表

| 状況 | 保守するもの | 補足 |
|----------|------------------|-------|
| Claude Code だけ | `CLAUDE.md` のみ | ネイティブに読まれる。`AGENTS.md` は不要 |
| Codex や他ツールだけ | `AGENTS.md` のみ | これらのツールは `CLAUDE.md` を読まない |
| 複数ツールのチーム | `AGENTS.md`（真実の源）+ 薄い `CLAUDE.md`（`@AGENTS.md`） | 源はひとつ、食い違いなし |

> `CLAUDE.md` の階層・テンプレート・コンテキスト管理については [CLAUDE.md 設定ガイド](/docs/usage/claude-md) を参照してください。

---

## 次のステップ

- [Codex クイックスタート](/docs/getting-started/codex-quick-start) -- Codex のインストールと設定
- [Codex vs Claude Code 比較](/docs/getting-started/codex-vs-claude-code) -- 両ツールの完全比較
- [Hooks システム](/docs/advanced/hooks) -- Claude Code のイベントフック（似た考え方）
- [CLI の便利な使い方](/docs/usage/cli-tips) -- AI コーディングを効率化する実践テクニック