対象 AGENTS.md設計を学びたい開発者

達成目標最適なプロジェクト構成を設計できる

前提知識 Getting Started完了

所要時間 20分

プロジェクト構成

AGENTS.md、config.toml、ファイル検出階層など、Codexプロジェクトの設計パターンを解説します。

全体ファイルマップ

Codexプロジェクトの典型的なディレクトリ構成です。太字のファイルがCodex固有の設定ファイルです。

プロジェクトルート

my-project/
├── AGENTS.md                    # プロジェクト指示書（メイン）
├── .codex/
│   └── config.toml              # Codex設定ファイル
├── skills/
│   ├── deploy.md                # デプロイSkill
│   ├── test-runner.md           # テスト実行Skill
│   └── code-review.md          # コードレビューSkill
├── src/
│   ├── AGENTS.md                # サブディレクトリ固有の指示
│   └── ...
├── tests/
│   ├── AGENTS.md                # テスト固有の指示
│   └── ...
├── package.json
└── README.md

📝 Note

サブディレクトリにも AGENTS.md を配置できます。Codexはファイルの編集・参照時に、最も近い AGENTS.md の指示を優先的に読み込みます。

AGENTS.md設計

AGENTS.mdはCodexの「プロジェクト理解」の基盤です。適切に設計することで、Codexの出力品質が大きく向上します。

推奨セクション構成

以下の4つのセクションを含めることを推奨します。

Repository expectations — プロジェクトの言語、フレームワーク、パッケージマネージャなどの基本情報。
Testing — テスト実行コマンド、カバレッジ要件、テスト作成ルール。
Coding conventions — 命名規則、インデント、importの順序、禁止パターンなど。
Build commands — ビルド、Lint、型チェック、デプロイなどのコマンド一覧。

AGENTS.md（推奨テンプレート）

# AGENTS.md

## Repository expectations
- Language: TypeScript 5.x
- Framework: Next.js 15 (App Router)
- Package manager: pnpm
- Node version: 22+

## Testing
- Unit tests: `pnpm test`
- E2E tests: `pnpm test:e2e`
- Coverage threshold: 80%
- 新機能には必ずテストを追加すること

## Coding conventions
- 変数名: camelCase
- コンポーネント: PascalCase
- ファイル名: kebab-case
- インデント: 2スペース
- import順: React → 外部ライブラリ → 内部モジュール
- any型の使用禁止
- console.log はデバッグ以外で使用しない

## Build commands
- Build: `pnpm build`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`
- Format: `pnpm format`

サブディレクトリオーバーライド

サブディレクトリに AGENTS.md または AGENTS.override.md を配置すると、そのディレクトリ以下で固有のルールを追加・上書きできます。

src/components/AGENTS.md

# Components Directory

## Conventions
- すべてのコンポーネントはdefault exportを使用
- Propsの型定義は同ファイル内に記述
- スタイルはCSS Modulesを使用
- Storybookストーリーを必ず作成

✅ Tip

サブディレクトリの AGENTS.md はルートの指示に「追加」されます。ルートの指示と矛盾する場合は、より近い（サブディレクトリの）指示が優先されます。

config.toml

.codex/config.toml は、Codexの動作を制御するTOML形式の設定ファイルです。モデル選択、承認モード、サンドボックス設定などをプロジェクト単位で管理できます。

.codex/config.toml

# モデル設定
model = "gpt-5-codex"

# 承認モード: "suggest" | "auto-edit" | "full-auto"
approval_mode = "auto-edit"

# Web検索の有効化
web_search = true

# サンドボックス設定
[sandbox]
# ワークスペースへの書き込み許可
workspace_write = true
# ネットワークアクセス（デフォルト: 無効）
network_access = false

# プロファイル定義
[profiles.fast]
model = "gpt-4.1-mini"
approval_mode = "full-auto"

[profiles.careful]
model = "gpt-5-codex"
approval_mode = "suggest"

プロファイル

プロファイルを定義すると、用途に応じた設定セットを素早く切り替えられます。

Terminal

# fastプロファイルで起動
codex --profile fast

# carefulプロファイルで起動
codex --profile careful

📝 Note

config.tomlはプロジェクトルートの .codex/ ディレクトリに配置します。チームで共有する場合はGitにコミットしましょう。個人設定は ~/.codex/config.toml に配置します。

ファイル検出階層

CodexはAGENTS.mdとconfig.tomlを階層的に検出します。最も近い（深い）ファイルが優先されます。

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

ユーザーのホームディレクトリにある設定。すべてのプロジェクトに適用されるデフォルト値として機能します。個人的な好み（モデル、承認モード等）を設定するのに最適です。

プロジェクトルート

プロジェクト直下の AGENTS.md と .codex/config.toml。プロジェクト全体に適用される設定。チーム共有の規約やビルドコマンドを記述します。グローバル設定を上書きします。

サブディレクトリ

各ディレクトリの AGENTS.md。そのディレクトリ以下のファイルを操作する際に追加で読み込まれます。コンポーネント固有の規約やテストポリシーなど、局所的なルールに使います。

⚠️ Warning

AGENTS.mdを深くネストしすぎると、コンテキストウィンドウを圧迫します。通常はルート + 主要ディレクトリ（src/、tests/など）の2階層で十分です。

Claude Code CLAUDE.mdとの違い

CodexのAGENTS.mdとClaude CodeのCLAUDE.mdは似た目的を持ちますが、いくつかの重要な違いがあります。

項目	Codex AGENTS.md	Claude Code CLAUDE.md
ファイル名	`AGENTS.md`	`CLAUDE.md`
設定ファイル	`.codex/config.toml`（TOML）	`.claude/settings.json`（JSON）
初期化コマンド	`/init`	`/init`
サブディレクトリ	AGENTS.md / AGENTS.override.md	CLAUDE.md（サブディレクトリ対応）
安全機構	サンドボックス（OS native）	Hooks（PreToolUse等）
自動化	Skills（Markdownベース）	Hooks + Custom Slash Commands
プロファイル	config.tomlの[profiles]セクション	なし（設定ファイル切替で対応）
承認モード	Suggest / Auto Edit / Full Auto	AllowedTools / DeniedTools

✅ Tip

両方のツールを使うプロジェクトでは、AGENTS.mdとCLAUDE.mdの内容を同期させましょう。共通部分（コーディング規約、ビルドコマンド等）は一方に書いてもう一方から参照する形にすると、メンテナンスが楽になります。

← 前のページ

Getting Started

CLI & App