OpenAI Codex AGENTS.md完全ガイド — カスタム環境設定とMCP連携で開発効率を最大化する方法【2026年版】

AGENTS.mdとは、リポジトリに配置するMarkdownファイルで、Codexにプロジェクト固有の指示を永続的に伝えるための設定ファイルです。READMEが人間向けであるのに対し、AGENTS.mdはAIエージェント向けのREADMEです。 適切に設定されたAGENTS.mdがあれば、「TypeScriptのstrictモードを使って」「テストはpnpm testで」「コミットはConventional Commits形式で」といった指示を毎回チャットで伝える必要がなくなります。Codexはタスクを受け取るたびにAGENTS.mdを読み込み、プロジェクトの文脈を理解してから作業を開始します。

Codexは複数の場所からAGENTS.mdを探し、優先順位に従って指示を合成します。 ``` [最高優先] AGENTS.override.md（サブディレクトリ） ↓ AGENTS.md（サブディレクトリ） ↓ gitルートに向かって上位ディレクトリを順次探索 ↓ ~/.codex/AGENTS.md（グローバル設定） ↓ [最低優先] フォールバック（TEAM_GUIDE.md / CONTRIBUTING.md等） ``` 実践的な活用法： - リポジトリルートの`AGENTS.md`にプロジェクト全体の規約を記述 - サブディレクトリ（例：`frontend/AGENTS.md`）でフロント固有の指示を上書き - `~/.codex/AGENTS.md`に個人の好みやグローバル設定を記述 - 緊急の上書きが必要なときは`AGENTS.override.md`を使用

以下は本番環境で使えるAGENTS.mdの実践テンプレートです： ```markdown # AGENTS.md — Project: my-saas-app ## コードベース構造 - `src/app/` — Next.js App Router（ページ・レイアウト） - `src/components/` — 再利用可能UIコンポーネント - `src/lib/` — ユーティリティ・DB・バリデーション - `api/` — バックエンドAPIルート - `tests/` — Vitestテストファイル ## 開発環境 - Node.js 22.x - パッケージマネージャ: pnpm（npmは使用禁止） - テストフレームワーク: Vitest ## コマンド - 開発サーバー: `pnpm dev` - テスト: `pnpm test --run`（watch不可） - ビルド: `pnpm build` - Lint: `pnpm lint` ## コーディング規約 - TypeScript strict mode必須 - ESLint + Prettier設定に従う - 関数コンポーネントのみ（class component禁止） - カスタムフックは `use` プレフィックス必須 ## Git・PR規約 - Conventional Commits形式: `feat:`, `fix:`, `chore:`, `docs:` - ブランチ命名: `feat/issue-123-feature-name` - PRには必ずテストを含める ## セキュリティ（厳守） - `.env`, `.env.local`, `credentials/` は絶対に読み書きしない - APIキー・シークレットをコードにハードコードしない - `console.log` にセンシティブ情報を出力しない ## 禁止事項 - `package-lock.json` の生成（pnpmのみ） - `any` 型の使用（型安全性を保つ） - `// TODO` コメントを残してPRを出す ```

AGENTS.mdに加えて、`.codex/config.toml`でより詳細な動作設定が可能です。 ```toml # .codex/config.toml [agent] # タスク実行前に必ず実行するコマンド setup_commands = ["pnpm install", "pnpm build:types"] # タスク完了後の検証コマンド verify_commands = ["pnpm lint", "pnpm test --run"] # Codexが参照できるファイルパターン include_patterns = ["src/", "api/", "tests/**"] # 除外ファイル（セキュリティ） exclude_patterns = [".env*", "credentials/**", "*.pem"] [sandbox] # サンドボックスのメモリ上限（MB） memory_limit = 4096 # タイムアウト（秒） timeout = 1800 [pr] # PR作成時のデフォルトラベル default_labels = ["ai-generated", "needs-review"] # レビュー担当者の自動割り当て default_reviewers = ["@team-lead"] ```

MCP（Model Context Protocol）を使うと、CodexをFigma・Linear・Jira・GitHub・社内Wikiなどの外部サービスに接続できます。 MCP設定例（`~/.codex/mcp.json`） ```json { "servers": [ { "name": "github", "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, { "name": "linear", "type": "stdio", "command": "npx", "args": ["-y", "@linear/mcp-server"], "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" } }, { "name": "figma", "type": "sse", "url": "https://figma.com/mcp/sse" } ] } ```

2026年3月、Codexにプラグインエコシステムが導入されました。Skillsと呼ばれる再利用可能なタスクテンプレートを定義・共有できます。 Skillsの定義例（`.codex/skills/add-test.yaml`） ```yaml name: add-unit-test description: 指定ファイルのユニットテストを自動生成する parameters: - name: target_file type: string description: テスト対象のファイルパス prompt: | {{target_file}} のユニットテストを Vitest で作成してください。 - すべてのexport関数をカバー - エッジケース（null, undefined, 空配列）を含める - tests/ ディレクトリに配置 - 既存のテストスタイルに合わせる ``` 定義したSkillは `codex run skill add-unit-test --target_file src/lib/utils.ts` のように呼び出せます。チームでSkillsを共有することで、コーディングタスクを標準化できます。

Codexは`SessionStart`・`SessionStop`・`userpromptsubmit`などのフックポイントを提供します。 フック設定例（`.codex/hooks.toml`） ```toml [hooks.session_start] # セッション開始時に最新の依存関係をインストール command = "pnpm install --frozen-lockfile" timeout = 60 [hooks.session_stop] # セッション終了時にキャッシュをクリア command = "pnpm store prune" [hooks.before_commit] # コミット前にLint・テストを強制実行 command = "pnpm lint && pnpm test --run" fail_on_error = true ``` フックの主な活用シーン： ``` [タスク受信] ↓ SessionStart Hook → 環境初期化・依存関係更新 ↓ [Codex作業中] ↓ userpromptsubmit Hook → 入力バリデーション・ロギング ↓ [作業完了] ↓ before_commit Hook → Lint・テスト検証 ↓ SessionStop Hook → クリーンアップ ```

Codexの真の力は、GitHub Actionsと組み合わせることで発揮されます。Issue作成時に自動でCodexが対応するワークフローの例です。 ```yaml # .github/workflows/codex-auto-fix.yml name: Codex Auto Fix on: issues: types: [labeled] jobs: auto-fix: if: contains(github.event.label.name, 'codex-fix') runs-on: ubuntu-latest steps: - uses: openai/codex-action@v2 with: task: | Issue #${{ github.event.issue.number }} を解決してください。 タイトル: ${{ github.event.issue.title }} 内容: ${{ github.event.issue.body }} create_pr: true pr_labels: "ai-generated,needs-review" env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` このワークフローにより、`codex-fix`ラベルを付けたIssueはCodexが自動でPRを作成します。チームはレビューと承認だけに集中できます。

AGENTS.mdをチームで効果的に活用するためのベストプラクティスをまとめます。

AGENTS.mdの継続的改善フロー ``` [初期作成] ↓ [Codexでタスク実行] ↓ [期待通りでない動作を発見] ↓ [AGENTS.mdに指示を追加/修正] ↓ [PRでチームレビュー] ↓ [マージ → 再テスト] ↓ [継続的改善ループ] ``` 理想的なAGENTS.mdは「育てていくもの」です。最初は必要最小限の情報から始め、Codexが誤った判断をするたびに指示を追加していくことで、プロジェクト専用の高精度エージェントが完成します。

Q1. AGENTS.mdはどのくらいの長さが適切？ A. 500〜2,000文字が目安です。長すぎるとCodexが重要な指示を見落とす可能性があります。「Codexが毎回聞いてくること」だけを書くのが原則です。 Q2. AGENTS.mdとCLAUDE.md（Claude Code用）は書き方が同じ？ A. 基本構造は同じですが、ツール固有のコマンド名やオプション名が異なります。共通部分をベースファイルに抽出し、ツール固有部分だけ分けて管理すると効率的です。 Q3. MCPサーバーの認証情報はAGENTS.mdに書いていい？ A. 絶対に書いてはいけません。APIキーや認証情報は環境変数（`~/.codex/env`か`.env`）で管理し、AGENTS.mdには変数名の参照のみ記述してください。 Q4. サブディレクトリのAGENTS.mdはルートのものを完全に上書きする？ A. いいえ、合成されます。サブディレクトリの指示がルートの指示より優先されますが、競合しない指示は両方有効になります。 Q5. AGENTS.mdの効果を確認する方法は？ A. `codex explain --show-context` コマンドでCodexが読み込んでいる設定ファイルの一覧と内容を確認できます。意図した指示が正しく伝わっているか検証できます。 Q6. プラグイン（Skills）は社外に公開できる？ A. はい。Skills定義ファイル（`.yaml`）はnpmパッケージとして公開できます。オープンソースプロジェクトでのスタンダードSkillsの共有が活発になっています。

OflightはOpenAI Codexの導入から、AGENTS.md設計・MCP連携・GitHub Action統合・チームへの展開まで、実践的なAIコーディング環境の構築を支援しています。 「AGENTS.mdを書いてもCodexが期待通りに動かない」「MCP連携の設定が複雑でわからない」「チーム全体にCodexを展開したい」といったご相談はお気軽にどうぞ。貴社のプロジェクトに最適なAIエージェント環境を一緒に構築します。 → AIコンサルティングサービスの詳細はこちら