OpenAI Codex 向け AGENTS.md 完全ガイド — Claude との違いと実践パターン

AGENTS.md はプロジェクトレベルの AI エージェント指示のクロスツール標準になりました。Claude Code も OpenAI Codex も読み取り、権威あるプロジェクトコンテキストとして扱います。しかし両者は異なる方法で読み取り、異なる方法で適用し、同じ指示に対して測定可能なほど異なる方法で応答します。

両ツールで機能する単一の AGENTS.md を維持する場合、または Claude Code から Codex に切り替える場合、このガイドは日常の出力に影響を与える実践的な違いをカバーします。

Codex が実際に読むもの

OpenAI Codex（古い補完モデルではなくクラウドベースのコーディングエージェント）は以下の場所で AGENTS.md を探します。

1. リポジトリルート（/AGENTS.md）
2. 作業を依頼されたディレクトリ
3. リポジトリルートまでの親ディレクトリ

ルックアップは階層的です。src/components/ 上で Codex を実行すると、src/components/AGENTS.md、次に src/AGENTS.md、次に ./AGENTS.md を読みます。見つかったすべてのファイルが結合され、より具体的な（深い）ファイルが競合する指示で優先されます。

これは Claude Code と同じルックアップ動作で、共有 AGENTS.md が原則として機能する理由です。違いは指示の解釈方法にあります。

指示の解釈の違い

明示的なコマンドは Codex でよりリテラルに実行されます。

Claude Code はルールの例外に文脈的な判断を適用します。CLAUDE.md に「コミット前に常にテストを実行する」とあって、「この小さな修正だけ」と伝えると、Claude Code は自分が何をしているか理解していると文脈から推測してテストなしで進む場合があります。

Codex はルールをより一様に適用します。同じ「小さな修正」という指示でも、それが AGENTS.md の指示だからというだけでテスト実行をより頻繁にトリガーします。これはバグではありません — 柔軟性より信頼性を優先する意図的な設計選択です。

実践的な意味: 厳しすぎる AGENTS.md を書くと、Codex は意図したよりリテラルに従います。実際に強制したいルールを書いてください。実際には無視している理想的なルールは書かないこと。

否定はより明示的な形で機能します。

CLAUDE.md では「main に直接コミットしない」は確実に尊重されます。Codex 向け AGENTS.md では、否定的な指示を一貫して従ってもらうには肯定的な代替案とペアにする必要があります。

# Codex での信頼性が低い
main に直接コミットしない。

# Codex での信頼性が高い
変更を行う前に必ずフィーチャーブランチを作成する。main に直接プッシュしない。

肯定的なバージョン（「ブランチを作成する」）は Codex に取るべき具体的なアクションを与えます。否定的なバージョン（「X をするな」）は代わりに何をすべきかを推測させ、結果が変わります。

フォーマット指定は厳密に従われます。

両ツールともフォーマット指示を尊重しますが、Codex は出力フォーマットについて特に一貫しています。「テスト結果を表で出力する」と指定すると、Codex は確実に表を生成します。これは Claude Code よりも Codex でフォーマット指示がより有用なことを意味します。Claude Code では実際のフォーマットが文脈によって変わることがあります。

Codex 互換の AGENTS.md 執筆

両ツールで機能する適切に構造化された AGENTS.md:

# プロジェクト: [名前]

## 目的
[このコードベースが何をするかを1文で]

## スタック
- ランタイム: Node 20
- フレームワーク: Next.js 14 (App Router)
- データベース: PostgreSQL 16 with Drizzle ORM
- テスト: Vitest + Testing Library

## 作業規約

### 変更を行う前に
1. まず関連する既存コードを読む
2. 変更する箇所にテストが存在するか確認する
3. 単一の関数より大きな変更の場合、実装前にアプローチをコメントで説明する

### 変更を行った後に
1. `npm run lint` を実行してすべてのエラーを修正する
2. `npm run test` を実行してすべてのテストがパスすることを確認する
3. 新しい機能を追加した場合、対応するテストを追加する

### ブランチとコミット
- 常に `feature/{説明}` または `fix/{説明}` という名前のブランチを作成する
- コミットメッセージ: `type: 簡潔な説明`（例: `fix: ユーザーローダーの null チェック`）
- コミットをスカッシュしない — 変更の履歴を保持する

### コードパターン
- デフォルトエクスポートよりも名前付きエクスポートを優先する
- 静的設定オブジェクトには `const` アサーションを使う
- 条件を深くネストする代わりに関数から早期リターンする
- テストはソースファイルとコロケーション

構造に注目してください: プロセスには番号付き手順、パターンには短い宣言的な文。このフォーマットは Claude Code と Codex の両方で一貫したパースを生み出します。

Codex との CI 連携

Codex は OpenAI Agents API を通じて CI パイプラインで動作します。ヘッドレス環境で動作する場合、曖昧さを解決するためのインタラクティブなセッションがないため、AGENTS.md のコンテキストがさらに重要になります。

CI 固有の動作のためにセクションを追加します。

## CI 環境

CI で動作する場合（CI=true 環境変数で検出）:
- 確認を求めない — 利用可能なコンテキストに基づいて最善の判断をする
- `npm run test` の代わりに `npm run test:ci` を実行する（ウォッチモードなし）
- テスト出力に `--reporter=json` フラグを使う（機械可読）
- ブラウザタブを開いたりインタラクティブな入力を要求したりしない
- 任意のステップが失敗した場合はコード 1 で終了する — 自動的に回復を試みない

Codex はこのセクションを読み取り、CI=true が設定されているときに適用して、自動化パイプラインでの動作を予測可能にします。

実際に機能するセキュリティ指示

Claude Code も Codex も AGENTS.md のセキュリティルールを尊重しますが、フレーミングが重要です。

## セキュリティルール

以下はすべてのコード変更に適用されます:

- データベースクエリやシステムコールで使用する前にすべてのユーザー入力をバリデーションする
- すべてのデータベース操作にはパラメータ化クエリを使う — 文字列連結は決して許容されない
- シークレットを含む可能性のある値をログに記録しない（パスワード・トークン・APIキー）
- 依存関係: このファイルに先にリストアップせずに新しい npm パッケージを追加しない
- 環境変数: ランタイムに環境から読み取る。値をハードコードしない

### 制限された操作
以下の操作は進める前に明示的な人間の承認が必要:
- データベーススキーマの変更（マイグレーション）
- 認証・認可ロジックの変更
- 新しい外部 API 統合の追加
- CORS 設定の変更

「制限された操作」セクションは Claude Code と Codex で異なる動作をします。Claude Code は一時停止して何に承認が必要かを説明します。CI パイプライン内の Codex は停止して実行を失敗させ、手動介入を必要とします。どちらも適切な結果です — 重要なのは、動作が暗黙的ではなく AGENTS.md に明示的に記載されていることです。

AGENTS.md の有効性のテスト

AGENTS.md の指示が従われているかをテストする最速の方法:

1. 観察可能な動作を生み出す指示を書く（出力フォーマット・ファイル命名・ブランチ命名）
2. それをトリガーするタスクを実行する
3. 出力が一致することを確認する

Codex の場合、サンドボックスリポジトリでテストします。

# テストタスクを作成
echo "メールアドレスをバリデーションするユーティリティ関数を追加して" | codex run

# AGENTS.md の命名規約に従っているか確認
# テストを作成したか確認
# フィーチャーブランチを作成したか確認

3つの単純な観察可能なルールが従われていない場合、長いルールリストも役に立ちません。まず根本的なパースの問題（通常はフォーマットや指示の明確さ）を修正してください。

別ファイルを維持すべき時

マルチエージェントの AGENTS.md はある程度まで機能します。Claude Code と Codex の動作の乖離が、一方のツールに対して積極的に機能しないルールを書くほど大きくなったら、別ファイルに分割します。

• AGENTS.md — 共有の普遍的なルール
• CLAUDE.md — Claude Code 固有の動作（AGENTS.md のコンテキストを暗黙的にインポート）

Claude Code は両方が存在する場合 CLAUDE.md を優先的に読みます。Codex は AGENTS.md を読みます。共有ルールは AGENTS.md に、Claude 固有の最適化は CLAUDE.md に。

このセットアップは、複雑な判断呼び出しに Claude Code のより文脈適応的な解釈を使いながら、CI パイプラインで一貫したリテラルなルール遵守のために Codex を使う場合を処理します。

まとめ

Claude Code vs Codex での AGENTS.md 動作の主な実践的違い:

番号付きプロセス手順と肯定的なアクション文で AGENTS.md を書いてください。判断呼び出しは CLAUDE.md のために残してください。動作の違いがツールごとに異なる指示を必要とする場合はファイル分割アプローチを使います。