対象環境を極限まで最適化したい上級者

達成目標高度なconfig.toml・AGENTS.md・CI/CD統合を構築できる

前提知識章1-8の実践経験

所要時間 25分

プロフェッショナル環境構築

Codex環境を本格的に運用するための高度な設定パターンを網羅します。config.tomlのプロファイル設計からCI/CD統合、他ツールとの設定ファイル変換まで、プロダクション品質の開発環境を構築しましょう。

高度なconfig.toml設計

config.tomlはCodexの動作を制御する中核ファイルです。基本設定を超えた、プロファイル・モデル切替・Sandbox詳細設定・Web検索設定を解説します。

設定ファイルの配置場所

config.tomlは2つのレベルで配置でき、プロジェクト固有の設定がグローバル設定をオーバーライドします。

レベル	パス	用途
グローバル	`~/.codex/config.toml`	全プロジェクト共通のデフォルト設定
プロジェクト	`.codex/config.toml`	リポジトリ固有の設定（Gitにコミット可）

プロファイル活用

異なるタスクに応じて設定を切り替えるために、プロファイルを定義できます。

.codex/config.toml

# デフォルト設定
model = "o3"
approval_mode = "auto-edit"

# 高速処理プロファイル
[profiles.fast]
model = "o4-mini"
approval_mode = "full-auto"

# 慎重な作業用プロファイル
[profiles.careful]
model = "o3"
approval_mode = "suggest"

# レビュー特化プロファイル
[profiles.review]
model = "o3"
approval_mode = "suggest"

Terminal - プロファイル切替

# 高速モードで起動
codex --profile fast "このテスト修正して"

# 慎重モードで起動
codex --profile careful "このリファクタリングの影響範囲を確認して"

Sandbox詳細設定

Full Autoモードで使用するSandboxの動作を細かく制御できます。

.codex/config.toml

[sandbox]
# Sandbox種別: "seatbelt" (macOS) | "landlock" (Linux) | "docker"
type = "seatbelt"

# 書き込み許可ディレクトリ（デフォルト: ワークスペースのみ）
writable_dirs = [
  ".",
  "/tmp/codex-scratch"
]

# ネットワークアクセス（デフォルト: false）
allow_network = false

# 環境変数のパススルー
pass_env = ["NODE_ENV", "DATABASE_URL"]

Web Search設定

--search フラグ使用時のWeb検索動作をカスタマイズします。

.codex/config.toml

[web_search]
# 検索結果の最大件数
max_results = 10

# 検索ソースの優先順位
preferred_sources = ["docs", "stackoverflow", "github"]

# 検索言語
language = "ja"

✅ Tip

チーム共有の設定は .codex/config.toml にコミットし、個人的な好みは ~/.codex/config.toml で管理するのがベストプラクティスです。

AGENTS.mdの高度パターン

AGENTS.mdを戦略的に配置・構成することで、Codexの精度と安全性を大幅に向上させます。

階層化（ルート + サブディレクトリ）

モノレポや大規模プロジェクトでは、ディレクトリごとにAGENTS.mdを配置できます。サブディレクトリの設定はルートの設定を継承＋上書きします。

ディレクトリ構造

project/
  AGENTS.md                    # ルート：共通ルール
  frontend/
    AGENTS.md                  # フロントエンド固有ルール
  backend/
    AGENTS.md                  # バックエンド固有ルール
  infrastructure/
    AGENTS.md                  # インフラ固有ルール

frontend/AGENTS.md

# Frontend Rules

## Coding conventions
- React 19 + TypeScript strict mode
- Tailwind CSS v4のユーティリティクラスを使用
- コンポーネントは関数コンポーネントのみ

## Testing
- テスト: `pnpm test:frontend`
- E2E: `pnpm test:e2e`

## Boundaries
- バックエンドのコードは変更しない
- APIスキーマの変更は提案のみ行い、実装しない

AGENTS.override.md

個人用のオーバーライドファイルを .gitignore に追加して、チーム設定を壊さずに個人設定を適用できます。

.gitignore

AGENTS.override.md

AGENTS.override.md

# 個人設定（Gitにコミットしない）

## Preferences
- コメントは日本語で書く
- コミットメッセージは英語で書く
- console.logでのデバッグは避け、debuggerを使う

Boundaries（Always / Ask / Never）パターン

Codexの自律行動に明確な境界を設定します。これにより意図しない変更を防ぎ、安全性を確保します。

AGENTS.md - Boundaries

## Boundaries

### Always（常に実行）
- テスト実行後にカバレッジレポートを確認
- 新規ファイル作成時にLintを実行
- コミット前に型チェックをパス

### Ask（確認して実行）
- データベースマイグレーションの作成
- パッケージの追加・削除
- API公開エンドポイントの変更

### Never（絶対に実行しない）
- 本番環境への直接デプロイ
- .envファイルの変更
- セキュリティ関連設定の自動変更
- node_modulesの直接編集

Lessons Learned蓄積

プロジェクト固有の「学び」をAGENTS.mdに蓄積し、同じミスを繰り返さないようにします。

AGENTS.md - Lessons Learned

## Lessons Learned

### 2025-06
- Prismaのマイグレーションは `prisma migrate dev` の前に必ず `prisma generate` を実行
- Next.js App Routerでは `use client` ディレクティブの付け忘れに注意
- テストでのmockはvi.mockではなくvi.spyOnを優先する

### 2025-07
- Docker Composeのvolumesパスは相対パスで統一
- CI/CDでのNode.jsバージョンは `.nvmrc` に従う

📝 Note

Lessons Learnedセクションは定期的にレビューし、古くなった情報は削除またはアーカイブしましょう。肥大化するとCodexのコンテキスト消費が増えます。

CI/CD統合

CodexをCI/CDパイプラインに組み込むことで、PR自動作成やテスト自動実行など、開発ワークフローを大幅に自動化できます。

GitHub ActionsとCodexの連携

GitHub Actionsのワークフロー内でCodex CLIを実行し、自動的にコード修正やPR作成を行います。

.github/workflows/codex-autofix.yml

name: Codex Auto-Fix
on:
  issues:
    types: [opened, labeled]

jobs:
  autofix:
    if: contains(github.event.issue.labels.*.name, 'codex')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Codex CLI
        run: npm i -g @openai/codex

      - name: Run Codex
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --approval-mode full-auto \
            --quiet \
            "Fix the issue: ${{ github.event.issue.title }}"

      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          title: "fix: ${{ github.event.issue.title }}"
          body: "Automated fix by Codex for #${{ github.event.issue.number }}"
          branch: "codex/fix-${{ github.event.issue.number }}"

PR自動作成パイプライン

Issueにラベルを付けるだけで、Codexが自動的にコードを修正し、PRを作成するパイプラインです。

Issue作成・ラベル付与

GitHubでIssueを作成し、codex ラベルを付けます。Issueのタイトルと本文がCodexへのプロンプトになります。

GitHub Actions起動

ラベル検知でワークフローが自動起動。Codex CLIがFull Autoモードでリポジトリを分析し、コード変更を実行します。

PR自動作成・レビュー

変更をブランチにpushし、PRを自動作成。Issueへのリンクが含まれるので、レビュー後にマージするだけで完了します。

テスト自動実行

PRが作成された際に、Codexでテストを自動生成・実行するワークフローも構築できます。

.github/workflows/codex-test.yml

name: Codex Test Generation
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - name: Install Codex CLI
        run: npm i -g @openai/codex

      - name: Generate missing tests
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --approval-mode full-auto \
            "変更されたファイルに対するユニットテストを追加して。既存テストがある場合はスキップ"

      - name: Run tests
        run: npm test

⚠️ Warning

CI/CDでCodexを使う場合は、API使用量に注意してください。大規模リポジトリでの自動実行はトークン消費が大きくなります。--model o4-mini でコストを抑えることも検討しましょう。

開発環境テンプレート

プロジェクト種類別のAGENTS.md + config.tomlテンプレートを用意しました。コピーして使えます。

Webアプリ（Next.js）

AGENTS.md - Webアプリ

# AGENTS.md - Next.js Web Application

## Repository expectations
- Next.js 15 (App Router) + TypeScript + Tailwind CSS
- パッケージマネージャ: pnpm
- ORM: Prisma
- テスト: Vitest + Playwright

## Build commands
- dev: `pnpm dev`
- build: `pnpm build`
- test: `pnpm test`
- lint: `pnpm lint`
- typecheck: `pnpm typecheck`
- e2e: `pnpm test:e2e`

## Coding conventions
- Server Components をデフォルトにし、必要な場合のみ 'use client'
- API Routes は src/app/api/ 配下に配置
- Zod でバリデーション
- エラーハンドリングは Result パターン

## Boundaries
### Never
- .env* ファイルの変更
- prisma/migrations/ の手動編集
- next.config.js のセキュリティ設定変更

APIサーバー（Express / Hono）

AGENTS.md - APIサーバー

# AGENTS.md - API Server

## Repository expectations
- Hono + TypeScript
- Runtime: Node.js 22 / Bun
- DB: PostgreSQL (Drizzle ORM)
- テスト: Vitest

## Build commands
- dev: `bun run dev`
- build: `bun run build`
- test: `bun test`
- migrate: `bun run db:migrate`

## Coding conventions
- レスポンスは必ずスキーマ定義に従う
- エラーは RFC 7807 Problem Details 形式
- 認証ミドルウェアは全APIルートに適用
- ロギングは構造化ログ（JSON形式）

## Boundaries
### Ask
- 新規テーブルの作成
- 認証・認可ロジックの変更
### Never
- 本番DBへの直接接続
- シークレットのハードコード

ライブラリ / パッケージ

AGENTS.md - ライブラリ

# AGENTS.md - Library / Package

## Repository expectations
- TypeScript ライブラリ
- ビルド: tsup (CJS + ESM dual)
- テスト: Vitest
- ドキュメント: TypeDoc

## Build commands
- build: `pnpm build`
- test: `pnpm test`
- lint: `pnpm lint`
- docs: `pnpm docs`

## Coding conventions
- すべての公開APIにJSDocコメント必須
- Breaking Changeは CHANGELOG.md に記録
- セマンティックバージョニング厳守
- tree-shakable な export 設計

## Boundaries
### Always
- 公開関数の変更時にはテスト追加
- README.mdのAPI仕様を更新
### Never
- peerDependenciesの暗黙的な変更
- バンドルサイズを20%以上増加させる変更

✅ Tip

テンプレートはあくまで出発点です。プロジェクト固有の要件を追加し、Lessons Learnedを蓄積していくことで、Codexの精度は継続的に向上します。

Claude Code / Copilotとの設定ファイル変換

既に別のAIコーディングツールを使っている場合、設定ファイルを相互変換してスムーズに移行できます。

CLAUDE.md ↔ AGENTS.md 変換

Claude CodeのCLAUDE.mdとCodexのAGENTS.mdは構造が似ていますが、いくつかの違いがあります。

CLAUDE.md	AGENTS.md	備考
`## Project Overview`	`## Repository expectations`	プロジェクト概要
`## Common Commands`	`## Build commands`	ビルド・テスト手順
`## Architecture`	`## Coding conventions`	アーキテクチャ方針
（なし）	`## Boundaries`	Codex固有：行動制約
`## Important Notes`	`## Lessons Learned`	過去の学び

変換コマンド例（Codexで自動変換）

codex "CLAUDE.mdの内容をAGENTS.md形式に変換して。Boundariesセクションも追加して"

settings.json ↔ config.toml 変換

Claude Codeの .claude/settings.json とCodexの .codex/config.toml のマッピングです。

Claude Code (settings.json)	Codex (config.toml)
`"model": "claude-sonnet-4-20250514"`	`model = "o3"`
`"permissions": {...}`	`approval_mode = "auto-edit"`
`"allowedTools": [...]`	`[sandbox] writable_dirs = [...]`

GitHub Copilotとの共存

Copilotの .github/copilot-instructions.md とAGENTS.mdは同時に配置できます。両方のツールが共存する環境では、共通ルールを抽出して参照するのが効率的です。

共通ルールの参照パターン

# .github/copilot-instructions.md
# See AGENTS.md for full coding conventions

Follow the coding conventions defined in AGENTS.md at the repository root.
Additional Copilot-specific rules:
- Suggest imports from @/ alias
- Prefer named exports over default exports

📝 Note

複数のAIツールを併用する場合は、AGENTS.mdを「Single Source of Truth」として扱い、他ツールの設定からAGENTS.mdを参照する形にすると管理が楽になります。

← 前のページ

落とし穴

上級テクニック集