対象全レベルの開発者

達成目標よくある失敗パターンを事前に回避できる

前提知識なし

所要時間 10分

よくある落とし穴

Codexの導入・運用でよく見られる失敗パターンとその対策。症状・原因・対策の3点セットで、同じ過ちを繰り返さないための実践ガイドです。

プロンプトにルール詰め込み

症状

毎回のプロンプトにコーディング規約、テスト要件、アーキテクチャルールなどを長文で記述してしまう。プロンプトが数百行に膨らみ、本来のタスク指示が埋もれる。

原因

AGENTS.mdやSkillsの存在を知らない、または活用していない。すべてのコンテキストをプロンプトで毎回渡そうとしている。

対策

永続的なルールはAGENTS.mdに、再利用可能な手順はSkillsに移動する。プロンプトには「今回のタスク」だけを書く。

悪い例: プロンプトにすべて詰め込み

# 毎回これを書いている...
"TypeScriptで書いて、strictモードで、ESLintルールに従って、
テストはVitestで書いて、カバレッジ80%以上にして、
コンポーネントはPascalCaseで、変数はcamelCaseで、
インデントは2スペースで... あとログインバグを直して"

良い例: ルールはAGENTS.mdに

# AGENTS.md にルールを記載済み
# プロンプトはタスクだけ
"ログイン画面のメールバリデーションバグを修正して"

エージェントに検証手段がない

症状

Codexがコードを生成するが、ビルドエラーやテスト失敗に気づかず、壊れたコードを提出してくる。

原因

AGENTS.mdにビルドコマンドやテストコマンドが記載されていない。Codexは検証手段を知らないため、生成したコードの正しさを確認できない。

対策

AGENTS.mdにビルド・テスト・Lintコマンドを明記する。Codexは自動的にこれらを使って自己検証を行う。

AGENTS.md に検証コマンドを追加

## Verification commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

## Rules
- コード変更後は必ず `pnpm build` と `pnpm test` を実行して確認すること
- テストが失敗する変更はコミットしないこと

✅ Tip

「変更後は必ずテストを実行して確認すること」とAGENTS.mdに明記するだけで、Codexの出力品質が劇的に向上します。検証手段を与えることは、最もコストパフォーマンスの高い改善策です。

ステップごとに監視

症状

Codexの各ステップを逐一確認し、一つひとつ承認している。結果として、手動で作業するのと変わらない速度になっている。

原因

Suggestモードのまま使い続けている。AIに任せることへの不安から、過度に監視してしまう。

対策

信頼できるタスクはAuto EditまたはFull Autoに切り替える。並列作業を活用し、Codexがタスクを実行している間に自分の仕事を進める。

低リスクタスク（テスト追加、ドキュメント更新、Lint修正）→ Full Auto
中リスクタスク（バグ修正、リファクタリング）→ Auto Edit
高リスクタスク（認証ロジック、決済処理、データ移行）→ Suggest

📝 Note

Codexを「もう一人のチームメイト」として扱いましょう。ペアプログラミングのように横で見張るのではなく、タスクを任せて自分は別の仕事に取り組む方が、全体の生産性は高くなります。

ネットワークブロック

症状

npm install や pip install が失敗する。外部APIへのリクエストがタイムアウトする。「ネットワークに接続できません」というエラーが頻発する。

原因

サンドボックスのデフォルト設定でネットワークアクセスが無効化されている。Full Autoモードではデフォルトでインターネット接続がブロックされる。

対策

必要なネットワークアクセスをconfig.tomlで明示的に許可する。または、パッケージインストールは事前に済ませておく。

.codex/config.toml

# ネットワークアクセスを許可するドメインを指定
[sandbox]
allow_network = [
  "registry.npmjs.org",
  "api.github.com"
]

⚠️ Warning

ネットワークアクセスの許可は最小限にとどめましょう。すべてのネットワーク通信を許可するのではなく、必要なドメインだけをホワイトリストに追加してください。

承認モードの混乱

症状

3つの承認モード（Suggest / Auto Edit / Full Auto）の違いが分からず、常に同じモードを使っている。または、状況に合わないモードを選択してしまう。

原因

各モードの権限範囲と適切なユースケースを理解していない。

対策

以下の基準で使い分ける。タスクのリスクレベルに応じて適切なモードを選択する。

モード	ファイル編集	コマンド実行	適切なタスク
Suggest	毎回承認	毎回承認	初めてのリポジトリ、セキュリティ関連、学習目的
Auto Edit	自動	毎回承認	日常的なコーディング、バグ修正、リファクタリング
Full Auto	自動	自動	テスト追加、定型作業、信頼度の高いタスク

AGENTS.mdスコープ不足

症状

プロジェクトルートに巨大なAGENTS.mdが1つだけあり、すべてのルールが混在している。フロントエンドのルールがバックエンドの作業時にも読み込まれ、コンテキストが無駄に膨らむ。

原因

AGENTS.mdの階層的スコープ機能を活用していない。単一ファイルにすべてを詰め込んでいる。

対策

ディレクトリごとにAGENTS.mdを配置し、階層的にスコープする。各ディレクトリのAGENTS.mdには、そのディレクトリに関連するルールだけを記述する。

階層的AGENTS.mdの配置

project-root/
  AGENTS.md              # 全体共通: 言語、パッケージマネージャ、基本規約
  src/
    frontend/
      AGENTS.md          # フロントエンド固有: React規約、コンポーネント設計
    backend/
      AGENTS.md          # バックエンド固有: API設計、DB操作規約
    shared/
      AGENTS.md          # 共有コード: 型定義、ユーティリティの規約
  tests/
    AGENTS.md            # テスト固有: テストフレームワーク、モック戦略

Codexは作業対象ファイルの位置から上位ディレクトリを辿り、すべてのAGENTS.mdをマージして適用します。これにより、フロントエンドのファイルを編集する際はフロントエンド固有のルールが自動的に適用されます。

症状

Codexが生成したコードをレビューせずにそのままマージしている。セキュリティ脆弱性やロジックエラーが本番に紛れ込む。

原因

AIの出力を「正しい」と過信している。Full Autoモードの利便性から、レビュープロセスを省略してしまう。

対策

特に以下の領域では、必ず人間によるレビューを行う。

認証・認可 — トークン検証、権限チェック、セッション管理
データ検証 — 入力サニタイズ、SQLインジェクション対策、XSS対策
暗号化 — パスワードハッシュ、暗号アルゴリズム選択、鍵管理
外部通信 — APIキーの扱い、CORS設定、Rate Limiting
データ削除 — 物理削除と論理削除の判断、カスケード削除

⚠️ Warning

AIが生成したコードは「優秀なジュニアエンジニアが書いたコード」と同じレベルで扱いましょう。動作することは多いですが、セキュリティやエッジケースの考慮が不十分な場合があります。必ずシニアエンジニアの目でレビューしてください。

まとめ

Codexを効果的に活用するための5つの成功原則をまとめます。

コンテキストを構造化する

AGENTS.mdにプロジェクトルール、Skillsに再利用手順を配置。プロンプトはタスク指示のみにする。

検証手段を提供する

ビルド・テスト・Lintコマンドを明記し、Codexが自己検証できる環境を作る。

タスクを適切に分割する

1スレッド1タスクの原則を守り、具体的で範囲が限定されたタスクを割り当てる。

リスクに応じて信頼する

承認モードをタスクのリスクレベルに合わせて使い分け、低リスクは任せて高リスクは監視する。

セキュリティは必ずレビューする

AIの出力を盲信せず、特に認証・データ・暗号化に関わるコードは人間の目で確認する。