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

# 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を出す

# .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"]

{
  "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"
    }
  ]
}

name: add-unit-test
description: 指定ファイルのユニットテストを自動生成する
parameters:
  - name: target_file
    type: string
    description: テスト対象のファイルパス
prompt: |
  {{target_file}} のユニットテストを Vitest で作成してください。
  - すべてのexport関数をカバー
  - エッジケース（null, undefined, 空配列）を含める
  - tests/ ディレクトリに配置
  - 既存のテストスタイルに合わせる

[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 → クリーンアップ

# .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でタスク実行]
    ↓
[期待通りでない動作を発見]
    ↓
[AGENTS.mdに指示を追加/修正]
    ↓
[PRでチームレビュー]
    ↓
[マージ → 再テスト]
    ↓
[継続的改善ループ]